Upgrading Swarm // Swarm 2017.2 Guide

Upgrading Swarm

The section covers upgrading specific Swarm releases to a newer release. If you are not already running Swarm, none of these instructions apply to you. Instead, see the Swarm installation instructions.

As there may be version specific upgrade requirements, each of the upgrades available are from one point release to the next.

If you have installed Swarm via packages, see the package update instructions.

Note

The instructions below can be applied to an OVA. The OVA's SWARM_ROOT, the folder where Swarm is installed, is /opt/perforce/swarm.

However, we recommend downloading the new OVA and then following the OVA setup steps. This provides you with an upgraded Swarm plus an updated web hosting environment within the OVA, which can include distribution, web server, PHP, and security updates.

If you have customized the original OVA's Swarm configuration, copy /opt/perforce/swarm/data/config.php to the same path in the new OVA.

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

If you are running the Swarm 2014.2 OVA, or newer, Swarm was installed using system packages and can be upgraded by following the package update instructions.

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 Versioning Engine. 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.

Warning

P4PHP should be upgraded to the version included in the new Swarm release. If you have already configured PHP to use the Swarm-provided P4PHP (as recommended), this happens automatically. If you have manually installed P4PHP in some other fashion, upgrade P4PHP before you perform any of the upgrade steps below. See PHP configuration for details.

If you have not already done so, download the Swarm TAR option: Download Swarm

The steps in the following sub-sections describe how to upgrade Swarm using the provided archive file. SWARM_ROOT refers to the current Swarm installation.

The following version-specific upgrades are described:

Upgrade Swarm 2017.1 to 2017.2

This section covers the steps to upgrade from Swarm's 2017.1 release to the 2017.2 release.

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.
Move SWARM_NEW to be a peer of SWARM_ROOT:
```
$ mv SWARM_NEW SWARM_ROOT/../
```
Copy the SWARM_ROOT/data/config.php file from the old Swarm to the new Swarm:
```
$ cp -p SWARM_ROOT/data/config.php SWARM_NEW/data/
```
Create the queue token directory:
```
$ mkdir SWARM_NEW/data/queue
```

Copy the existing trigger token(s):

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

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.
Copy the new Swarm trigger script to your Perforce server machine. The trigger script is SWARM_NEW/p4-bin/scripts/swarm-trigger.pl, and requires installation of Perl 5.08+ (use the latest available) on the Perforce 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.

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

# 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)
# 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)
# 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.
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.

Note

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

For Linux systems, ensure that the script is executable:
```
$ sudo chmod +x swarm-trigger-new.pl
```

Rename the new trigger script:

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

On Windows:

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

Update the triggers in your Helix Versioning Engine.
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:
```
$ ./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 the old Swarm with the new Swarm. Downtime occurs in this step.

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

All done!

Upgrade Swarm 2016.3 to 2017.1

This section covers the steps to upgrade from Swarm's 2016.3 release to the 2017.1 release.

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.
Move SWARM_NEW to be a peer of SWARM_ROOT:
```
$ mv SWARM_NEW SWARM_ROOT/../
```
Copy the SWARM_ROOT/data/config.php file from the old Swarm to the new Swarm:
```
$ cp -p SWARM_ROOT/data/config.php SWARM_NEW/data/
```
Create the queue token directory:
```
$ mkdir SWARM_NEW/data/queue
```

Copy the existing trigger token(s):

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

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.
Copy the new Swarm trigger script to your Perforce server machine. The trigger script is SWARM_NEW/p4-bin/scripts/swarm-trigger.pl, and requires installation of Perl 5.08+ (use the latest available) on the Perforce server machine.

Warning

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

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

# 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)
# 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)
# 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.
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.sh.

Note

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

For Linux systems, ensure that the script is executable:
```
$ sudo chmod +x swarm-trigger-new.pl
```

Rename the new trigger script:

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

On Windows:

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

Update the triggers in your Helix Versioning Engine.
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:
```
$ ./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 the old Swarm with the new Swarm. Downtime occurs in this step.

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

All done!

Upgrade Swarm 2016.2 to 2016.3

This section covers the steps to upgrade from Swarm's 2016.2 release to the 2016.3 release.

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.
Move SWARM_NEW to be a peer of SWARM_ROOT:
```
$ mv SWARM_NEW SWARM_ROOT/../
```
Copy the SWARM_ROOT/data/config.php file from the old Swarm to the new Swarm:
```
$ cp -p SWARM_ROOT/data/config.php SWARM_NEW/data/
```
Create the queue token directory:
```
$ mkdir SWARM_NEW/data/queue
```

Copy the existing trigger token(s):

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

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.
Copy the new Swarm trigger script to your Perforce server machine. The trigger script is SWARM_NEW/p4-bin/scripts/swarm-trigger.pl, and requires installation of Perl 5.08+ (use the latest available) on the Perforce server machine.

Warning

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

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

# 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)
# 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)
# 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.
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.sh.

Note

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

For Linux systems, ensure that the script is executable:
```
$ sudo chmod +x swarm-trigger-new.pl
```

Rename the new trigger script:

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

On Windows:

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

Update the triggers in your Helix Versioning Engine.
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:
```
$ ./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 the old Swarm with the new Swarm. Downtime occurs in this step.

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

All done!

Upgrade Swarm 2016.1 to 2016.1 SP1 or 2016.2

This section covers the steps to upgrade from Swarm's 2016.1 release to the 2016.1 Service Pack 1 or 2016.2 releases.

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.
Move SWARM_NEW to be a peer of SWARM_ROOT:
```
$ mv SWARM_NEW SWARM_ROOT/../
```
Copy the SWARM_ROOT/data/config.php file from the old Swarm to the new Swarm:
```
$ cp -p SWARM_ROOT/data/config.php SWARM_NEW/data/
```
Create the queue token directory:
```
$ mkdir SWARM_NEW/data/queue
```

Copy the existing trigger token(s):

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

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.
Copy the new Swarm trigger script to your Perforce server machine. The trigger script is SWARM_NEW/p4-bin/scripts/swarm-trigger.pl, and requires installation of Perl 5.08+ (use the latest available) on the Perforce server machine.

Warning

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

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

# 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)
# 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)
# 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.
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.sh.

Note

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

For Linux systems, ensure that the script is executable:
```
$ sudo chmod +x swarm-trigger-new.pl
```

Rename the new trigger script:

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

On Windows:

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

Update the triggers in your Helix Versioning Engine.
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:
```
$ ./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 the old Swarm with the new Swarm. Downtime occurs in this step.

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

All done!

Upgrade Swarm 2015.4 to 2016.1

This section covers the steps to upgrade from Swarm's 2015.4 release to the 2016.1 release.

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.
Move SWARM_NEW to be a peer of SWARM_ROOT:
```
$ mv SWARM_NEW SWARM_ROOT/../
```
Copy the SWARM_ROOT/data/config.php file from the old Swarm to the new Swarm:
```
$ cp -p SWARM_ROOT/data/config.php SWARM_NEW/data/
```
Create the queue token directory:
```
$ mkdir SWARM_NEW/data/queue
```

Copy the existing trigger token(s):

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

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.
Copy the new Swarm trigger script to your Perforce server machine. The trigger script is SWARM_NEW/p4-bin/scripts/swarm-trigger.pl, and requires installation of Perl 5.08+ (use the latest available) on the Perforce server machine.

Warning

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

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

# 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)
# 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)
# 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.
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.sh.

Note

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

For Linux systems, ensure that the script is executable:
```
$ sudo chmod +x swarm-trigger-new.pl
```

Rename the new trigger script:

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

On Windows:

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

Update the triggers in your Helix Versioning Engine.
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:
```
$ ./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 the old Swarm with the new Swarm. Downtime occurs in this step.

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

All done!

Upgrade Swarm 2015.3 to 2015.4

This section covers the steps to upgrade from Swarm's 2015.3 release to the 2015.4 release.

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.
Move SWARM_NEW to be a peer of SWARM_ROOT:
```
$ mv SWARM_NEW SWARM_ROOT/../
```
Copy the SWARM_ROOT/data/config.php file from the old Swarm to the new Swarm:
```
$ cp -p SWARM_ROOT/data/config.php SWARM_NEW/data/
```
Create the queue token directory:
```
$ mkdir SWARM_NEW/data/queue
```

Copy the existing trigger token(s):

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

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.
Copy the new Swarm trigger script to your Perforce server machine. The trigger script is SWARM_NEW/p4-bin/scripts/swarm-trigger.pl, and requires installation of Perl 5.08+ (use the latest available) on the Perforce server machine.

Warning

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

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

# 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)
# 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)
# 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.
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.sh.

Note

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

For Linux systems, ensure that the script is executable:
```
$ sudo chmod +x swarm-trigger-new.pl
```

Rename the new trigger script:

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

On Windows:

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

Update the triggers in your Helix Versioning Engine.
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:
```
$ ./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 the old Swarm with the new Swarm. Downtime occurs in this step.

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

All done!

Upgrade Swarm 2015.2 to 2015.3

This section covers the steps to upgrade from Swarm's 2015.2 release to the 2015.3 release.

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.
Move SWARM_NEW to be a peer of SWARM_ROOT:
```
$ mv SWARM_NEW SWARM_ROOT/../
```
Copy the SWARM_ROOT/data/config.php file from the old Swarm to the new Swarm:
```
$ cp -p SWARM_ROOT/data/config.php SWARM_NEW/data/
```
Create the queue token directory:
```
$ mkdir SWARM_NEW/data/queue
```

Copy the existing trigger token(s):

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

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.
Copy the new Swarm trigger script to your Perforce server machine. The trigger script is SWARM_NEW/p4-bin/scripts/swarm-trigger.pl, and requires installation of Perl 5.08+ (use the latest available) on the Perforce server machine.

Warning

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

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

# 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)
# 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)
# 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.
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.sh.

Note

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

For Linux systems, ensure that the script is executable:
```
$ sudo chmod +x swarm-trigger-new.pl
```

Rename the new trigger script:

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

On Windows:

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

Update the triggers in your Helix Versioning Engine.
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:
```
$ ./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 the old Swarm with the new Swarm. Downtime occurs in this step.

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

All done!

Upgrade Swarm 2015.1 to 2015.2

This section covers the steps to upgrade from Swarm's 2015.1 release to the 2015.2 release.

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.
Move SWARM_NEW to be a peer of SWARM_ROOT:
```
$ mv SWARM_NEW SWARM_ROOT/../
```
Copy the SWARM_ROOT/data/config.php file from the old Swarm to the new Swarm:
```
$ cp -p SWARM_ROOT/data/config.php SWARM_NEW/data/
```
Create the queue token directory:
```
$ mkdir SWARM_NEW/data/queue
```

Copy the existing trigger token(s):

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

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.

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

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

If your Swarm is not hosted on Windows, update the trigger entries in the Helix Versioning Engine.

Swarm 2015.2 includes a new trigger script written in Perl. See Setup Swarm triggers with a Linux-hosted Helix Versioning Engine for details.

All done!

Swarm 2017.2 Guide (August 2017)

Upgrading Swarm

Note

Warning

Upgrade Swarm 2017.1 to 2017.2

Note

Warning

Note

Important

Upgrade Swarm 2016.3 to 2017.1

Note

Warning

Note

Important

Upgrade Swarm 2016.2 to 2016.3

Note

Warning

Note

Important

Upgrade Swarm 2016.1 to 2016.1 SP1 or 2016.2

Note

Warning

Note

Important

Upgrade Swarm 2015.4 to 2016.1

Note

Warning

Note

Important

Upgrade Swarm 2015.3 to 2015.4

Note

Warning

Note

Important

Upgrade Swarm 2015.2 to 2015.3

Note

Warning

Note

Important

Upgrade Swarm 2015.1 to 2015.2

Note