Upgrade Swarm

The section describes how to upgrade a Swarm package install to a newer release.

Swarm upgrade process:

• If you installed Swarm via a package, see Upgrade a Swarm package installation for details.
• If you installed Swarm via an OVA (Swarm 2014.2 or later), see Upgrade a Swarm package installation for details.
• If you installed Swarm via an OVA (Swarm 2014.1 or earlier), see Upgrade a Swarm OVA installation from Swarm 2014.1 or earlier for details
• If you installed Swarm via a source distribution archive (tar file), see Upgrade a Swarm tarball installation for details.

Upgrade a Swarm package installation

Before you begin your Swarm upgrade

The Swarm Workflow feature was introduced in Swarm 2018.2 and was disabled by default, this feature is now enabled by default for Swarm 2019.2 and later.

If you are not currently using the Swarm workflow feature and you are using the strict and enforce triggers to control commits you have the following options:

• Use the Swarm workflow feature: you must comment out your strict and enforce triggers and use the new workflow triggers.
Note
Known limitations of the Swarm workflow feature:
• EXEMPT_FILE_COUNT: When set to a positive integer, commits with a file count greater or equal to this value are exempt from enforce or strict verifications.
• EXEMPT_EXTENSIONS: A comma separated list of file extension. Commits with files having only these extensions are exempt from enforce or strict verifications.

• Continue to use the strict and enforce triggers: keep your existing enforce and strict triggers and Disable the Workflow feature. Support for these triggers will be dropped in a later release.

  Tip

  If you disable the workflow feature in the Swarm config.php file, workflow will not be processed by Swarm but a small overhead is still incurred by the Helix server each time it runs a workflow trigger script. This overhead can be eliminated by commenting out the swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit workflow triggers.

Decide whether you want to use the workflow feature before you start your upgrade because this will determine which triggers you need to use. The trigger requirements are described in more detail in the Update your triggers stage of the Swarm upgrade.

Upgrade Swarm

The following process attempts to minimize downtime, but a short period of downtime for Swarm users is unavoidable. There should be no downtime for your Helix server. After a successful upgrade, all Swarm users are logged out.

If you are using Swarm in a production environment, we encourage you to test this upgrade process in a non-production environment first.

1. Follow the instructions for your OS distribution:
Ubuntu:

$ sudo apt-get update
$ sudo apt-get install helix-swarm helix-swarm-triggers helix-swarm-optional

CentOS 6 (run these commands as root):

Important

• As part of the PHP upgrade process your Apache 2.2 server will be stopped and disabled, if you are currently using the Apache 2.2 server for any other applications they will stop working. You will either need to upgrade these applications to work with PHP 7 and Apache 2.4 or move them to another server.

• If Apache 2.4 has been installed from the SCL or RHSCL packages, the Apache configuration files are installed into /opt/rh/httpd24/root/etc rather than their normal locations in /etc. This means that the usual service, systemctl, and apachectl commands will control the wrong server. To control the version of Apache used by Swarm, use one of the following:

  • For CentOS/RHEL 6 to use System V scripts: service httpd24-httpd restart
  • For CentOS/RHEL 7 to use systemd scripts: systemctl restart httpd24-httpd

  The apachectl command still exists, but must be run in the /opt/rh/httpd24 environment. Because of this we recommended that you use one of the above commands instead.

• To avoid seeing the Apache HTTP server Linux test page when you start the Apache server, comment out the content of the welcome.conf file located in the /opt/rh/httpd24/root/etc/httpd/conf.d/ directory.

The full upgrade process described below is only required the first time you upgrade to PHP 7, for future Swarm upgrades just run step b.

The upgrade process will deploy centos-release-scl which gives Swarm access to PHP 7.x and Apache 2.4, upgrade Swarm, stop and disable the Apache 2.2 server, copy and edit Swarm files so they work with Apache 2.4, and finally start and enable the Apache 2.4 server.

1. Deploy the centos-release-scl repository to give Swarm access to PHP 7:

$ yum -y install centos-release-scl

Tip

If you don't deploy the centos-release-scl repository you will see an error similar to the one shown below when you do the next step:



2. Run the Swarm upgrade, this will automatically install PHP 7.x and Apache 2.4:

$ yum install helix-swarm helix-swarm-triggers helix-swarm-optional

3. Disable your Apache 2.2 HTTP server so that is does not automatically start:

$ chkconfig httpd off

4. Stop your Apache 2.2 HTTP server:

$ service httpd stop

5. If you have any special php.ini configuration options set, copy the php.ini file to the /etc/opt/rh/rh-php70/php.d/ directory:

$ cp /etc/php.d/php.ini /etc/opt/rh/rh-php70/php.d/php.ini

6. Copy the perforce-swarm-site.conf file to the /opt/rh/httpd24/root/etc/httpd/conf.d/ directory:

$ cp /etc/httpd/conf.d/perforce-swarm-site.conf /opt/rh/httpd24/root/etc/httpd/conf.d/perforce-swarm-site.conf

7. Replace the /log/httpd/ filepath with /log/httpd24 in the perforce-swarm-site.conf file using the sed command:

$ sed -i "s#/log/httpd/#/log/httpd24/#g" /opt/rh/httpd24/root/etc/httpd/conf.d/perforce-swarm-site.conf

8. Update the permissions for Apache 2.4 by replacing Order allow,deny references with Require all granted in the perforce-swarm-site.conf file using the sed command:

$ sed -i "s/Order allow,deny/Require all granted/g" /opt/rh/httpd24/root/etc/httpd/conf.d/perforce-swarm-site.conf

9. Enable your Apache 2.4 HTTP server so that it automatically starts:

$ chkconfig httpd24-httpd on

10. Start the Apache 2.4 HTTP server:

$ service httpd24-httpd start

RHEL 6 (run these commands as root):

Important

• As part of the PHP upgrade process your Apache 2.2 server will be stopped and disabled, if you are currently using the Apache 2.2 server for any other applications they will stop working. You will either need to upgrade these applications to work with PHP 7 and Apache 2.4 or move them to another server.

• If Apache 2.4 has been installed from the SCL or RHSCL packages, the Apache configuration files are installed into /opt/rh/httpd24/root/etc rather than their normal locations in /etc. This means that the usual service, systemctl, and apachectl commands will control the wrong server. To control the version of Apache used by Swarm, use one of the following:

  • For CentOS/RHEL 6 to use System V scripts: service httpd24-httpd restart
  • For CentOS/RHEL 7 to use systemd scripts: systemctl restart httpd24-httpd

  The apachectl command still exists, but must be run in the /opt/rh/httpd24 environment. Because of this we recommended that you use one of the above commands instead.

• To avoid seeing the Apache HTTP server Linux test page when you start the Apache server, comment out the content of the welcome.conf file located in the /opt/rh/httpd24/root/etc/httpd/conf.d/ directory.

The full upgrade process described below is only required the first time you upgrade to PHP 7, for future Swarm upgrades just run step b.

The upgrade process will enable rhel-server-rhscl-6-eus-rpms which gives Swarm access to PHP 7.x and Apache 2.4, upgrade Swarm, stop and disable the Apache 2.2 server, copy and edit Swarm files so they work with Apache 2.4, and finally start and enable the Apache 2.4 server.

1. Enable the rhel-server-rhscl-6-eus-rpms repository to give Swarm access to PHP 7:

# subscription-manager repos --enable rhel-server-rhscl-6-eus-rpms

Tip

If you don't enable the rhel-server-rhscl-6-eus-rpms repository you will see an error similar to the one shown below when you do the next step:

Error: Package: helix-swarm-2019.2-1845646.el6.x86_64 (perforce)
        Requires: rh-php70

2. Run the Swarm upgrade, this will automatically install PHP 7.x and Apache 2.4:

$ yum install helix-swarm helix-swarm-triggers helix-swarm-optional

3. Disable your Apache 2.2 HTTP server so that is does not automatically start:

$ chkconfig httpd off

4. Stop your Apache 2.2 HTTP server:

$ service httpd stop

5. If you have any special php.ini configuration options set, copy the php.ini file to the /etc/opt/rh/rh-php70/php.d/ directory:

$ cp /etc/php.d/php.ini /etc/opt/rh/rh-php70/php.d/php.ini

6. Copy the perforce-swarm-site.conf file to the /opt/rh/httpd24/root/etc/httpd/conf.d/ directory:

$ cp /etc/httpd/conf.d/perforce-swarm-site.conf /opt/rh/httpd24/root/etc/httpd/conf.d/perforce-swarm-site.conf

7. Replace the /log/httpd/ filepath with /log/httpd24 in the perforce-swarm-site.conf file using the sed command:

$ sed -i "s#/log/httpd/#/log/httpd24/#g" /opt/rh/httpd24/root/etc/httpd/conf.d/perforce-swarm-site.conf

8. Update the permissions for Apache 2.4 by replacing Order allow,deny references with Require all granted in the perforce-swarm-site.conf file using the sed command:

$ sed -i "s/Order allow,deny/Require all granted/g" /opt/rh/httpd24/root/etc/httpd/conf.d/perforce-swarm-site.conf

9. Enable your Apache 2.4 HTTP server so that it automatically starts:

$ chkconfig httpd24-httpd on

10. Start the Apache 2.4 HTTP server:

$ service httpd24-httpd start

CentOS 7 (run these commands as root):
Important
• As part of the PHP upgrade process your Apache 2.2 server will be stopped and disabled, if you are currently using the Apache 2.2 server for any other applications they will stop working. You will either need to upgrade these applications to work with PHP 7 and Apache 2.4 or move them to another server.

• If Apache 2.4 has been installed from the SCL or RHSCL packages, the Apache configuration files are installed into /opt/rh/httpd24/root/etc rather than their normal locations in /etc. This means that the usual service, systemctl, and apachectl commands will control the wrong server. To control the version of Apache used by Swarm, use one of the following:

  • For CentOS/RHEL 6 to use System V scripts: service httpd24-httpd restart
  • For CentOS/RHEL 7 to use systemd scripts: systemctl restart httpd24-httpd

  The apachectl command still exists, but must be run in the /opt/rh/httpd24 environment. Because of this we recommended that you use one of the above commands instead.

• To avoid seeing the Apache HTTP server Linux test page when you start the Apache server, comment out the content of the welcome.conf file located in the /opt/rh/httpd24/root/etc/httpd/conf.d/ directory.
The full upgrade process described below is only required the first time you upgrade to PHP 7, for future Swarm upgrades just run step b.
The upgrade process will deploy centos-release-scl which gives Swarm access to PHP 7.x and Apache 2.4, upgrade Swarm, stop and disable the Apache 2.2 server, copy and edit some Swarm files so they work with Apache 2.4, and finally start and enable the Apache 2.4 server.
1. Deploy the centos-release-scl repository to give Swarm access to PHP 7:

$ yum -y install centos-release-scl

Tip

If you don't deploy the centos-release-scl repository you will see an error similar to the one shown below when you do the next step:



2. Run the Swarm upgrade, this will automatically install PHP 7.x and Apache 2.4:

$ yum install helix-swarm helix-swarm-triggers helix-swarm-optional

3. Disable your Apache 2.2 HTTP server so that is does not automatically start:

$ systemctl disable httpd

4. Stop your Apache 2.2 HTTP server:

$ systemctl stop httpd

5. If you have any special php.ini configuration options set, copy the php.ini file to the /etc/opt/rh/rh-php71/php.d/ directory:

$ cp /etc/php.d/php.ini /etc/opt/rh/rh-php71/php.d/php.ini

6. Copy the perforce-swarm-site.conf file to the /opt/rh/httpd24/root/etc/httpd/conf.d/ directory:

$ cp /etc/httpd/conf.d/perforce-swarm-site.conf /opt/rh/httpd24/root/etc/httpd/conf.d/perforce-swarm-site.conf

7. Replace the /log/httpd/ filepath with /log/httpd24 in the perforce-swarm-site.conf file using the sed command:

$ sed -i "s#/log/httpd/#/log/httpd24/#g" /opt/rh/httpd24/root/etc/httpd/conf.d/perforce-swarm-site.conf

8. Enable your Apache 2.4 HTTP server so that it automatically starts:

$ systemctl enable httpd24-httpd

9. Start the Apache 2.4 HTTP server:

$ systemctl start httpd24-httpd

10. Check that SELinux is working correctly for your system. For instructions on configuring SELinux on CentOS 7, see SELinux on CentOS 7 configuration.
RHEL 7 (run these commands as root):
Important
• As part of the PHP upgrade process your Apache 2.2 server will be stopped and disabled, if you are currently using the Apache 2.2 server for any other applications they will stop working. You will either need to upgrade these applications to work with PHP 7 and Apache 2.4 or move them to another server.

• If Apache 2.4 has been installed from the SCL or RHSCL packages, the Apache configuration files are installed into /opt/rh/httpd24/root/etc rather than their normal locations in /etc. This means that the usual service, systemctl, and apachectl commands will control the wrong server. To control the version of Apache used by Swarm, use one of the following:

  • For CentOS/RHEL 6 to use System V scripts: service httpd24-httpd restart
  • For CentOS/RHEL 7 to use systemd scripts: systemctl restart httpd24-httpd

  The apachectl command still exists, but must be run in the /opt/rh/httpd24 environment. Because of this we recommended that you use one of the above commands instead.

• To avoid seeing the Apache HTTP server Linux test page when you start the Apache server, comment out the content of the welcome.conf file located in the /opt/rh/httpd24/root/etc/httpd/conf.d/ directory.
The full upgrade process described below is only required the first time you upgrade to PHP 7, for future Swarm upgrades just run step b.
The upgrade process will enable rhel-server-rhscl-7-eus-rpms which gives Swarm access to PHP 7.x and Apache 2.4, upgrade Swarm, stop and disable the Apache 2.2 server, copy and edit some Swarm files so they work with Apache 2.4, and finally start and enable the Apache 2.4 server.
1. Enable the rhel-server-rhscl-7-eus-rpms repository to give Swarm access to PHP 7:

# subscription-manager repos --enable rhel-server-rhscl-7-eus-rpms

Tip

If you don't enable the rhel-server-rhscl-7-eus-rpms repository you will see an error similar to the one shown below when you do the next step:

Error: Package: helix-swarm-2019.2-1845646.el6.x86_64 (perforce)
        Requires: rh-php71

2. Run the Swarm upgrade, this will automatically install PHP 7.x and Apache 2.4:

$ yum install helix-swarm helix-swarm-triggers helix-swarm-optional

3. Disable your Apache 2.2 HTTP server so that is does not automatically start:

$ systemctl disable httpd

4. Stop your Apache 2.2 HTTP server:

$ systemctl stop httpd

5. If you have any special php.ini configuration options set, copy the php.ini file to the /etc/opt/rh/rh-php71/php.d/ directory:

$ cp /etc/php.d/php.ini /etc/opt/rh/rh-php71/php.d/php.ini

6. Copy the perforce-swarm-site.conf file to the /opt/rh/httpd24/root/etc/httpd/conf.d/ directory:

$ cp /etc/httpd/conf.d/perforce-swarm-site.conf /opt/rh/httpd24/root/etc/httpd/conf.d/perforce-swarm-site.conf

7. Replace the /log/httpd/ filepath with /log/httpd24 in the perforce-swarm-site.conf file using the sed command:

$ sed -i "s#/log/httpd/#/log/httpd24/#g" /opt/rh/httpd24/root/etc/httpd/conf.d/perforce-swarm-site.conf

8. Enable your Apache 2.4 HTTP server so that it automatically starts:

$ systemctl enable httpd24-httpd

9. Start the Apache 2.4 HTTP server:

$ systemctl start httpd24-httpd

10. Check that SELinux is working correctly for your system. For instructions on configuring SELinux on RHEL 7, see SELinux on CentOS 7 configuration.
2. Swarm generally has several major updates each year, and may occasionally have a patch update between major updates. To determine whether a Swarm update is available, follow the instructions for your OS distribution:
Ubuntu:

$ sudo apt-get update
$ sudo apt-get -s upgrade | grep swarm

CentOS/RHEL (run this command as root):

# yum list updates | grep swarm

Update your triggers

1. Copy the new Swarm trigger script to your Helix Core server machine. The trigger script is SWARM_ROOT/p4-bin/scripts/swarm-trigger.pl, and requires installation of Perl 5.08+ (use the latest available) on the Helix server machine. If Swarm is using SSL, then the triggers also require the IO::Socket::SSL Perl module.

   Warning

   Do not overwrite any existing trigger script at this time. Give the script a new name, for example: swarm-trigger-new.pl

2. Configure the Swarm trigger script by creating, in the same directory on the Helix server machine, swarm-trigger.conf. It should contain:

   Note

   If you already have a swarm-trigger.conf file, no additional configuration is required.

   # SWARM_HOST (required)
   # Hostname of your Swarm instance, with leading "http://" or "https://".
   SWARM_HOST="http://my-swarm-host"
   
   # SWARM_TOKEN (required)
   # The token used when talking to Swarm to offer some security. To obtain the
   # value, log in to Swarm as a super user and select 'About Swarm' to see the
   # token value.
   SWARM_TOKEN="MY-UUID-STYLE-TOKEN"
   
   # ADMIN_USER (optional) Do not use if the Workflow feature is enabled (default)
   # For enforcing reviewed changes, optionally specify the normal Perforce user
   # with admin privileges (to read keys); if not set, will use whatever Perforce
   # user is set in environment.
   ADMIN_USER=
   
   # ADMIN_TICKET_FILE (optional) Do not use if the Workflow feature is enabled (default)
   # For enforcing reviewed changes, optionally specify the location of the
   # p4tickets file if different from the default ($HOME/.p4tickets).
   # Ensure this user is a member of a group with an 'unlimited' or very long
   # timeout; then, manually login as this user from the Perforce server machine to
   # set the ticket.
   ADMIN_TICKET_FILE=				
   										
   # VERIFY_SSL (optional)
   # If HTTPS is being used on the Swarm web server, then this controls whether
   # the SSL certificate is validated or not. By default this is set to 1, which
   # means any SSL certificates must be valid. If the web server is using a self
   # signed certificate, then this must be set to 0.
   # set the ticket.
   VERIFY_SSL=1

   Fill in the required SWARM_HOST and SWARM_TOKEN variables with the configuration from any previous Swarm trigger script, typically swarm-trigger.pl.

   Tip

   The ADMIN_USER and ADMIN_TICKET variables were used by the 'enforce triggers' in Swarm 2019.1 and earlier. They can be removed unless you are explicitly disabling workflow and using the deprecated 'enforce triggers'.

   Note

   Swarm 2015.4 and earlier: Swarm trigger script files were available as shell scripts in these earlier Swarm versions, typically swarm-trigger.sh.

   Swarm must now use a Perl trigger script file, typically swarm-trigger.pl.

3. On Linux: ensure that the script is executable:

   $ sudo chmod +x swarm-trigger-new.pl

4. Rename the new trigger script:

   On Linux:

   $ mv swarm-trigger-new.pl swarm-trigger.pl

   On Windows:

   C:\> ren swarm-trigger-new.pl swarm-trigger.pl

5. Update the triggers in your Helix server.

   Warning

   • Add the swarm.shelvedel shelve-delete trigger line to the Helix server trigger table if it is not already present, see Update the Helix server triggers table to run the trigger script.

   • Workflow feature:

     The Workflow feature is enabled by default in Swarm 2019.2 and later. The trigger lines required when workflow is enabled are different to those required when workflow is disabled:

     • Workflow feature enabled (default):
       • Comment out the swarm.enforce.1, swarm.enforce.2, swarm.strict.1, and swarm.strict.2 trigger lines in the Helix server trigger table if they are present, see Update the Helix server triggers table to run the trigger script.
       • Add the swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit trigger lines to the Helix server trigger table if they are not already present, see Update the Helix server triggers table to run the trigger script.
     • Workflow feature disabled:

       Comment out the swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit trigger lines in the Helix server trigger table if they are present, see Update the Helix server triggers table to run the trigger script.

   1. Run the Swarm trigger script to capture (using Ctrl+C on Windows and Linux, Command+C on Mac OSX) the trigger lines that should be included in the Perforce trigger table:

      On Linux:

      $ ./swarm-trigger.pl -o

      On Windows:

      C:\> path/to/perl swarm-trigger.pl -o

   2. As a Perforce user with super privileges, update the Perforce trigger table by running p4 triggers command and replacing any swarm.* lines with the previously captured trigger line output (using Ctrl+V on Windows and Linux, Command+V on Mac OSX).
   Important

   If you previously customized the Swarm trigger lines, perhaps to apply various Trigger options, be sure to repeat those customizations within the updated trigger lines.

Validate your upgrade

Check that your upgraded Swarm instance is working correctly by doing the following:

1. Create a new changelist that:
   1. Contains at least one modified file
   2. Contains the #review keyword in the changelist description
2. Right click on the new changelist in P4V and click Shelve Files...
Important

Do not select Request New Swarm Review... because this method uses the API and will not fully test the Swarm triggers.

3. Check that a new Swarm review is created for the changelist.

Swarm index upgrade

If you are upgrading from Swarm 2017.2 or earlier you should run the index upgrade, this ensures that the review activity history is displayed in the correct order on the Dashboard, and Reviews list pages.

The index upgrade process can be configured to suit your Swarm system specifications. See Upgrade index for details.

Run the upgrade as an Admin user by visiting the following URL:

http://SWARM-HOST/upgrade

All done!

Upgrade a Swarm OVA installation from Swarm 2014.1 or earlier

Before you begin your Swarm upgrade

The Swarm Workflow feature was introduced in Swarm 2018.2 and was disabled by default, this feature is now enabled by default for Swarm 2019.2 and later.

If you are not currently using the Swarm workflow feature and you are using the strict and enforce triggers to control commits you have the following options:

• Use the Swarm workflow feature: you must comment out your strict and enforce triggers and use the new workflow triggers.
Note
Known limitations of the Swarm workflow feature:
• EXEMPT_FILE_COUNT: When set to a positive integer, commits with a file count greater or equal to this value are exempt from enforce or strict verifications.
• EXEMPT_EXTENSIONS: A comma separated list of file extension. Commits with files having only these extensions are exempt from enforce or strict verifications.

• Continue to use the strict and enforce triggers: keep your existing enforce and strict triggers and Disable the Workflow feature. Support for these triggers will be dropped in a later release.

  Tip

  If you disable the workflow feature in the Swarm config.php file, workflow will not be processed by Swarm but a small overhead is still incurred by the Helix server each time it runs a workflow trigger script. This overhead can be eliminated by commenting out the swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit workflow triggers.

Decide whether you want to use the workflow feature before you start your upgrade because this will determine which triggers you need to use. The trigger requirements are described in more detail in the Update your triggers stage of the Swarm upgrade.

Upgrade Swarm

The following process attempts to minimize downtime, but a short period of downtime for Swarm users is unavoidable. There should be no downtime for your Helix server. After a successful upgrade, all Swarm users are logged out.

If you are using Swarm in a production environment, we encourage you to test this upgrade process in a non-production environment first.

1. Download the new OVA from https://www.perforce.com/downloads/helix-swarm.
2. Follow the OVA setup steps. This provides you with an upgraded Swarm and an updated web hosting environment within the OVA, which can include distribution, web server, PHP, and security updates.

Update your triggers

1. Copy the new Swarm trigger script to your Helix Core server machine. The trigger script is SWARM_ROOT/p4-bin/scripts/swarm-trigger.pl, and requires installation of Perl 5.08+ (use the latest available) on the Helix server machine. If Swarm is using SSL, then the triggers also require the IO::Socket::SSL Perl module.

   Warning

   Do not overwrite any existing trigger script at this time. Give the script a new name, for example: swarm-trigger-new.pl

2. Configure the Swarm trigger script by creating, in the same directory on the Helix server machine, swarm-trigger.conf. It should contain:

   Note

   If you already have a swarm-trigger.conf file, no additional configuration is required.

   # SWARM_HOST (required)
   # Hostname of your Swarm instance, with leading "http://" or "https://".
   SWARM_HOST="http://my-swarm-host"
   
   # SWARM_TOKEN (required)
   # The token used when talking to Swarm to offer some security. To obtain the
   # value, log in to Swarm as a super user and select 'About Swarm' to see the
   # token value.
   SWARM_TOKEN="MY-UUID-STYLE-TOKEN"
   
   # ADMIN_USER (optional) Do not use if the Workflow feature is enabled (default)
   # For enforcing reviewed changes, optionally specify the normal Perforce user
   # with admin privileges (to read keys); if not set, will use whatever Perforce
   # user is set in environment.
   ADMIN_USER=
   
   # ADMIN_TICKET_FILE (optional) Do not use if the Workflow feature is enabled (default)
   # For enforcing reviewed changes, optionally specify the location of the
   # p4tickets file if different from the default ($HOME/.p4tickets).
   # Ensure this user is a member of a group with an 'unlimited' or very long
   # timeout; then, manually login as this user from the Perforce server machine to
   # set the ticket.
   ADMIN_TICKET_FILE=				
   										
   # VERIFY_SSL (optional)
   # If HTTPS is being used on the Swarm web server, then this controls whether
   # the SSL certificate is validated or not. By default this is set to 1, which
   # means any SSL certificates must be valid. If the web server is using a self
   # signed certificate, then this must be set to 0.
   # set the ticket.
   VERIFY_SSL=1

   Fill in the required SWARM_HOST and SWARM_TOKEN variables with the configuration from any previous Swarm trigger script, typically swarm-trigger.pl.

   Tip

   The ADMIN_USER and ADMIN_TICKET variables were used by the 'enforce triggers' in Swarm 2019.1 and earlier. They can be removed unless you are explicitly disabling workflow and using the deprecated 'enforce triggers'.

   Note

   Swarm 2015.4 and earlier: Swarm trigger script files were available as shell scripts in these earlier Swarm versions, typically swarm-trigger.sh.

   Swarm must now use a Perl trigger script file, typically swarm-trigger.pl.

3. On Linux: ensure that the script is executable:

   $ sudo chmod +x swarm-trigger-new.pl

4. Rename the new trigger script:

   On Linux:

   $ mv swarm-trigger-new.pl swarm-trigger.pl

   On Windows:

   C:\> ren swarm-trigger-new.pl swarm-trigger.pl

5. Update the triggers in your Helix server.

   Warning

   • Add the swarm.shelvedel shelve-delete trigger line to the Helix server trigger table if it is not already present, see Update the Helix server triggers table to run the trigger script.

   • Workflow feature:

     The Workflow feature is enabled by default in Swarm 2019.2 and later. The trigger lines required when workflow is enabled are different to those required when workflow is disabled:

     • Workflow feature enabled (default):
       • Comment out the swarm.enforce.1, swarm.enforce.2, swarm.strict.1, and swarm.strict.2 trigger lines in the Helix server trigger table if they are present, see Update the Helix server triggers table to run the trigger script.
       • Add the swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit trigger lines to the Helix server trigger table if they are not already present, see Update the Helix server triggers table to run the trigger script.
     • Workflow feature disabled:

       Comment out the swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit trigger lines in the Helix server trigger table if they are present, see Update the Helix server triggers table to run the trigger script.

   1. Run the Swarm trigger script to capture (using Ctrl+C on Windows and Linux, Command+C on Mac OSX) the trigger lines that should be included in the Perforce trigger table:

      On Linux:

      $ ./swarm-trigger.pl -o

      On Windows:

      C:\> path/to/perl swarm-trigger.pl -o

   2. As a Perforce user with super privileges, update the Perforce trigger table by running p4 triggers command and replacing any swarm.* lines with the previously captured trigger line output (using Ctrl+V on Windows and Linux, Command+V on Mac OSX).
   Important

   If you previously customized the Swarm trigger lines, perhaps to apply various Trigger options, be sure to repeat those customizations within the updated trigger lines.

Customized OVA configurations

If you have customized the original OVA's Swarm configuration:

1. Copy /opt/perforce/swarm/data/config.php to the same path in the new OVA.
2. Copy all token files in /opt/perforce/swarm/data/queue/tokens/ to the same path in the new OVA.

Validate your upgrade

Check that your new OVA is working correctly by doing the following:

1. Create a new changelist that:
   1. Contains at least one modified file
   2. Contains the #review keyword in the changelist description
2. Right click on the new changelist in P4V and click Shelve Files...
Important

Do not select Request New Swarm Review... because this method uses the API and will not fully test the Swarm triggers.

3. Check that a new Swarm review is created for the changelist.

When you are happy that your new OVA is working correctly, shutdown the old OVA.

Swarm index upgrade

If you are upgrading from Swarm 2017.2 or earlier you should run the index upgrade, this ensures that the review activity history is displayed in the correct order on the Dashboard, and Reviews list pages.

The index upgrade process can be configured to suit your Swarm system specifications. See Upgrade index for details.

Run the upgrade as an Admin user by visiting the following URL:

http://SWARM-HOST/upgrade

All done!

Upgrade a Swarm tarball installation

Before you begin your Swarm upgrade

The Swarm Workflow feature was introduced in Swarm 2018.2 and was disabled by default, this feature is now enabled by default for Swarm 2019.2 and later.

If you are not currently using the Swarm workflow feature and you are using the strict and enforce triggers to control commits you have the following options:

• Use the Swarm workflow feature: you must comment out your strict and enforce triggers and use the new workflow triggers.
Note
Known limitations of the Swarm workflow feature:
• EXEMPT_FILE_COUNT: When set to a positive integer, commits with a file count greater or equal to this value are exempt from enforce or strict verifications.
• EXEMPT_EXTENSIONS: A comma separated list of file extension. Commits with files having only these extensions are exempt from enforce or strict verifications.

• Continue to use the strict and enforce triggers: keep your existing enforce and strict triggers and Disable the Workflow feature. Support for these triggers will be dropped in a later release.

  Tip

  If you disable the workflow feature in the Swarm config.php file, workflow will not be processed by Swarm but a small overhead is still incurred by the Helix server each time it runs a workflow trigger script. This overhead can be eliminated by commenting out the swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit workflow triggers.

Decide whether you want to use the workflow feature before you start your upgrade because this will determine which triggers you need to use. The trigger requirements are described in more detail in the Update your triggers stage of the Swarm upgrade.

Upgrade Swarm

The following process attempts to minimize downtime, but a short period of downtime for Swarm users is unavoidable. There should be no downtime for your Helix server. After a successful upgrade, all Swarm users are logged out.

If you are using Swarm in a production environment, we encourage you to test this upgrade process in a non-production environment first.

CentOS/RHEL: PHP 7.x and Apache 2.4 installation

CentOS and RHEL do not have PHP 7 and Apache 2.4 by default so you must upgrade your system before you can upgrade Swarm. This process is only required the first time you upgrade to PHP 7.

Configure Redis on the Swarm machine

Swarm requires Redis to manage its caches and by default Swarm uses its own Redis server on the Swarm machine. Swarm caches data from the Helix server to improve the performance of common searches in Swarm and to reduce the load on the Helix server. Redis is included in the Swarm Tarball installation.

This section describes how to configure the Swarm Redis service on the Swarm machine. Do not change the default values of the following configuration files if you are using the Swarm Redis server.

Swarm has two Redis binaries in SWARM_ROOT/p4-bin/bin.linux26x86_64/:

• redis-server-swarm
• redis-cli-swarm

1. Configure the Redis cache database, enter the following details in the redis-server.conf file in /opt/perforce/etc/:

bind 127.0.0.1
port 7379
supervised auto
save ""
dir /opt/perforce/swarm/redis

Default values:

Tip
• The default settings are shown below, the redis-server.conf file contains more detailed information about the Redis configuration for Swarm.
• On Swarm systems with a large number of users, groups, and projects, start-up time can be improved by persisting the memory cache. You can persist the memory cache by disabling background saves and enabling append saves, see the redis-server.conf file comments for detailed information.
• bind 127.0.0.1 - Redis server IP address (loopback interface)
• port 7379 - Redis server port number
• supervised auto - detects the use of upstart or systemd automatically to signal that the process is ready to use the supervisors
• save "" - background saves disabled, recommended.
• dir /opt/perforce/swarm/redis - the directory the Redis cache database is stored in.
Tip

To fine-tune your Redis server settings, make your changes in the Zend Redis adapter. For information about the Zend Redis adapter, see the Zend Redis Adapter documentation.

2. The Redis cache database must be running before Swarm starts so we recommend setting it up as a service so that it starts automatically at boot time.

The following example scripts will:

• run the Redis service as the Perforce user
• use the configuration file in /opt/perforce/etc/redis-server.conf
• assume the database server is installed in /opt/perforce/swarm/p4-bin/bin.linux26x86_64/

Use one of the following example scripts to configure Redis as a service:

Ubuntu and CentOS/RHEL 7: add a script with the following content in /etc/systemd/system

redis-server-swarm.service

[Unit]
Description=Redis Server for Swarm
After=network.target

[Service]
ExecStart=/opt/perforce/swarm/p4-bin/bin.linux26x86_64/redis-server-swarm /opt/perforce/etc/redis-server.conf
ExecStop=/opt/perforce/swarm/p4-bin/bin.linux26x86_64/redis-cli-swarm shutdown
Restart=always
RestartSec=10
StandardOutput=syslog
StandardError=syslog
SyslogIndentifier=redis
User=perforce
	Group=perforce
 
[Install]
WantedBy=multi-user.target

CentOS/RHEL 6: add a script with the following content in /etc/init.d

redis-server-swarm.initd

#!/bin/sh
#
# redis-server-swarm init file for starting up the redis daemon used by Helix Swarm
#
# chkconfig:   - 20 80
# description: Starts and stops the redis daemon.
#
### BEGIN INIT INFO
# Provides: redis-server-swarm
# Required-Start: $local_fs $remote_fs $network
# Required-Stop: $local_fs $remote_fs $network
# Short-Description: start and stop Redis server
# Description: A persistent key-value database used by Helix Swarm. Should not clash with
#  any Redis server used by other products.
### END INIT INFO
					
# Source function library.
. /etc/rc.d/init.d/functions

name="redis-server-swarm"
exec="/opt/perforce/swarm/p4-bin/bin.linux26x86_64/$name"
shut="/opt/perforce/swarm/p4-bin/bin.linux26x86_64/redis-cli-swarm"
RUNDIR="/opt/perforce/swarm/redis"
pidfile="$RUNDIR/redis.pid"
REDIS_CONFIG="/opt/perforce/etc/redis-server.conf"
PORT=`grep port $REDIS_CONFIG | cut -d " " -f 2`

lockfile="$RUNDIR/redis.lock"
 
if [ ! -d "$RUNDIR" ]
then
    mkdir -p "$RUNDIR"
    chown perforce:perforce "$RUNDIR"
    chmod 750 "$RUNDIR"
fi

start() {
    [ -f $REDIS_CONFIG ] || exit 6
    [ -x $exec ] || exit 5
    echo -n $"Starting $name: "
    daemon --user perforce "$exec $REDIS_CONFIG --daemonize yes --pidfile $pidfile"
    retval=$?
    echo
    [ $retval -eq 0 ] && touch $lockfile
    return $retval
}

stop() {
    echo -n $"Stopping $name: "
    [ -x $shut ] && $shut -p $PORT shutdown
    retval=$?
    if [ -f $pidfile ]
    then
        # shutdown haven't work, try old way
        killproc -p $pidfile $name
        retval=$?
    else
        success "$name shutdown"
    fi
    echo
    [ $retval -eq 0 ] && rm -f $lockfile
    return $retval
}

restart() {
    stop
    start
}
 
rh_status() {
    status -p $pidfile $name
}

rh_status_q() {
    rh_status >/dev/null 2>&1
}

case "$1" in
    start)
        rh_status_q && exit 0
        $1
        ;;
    stop)
        echo stop
        rh_status_q || exit 0
        $1
        ;;
    restart)
        $1
        ;;
    status)
        rh_status
        ;;		
    condrestart|try-restart)
        rh_status_q || exit 0
        restart
        ;;
    reload|force-reload)
        exit 3
        ;;
    *)	
        echo $"Usage: $0 {start|stop|status|restart|condrestart|try-restart}"
        exit 2	
esac
exit $?

3. The redis block of the SWARM_ROOT/data/config.php file contains the password, namespace, host and port details of the Swarm Redis server:

<?php
    // this block should be a peer of 'p4'
    'redis' => array(
        'options' => array(
            'password' => null, // Defaults to null
            'namespace' => 'Swarm',
            'server' => array(
                'host' => 'localhost', // Defaults to 'localhost' or enter your Redis server hostname
                'port' => '7379', // Defaults to '7379 or enter your Redis server port
            ),            
        ),
        'items_batch_size' => 100000,
        'check_integrity' => '03:00', // Defaults to '03:00' Use one of the following two formats: 
                                      // 1) The time of day that the integrity check starts each day. Set in 24 hour format with leading zeros and a : separator
                                      // 2) The number of seconds between each integrity check. Set as a positive integer. Specify '0' to disable the integrity check.
        'population_lock_timeout' => 300, // Timeout for initial cache population. Defaults to 300 seconds. 
    ),

Configurables:

• password: Redis server password. Defaults to null and should be left at default if using the Swarm Redis server.
• namespace: the prefix used for key values in the Redis cache. Defaults to Swarm and should be left at default if using the Swarm Redis server.
Note

If you have multiple-Swarm instances running against a single Redis server, each Swarm server must use a different Redis namespace. This enables the cache data for the individual Swarm instances to be identified. The namespace is limited to ≤ 128 characters.

If one or more of your Swarm instances is connected to multiple-Helix servers, the Redis namespace includes the server label and the character limit is reduced to ≤ 127 characters, see Multiple-Helix server instances.

• host: Redis server hostname. Defaults to localhost and should be left at default if using the Swarm Redis server.
• port: Redis server port number. Defaults to 7379. Swarm uses port 7379 as its default to avoid clashing with other Redis servers that might be on your network. It should be left at default if using the Swarm Redis server. The default port for a non-Swarm Redis server is 6379.
• items_batch_size: Maximum number of key/value pairs allowed in an mset call to Redis. Sets exceeding this will be batched according to this maximum for efficiency. Defaults to 100000.
Note

The default value of 100000 was chosen to strike a balance between efficiency and project data complexity. This value should not normally need to be changed, contact support before making a change to this value.

• check_integrity: In some circumstances, such as when changes are made in the Helix server when Swarm is down or if errors occur during updates, the Redis cache can get out of sync with the Helix server. Swarm can run a regular integrity check to make sure that the Redis caches and Helix server are in sync. If an integrity check finds an out of sync cache file, Swarm automatically updates the data in that cache.

The check_integrity configurable specifies when the Redis cache integrity check is run. Set as a specific time of day (24 hour format with leading zeros) or a number of seconds (positive integer) between checks. Disable the integrity check with '0'. Defaults to '03:00'.

• population_lock_timeout: specifies the timeout, in seconds, for initial cache population. If you have a large Swarm system, increase this time if the initial cache population times out. Defaults to 300 seconds.

Now that the Swarm Redis service is configured for the Swarm machine, start your Swarm upgrade, see Upgrade Swarm.

Upgrade Swarm

The steps in this section describe how to upgrade Swarm using the provided archive file. SWARM_ROOT refers to the current Swarm installation.

1. Download the new TAR file from https://www.perforce.com/downloads/helix-swarm.

2. Expand the new swarm.tgz:

   $ tar -zxf swarm.tgz
   

   The contents of swarm.tgz are expanded into a top-level folder named swarm-version, where version corresponds to the version downloaded. This directory is identified as SWARM_NEW below.

3. Move SWARM_NEW to be a peer of SWARM_ROOT:

   $ mv SWARM_NEW SWARM_ROOT/../

4. Copy the SWARM_ROOT/data/config.php file from SWARM_ROOT to SWARM_NEW:

    $ cp -p SWARM_ROOT/data/config.php SWARM_NEW/data/
   

5. Create the queue token directory:

    $  mkdir SWARM_NEW/data/queue

6. Copy the existing trigger token(s):

    $ sudo cp -pR SWARM_ROOT/data/queue/tokens SWARM_NEW/data/queue/

7. Assign correct ownership to the new Swarm's data directory:

   $ sudo chown -R www-data SWARM_NEW/data

   Note

   The www-data user above is an example of what the web server user name might be, and can vary based on distribution or customization. For example, the user is typically apache for Red Hat/Fedora/CentOS, www-data for Debian/Ubuntu, wwwrun for SuSE, _www for Mac OSX.

Update your triggers

1. Copy the new Swarm trigger script to your Helix Core server machine. The trigger script is SWARM_ROOT/p4-bin/scripts/swarm-trigger.pl, and requires installation of Perl 5.08+ (use the latest available) on the Helix server machine. If Swarm is using SSL, then the triggers also require the IO::Socket::SSL Perl module.

   Warning

   Do not overwrite any existing trigger script at this time. Give the script a new name, for example: swarm-trigger-new.pl

2. Configure the Swarm trigger script by creating, in the same directory on the Helix server machine, swarm-trigger.conf. It should contain:

   Note

   If you already have a swarm-trigger.conf file, no additional configuration is required.

   # SWARM_HOST (required)
   # Hostname of your Swarm instance, with leading "http://" or "https://".
   SWARM_HOST="http://my-swarm-host"
   
   # SWARM_TOKEN (required)
   # The token used when talking to Swarm to offer some security. To obtain the
   # value, log in to Swarm as a super user and select 'About Swarm' to see the
   # token value.
   SWARM_TOKEN="MY-UUID-STYLE-TOKEN"
   
   # ADMIN_USER (optional) Do not use if the Workflow feature is enabled (default)
   # For enforcing reviewed changes, optionally specify the normal Perforce user
   # with admin privileges (to read keys); if not set, will use whatever Perforce
   # user is set in environment.
   ADMIN_USER=
   
   # ADMIN_TICKET_FILE (optional) Do not use if the Workflow feature is enabled (default)
   # For enforcing reviewed changes, optionally specify the location of the
   # p4tickets file if different from the default ($HOME/.p4tickets).
   # Ensure this user is a member of a group with an 'unlimited' or very long
   # timeout; then, manually login as this user from the Perforce server machine to
   # set the ticket.
   ADMIN_TICKET_FILE=				
   										
   # VERIFY_SSL (optional)
   # If HTTPS is being used on the Swarm web server, then this controls whether
   # the SSL certificate is validated or not. By default this is set to 1, which
   # means any SSL certificates must be valid. If the web server is using a self
   # signed certificate, then this must be set to 0.
   # set the ticket.
   VERIFY_SSL=1

   Fill in the required SWARM_HOST and SWARM_TOKEN variables with the configuration from any previous Swarm trigger script, typically swarm-trigger.pl.

   Tip

   The ADMIN_USER and ADMIN_TICKET variables were used by the 'enforce triggers' in Swarm 2019.1 and earlier. They can be removed unless you are explicitly disabling workflow and using the deprecated 'enforce triggers'.

   Note

   Swarm 2015.4 and earlier: Swarm trigger script files were available as shell scripts in these earlier Swarm versions, typically swarm-trigger.sh.

   Swarm must now use a Perl trigger script file, typically swarm-trigger.pl.

3. On Linux: ensure that the script is executable:

   $ sudo chmod +x swarm-trigger-new.pl

4. Rename the new trigger script:

   On Linux:

   $ mv swarm-trigger-new.pl swarm-trigger.pl

   On Windows:

   C:\> ren swarm-trigger-new.pl swarm-trigger.pl

5. Update the triggers in your Helix server.

   Warning

   • Add the swarm.shelvedel shelve-delete trigger line to the Helix server trigger table if it is not already present, see Update the Helix server triggers table to run the trigger script.

   • Workflow feature:

     The Workflow feature is enabled by default in Swarm 2019.2 and later. The trigger lines required when workflow is enabled are different to those required when workflow is disabled:

     • Workflow feature enabled (default):
       • Comment out the swarm.enforce.1, swarm.enforce.2, swarm.strict.1, and swarm.strict.2 trigger lines in the Helix server trigger table if they are present, see Update the Helix server triggers table to run the trigger script.
       • Add the swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit trigger lines to the Helix server trigger table if they are not already present, see Update the Helix server triggers table to run the trigger script.
     • Workflow feature disabled:

       Comment out the swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit trigger lines in the Helix server trigger table if they are present, see Update the Helix server triggers table to run the trigger script.

   1. Run the Swarm trigger script to capture (using Ctrl+C on Windows and Linux, Command+C on Mac OSX) the trigger lines that should be included in the Perforce trigger table:

      On Linux:

      $ ./swarm-trigger.pl -o

      On Windows:

      C:\> path/to/perl swarm-trigger.pl -o

   2. As a Perforce user with super privileges, update the Perforce trigger table by running p4 triggers command and replacing any swarm.* lines with the previously captured trigger line output (using Ctrl+V on Windows and Linux, Command+V on Mac OSX).
   Important

   If you previously customized the Swarm trigger lines, perhaps to apply various Trigger options, be sure to repeat those customizations within the updated trigger lines.

Replace your old Swarm instance with your new Swarm instance

Replace your old Swarm with the new Swarm. Downtime occurs in this step.

$ sudo apache2ctl stop; mv SWARM_ROOT SWARM.old; mv SWARM_NEW SWARM_ROOT; sudo apache2ctl start

Delete the Swarm config cache

Delete the Swarm config cache to force Swarm to use any new and updated modules in the upgrade. To delete the Swarm config cache, make the following curl request as an admin user:

curl -u "username:password" -X DELETE "https://myswarm.url/api/v10/cache/config/"

For more information on deleting the config cache, see Swarm config cache file delete.

Validate your upgrade

Check that your new Swarm instance is working correctly by doing the following:

1. Create a new changelist that:
   1. Contains at least one modified file
   2. Contains the #review keyword in the changelist description
2. Right click on the new changelist in P4V and click Shelve Files...
Important

Do not select Request New Swarm Review... because this method uses the API and will not fully test the Swarm triggers.

3. Check that a new Swarm review is created for the changelist.

Swarm index upgrade

If you are upgrading from Swarm 2017.2 or earlier you should run the index upgrade, this ensures that the review activity history is displayed in the correct order on the Dashboard, and Reviews list pages.

The index upgrade process can be configured to suit your Swarm system specifications. See Upgrade index for details.

Run the upgrade as an Admin user by visiting the following URL:

http://SWARM-HOST/upgrade

All done!