Alpaca 10.1

Alpaca Upgrade

This is an upgrade guide for an existing Alpaca installation.

Assumptions

  • An existing installation of Alpaca.
  • Credentials to access the Alpaca server as root.
  • Working knowledge of ssh and a file transfer tool such as scp.
  • Understanding of alpacactl for Alpaca 9.2+.

Guide

The guide is split into sections based on the server or machine that the operations should be performed. It is also in chronological order. Performing the steps from top to bottom is the desired procedure.

Local Work Station

Alpaca Server

General Upgrade Process

These are the general steps for upgrading Alpaca Server. Please check caveats for specific instructions for the version that you are upgrading to.

  • Step: A-1
  • Commands:
    1. Turn off the existing Alpaca service.
      • < 9.2 - # service alpaca stop
      • >= Alpaca 9.2 - # alpacactl stop
    2. Perform RPM upgrade
      • rpm -U alpaca-ALPACA_VERSION_1.x86_64.rpm
    3. Restart Alpaca service.
      • < 9.2 - # service alpaca start
      • >= Alpaca 9.2 - # alpacactl start

Caveats

Upgrading to 10.0.0
  • MongoDB 4.4 is now required.
Upgrading to 9.3.0 from any 9.2.x version
  • If not upgrading from pre 9.2.0, an incremental upgrade to the latest 9.2.x version is required.
  • Once upgraded to 9.2.x, shut down alpaca (alpacactl stop) and then upgrade to the latest version of Java17.
    • Java distributions from Oracle, OpenJdk, or Amazon (Corretto) are all acceptable for Alpaca.
  • Once Java is upgraded, proceed with upgrading to Alpaca 9.3.0.
    • rpm -U alpaca-<var>ALPACA_VERSION</var>\_1.x86_64.rpm
    • alpacactl start
Upgrading to 9.2.0 from any 9.x version
  • Note: For commands that use yum, depending on your OS and setup, you may need to replace yum with dnf.
  • All Alpaca components (Eureka, Gateway, and all version of the Server) are now packaged together in one RPM.
  • Upgrading to 9.2.0 requires uninstalling all previous Alpaca components and then installing the new single RPM.
  • Steps:
    • Stop all components
    • Commands:
      1. # service alpaca-server stop
      2. # service alpaca-gateway stop
      3. # service alpaca-eureka stop
    • Back up the following files/directories
    • Eureka
      • All files/directories in /etc/alpaca/eureka
    • Gateway
      • All files/directories in /etc/alpaca/gateway
    • Server
      • All files/directories in /etc/alpaca/server
      • License file in /opt/alpaca
      • Any plugins in /opt/alpaca/plugins
      • Any custom branding files in /opt/alpaca/static
    • Uninstall individual components
    • Commands:
      1. # yum remove -y alpaca-server-BROADWORKS_RELEASE.x86_64
      2. # yum remove -y alpaca-gateway-BROADWORKS_RELEASE.x86_64
      3. # yum remove -y alpaca-eureka-BROADWORKS_RELEASE.x86_64
    • Install Alpaca - Commands:
    • # cd /tmp
    • # yum -y install alpaca-ALPACA_VERSION.x86_64.rpm
    • Replace license and any configurations
      • Note that the server is no longer installed in /opt/alpaca. Three versions are now installed at /opt/alpaca-server-22, /opt/alpaca-server-23, and /opt/alpaca-server-24. The license file will need to be placed in the directory of each version that you plan to use. - All custom branding will need to be placed in the static/ directory of each version that you plan to use. - All non-versioned plugins will need to be placed in the plugins/ directory of each version that you plan to use.
      • All versioned plugins will need to be placed in the plugins/ directory of the corresponding Alpaca server.
      • Configure Alpaca according to the configuration guide.
        • You should already have configurations backed-up, use these as a reference.
      • Note that there is a new start-up configuration (/etc/sysconfig/alpaca_config) that replaced the individual start up configurations that were in /opt/alpaca/configuration , /opt/alpaca-eureka/configuration, and /opt/alpaca-gateway/configuration.
    • Configure Version(s)
      • By default, all version of Alpaca are enabled (R22, R23, and R24).
      • If you wish for a version to not run, you can simply use chkconfig to turn it off.
        • # chkconfig alpaca-server-{22|23|24} off
      • To re-enable a version, use the following command:
        • # chkconfig alpaca-server-{22|23|24} on
    • Start Alpaca
      • Commands:
        • # alpacactl start
      • Note that individual components can be stopped, started, restarted, or status checked by using:
        • # alpacactl {start|stop|restart|status} {eureka|gateway|server-22|server-23|server-24}
        • See the alpacactl guide.
Upgrading to 9.1.0 from any previous version
  • The default Alpaca store location has been moved from /tmp/alpacastore to /var/alpaca/store. If your Alpaca installation includes a configuration for alpaca.file-store.location, this new default will not overwrite that. This change will only affect users who did not specify an Alpaca store location and are using the default. For those who used the default directory, you will need to manually move the contents of /tmp/alpacastore to /var/alpaca/store.
  • The following configurations have been removed: alpaca.file-store.cleanup-interval and alpaca.task.retention-period-days. They have been replaced with alpaca.file-store.temp-file-retention-period-days, alpaca.file-store.task-file-retention-period-months and alpaca.file-store.report-file-retention-period-months.
Upgrading to 9.0.0 from any previous version.
  • RabbitMQ is a required part of the Alpaca system for version 9.0.0 and following. Please follow the installation guide to complete the RabbitMQ installation.
  • There is additional configuration required for connection to Eureka, RabbitMQ, and the optional Amazon S3 bucket support. Please follow the configuration guide and update the /etc/alpaca/server/config/application-prod.yml file accordingly.
  • Note that upgrading to Alpaca 9.0.0 will remove any Recurring (scheduled) Tasks that are configured.
  • Please note that in the application-https.yml that the ECDHE_RSA_WITH_AES_256_CBC_SHA384 cipher has been renamed TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384. This means that if the https configuration is moved from the Server to the Gatway that the cipher needs to be renamed.
  • Note that if using a Highly Available Clustering setup (HA), the SSL configuration has been moved from the Alpaca Server configuration to the Alpaca Gateway configuration.
Upgrading to 8.1.0 from any previous version.
  • In 8.1.0 the configuration that was previously uc-one is now cisco-soft-client. Property files that contain the old uc-one tag will need to be updated.
Upgrading from 7.2.X or earlier to 8.0.0 or higher

  • If running Alpaca 7.2.0 or earlier, an incremental upgrade to Alpaca 7.2.1 is required before upgrading to 8.0.0 or higher. After the update to 7.2.1, shut off Alpaca, and then upgrade to Java11 before upgrading to Alpaca 8.0.0 or higher.

  • If using an existing /plugins directory for Alpaca. This directory will need to be backed up manually and the plugins re-added to the Alpaca plugins directory.

Upgrading from 7.0.4 or earlier to 7.1.0 or higher
  • Back up all configuration files in /opt/alpaca/config/.
  • After upgrade, configuration files will be located in /etc/alpaca/<ALPACA_PACKAGE>/config/.
    • The backed up configurations files will need to be copied here.
  • After upgrade, log files will be located in /var/log/alpaca/.
Upgrading from 6.6.6 or earlier to 7.0.0 or higher
  • If running Alpaca 6.6.6 or earlier, an incremental upgrade to Alpaca 6.6.7 is required before upgrading to 7.0.0 or higher.
Upgrading from version 6.6.0 or later.
  • Step: A-1
  • Commands:
    1. # cd /tmp
    2. # rpm -U alpaca-server-21sp1-8.0.3-SNAPSHOT_1.x86_64.rpm
Upgrading from version 6.5.3 or earlier.
  • Step: A-1
  • Commands:
    1. Turn off the existing Alpaca service.
      • # service alpaca stop
    2. Remove the Alpaca service script.
      • # rm /etc/init.d/alpaca
    3. Remove the Alpaca symlink in the "/opt" directory if it exists.
      • # rm /opt/alpaca
    4. Install the Alpaca Server RPM
      • # yum install -y alpaca-server-ALPACA_VERSION.x86_64.rpm

Alpaca Eureka

General Upgrade Process

These are the general steps for upgrading Alpaca Eureka.

  • Step: A-1
  • Commands:
    1. Turn off the existing Alpaca Eureka service.
      • # service alpaca-eureka stop
    2. Perform RPM upgrade
      • rpm -U alpaca-eureka-ALPACA_VERSION_1.x86_64.rpm
    3. Restart Alpaca service.
      • # service alpaca-eureka start

Alpaca Gateway

General Upgrade Process

These are the general steps for upgrading Alpaca Gateway.

  • Step: A-1
  • Commands:
    1. Turn off the existing Alpaca Gateway service.
      • # service alpaca-gateway stop
    2. Perform RPM upgrade
      • rpm -U alpaca-gateway-ALPACA_VERSION_1.x86_64.rpm
    3. Restart Alpaca service.
      • # service alpaca-gateway start