Helix Core is now P4 and Helix Swarm is now P4 Code Review. Product user interfaces will be updated soon. Learn more >>

Documentation | 2025.5

# Upgrading a Ubuntu package installation

The section describes how to upgrade a P4 Code Review Ubuntu package installation to a newer release.

- P4 Code Review runtime dependencies change between releases, you must check that your system satisfies the P4 Code Review runtime dependencies before starting the upgrade, see Runtime dependencies.

- Review the PHP requirements before you upgrade P4 Code Review, see PHP.

  P4 Code Review no longer supports PHP 8.0 version.

- Review the P4 Server requirements before you upgrade P4 Code Review, see P4 Server requirements.
- P4 Server 2020.1 and later, permissions have changed for viewing and editing stream spec files in P4 Code Review. To view and edit stream spec files in P4 Code Review, the P4 Code Review user must have admin permissions for the entire depot //...

- If you are upgrading from P4 Code Review 2020.2 or earlier and have userids that contain the forward slash (/) character, add AllowEncodedSlashes NoDecode to the VirtualHost block of your /etc/apache2/sites-enabled/perforce-swarm-site.conf file. For more information about the VirtualHost block, see Apache configuration.

## Upgrade P4 Code Review

From P4 Code Review 2021.1, the P4 Code Review package upgrade installs logrotate to manage your P4 Code Review log rotation. If the package upgrade finds an existing custom logrotate configuration file for P4 Code Review, the upgrade will notify you and give you details on how to disable the new logrotate configuration.

For information about the logrotate configuration, see Logrotate.

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

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

1. Run the following commands:

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

2. P4 Code Review generally has several major updates each year, and may occasionally have a patch update between major updates. To determine whether a P4 Code Review update is available, run the following commands:

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

P4 Code Review uses a Redis server to manage its caches. This is installed and configured on the P4 Code Review machine during the upgrade. If you prefer to use your own Redis server, see Use your own Redis server.

## Configuring P4 Server event notification

P4 Code Review needs to know about a number of P4 Server events to operate correctly, this can be done by using P4 Server Extensions or P4 Server Triggers. P4 Code Review installs include the P4 Server extension file and trigger scripts required for P4 Code Review to get the events it needs from your P4 Server.

You must install the P4 Server extension or update your P4 Code Review triggers to complete the P4 Code Review upgrade.

Do one of the following so that P4 Code Review is notified about events on the P4 Server:

- Install and configure the P4 Server extension, see Installing the P4 Server extension

- Update your P4 Code Review Triggers, see Updating your triggers

### Installing the P4 Server extension

- If you are using the P4 Code Review extension to connect to the P4 Server, do not install P4 Code Review triggers.

- You must be a user with super user permissions to install and configure P4 Server Extensions.

#### Prerequisites

To install the P4 Server extension you need:

A compatible version of P4 Server for the extension:

- Linux: P4 Server 2021.2 and later. If you are using an earlier version of P4 Server, you must use triggers.

- Windows: P4 Server 2021.2 and later. If you are using an earlier version of P4 Server, you must use triggers.

You will also need:

- P4 Server Extensions installed and configured on your P4 Server.

- Your P4 Code Review user password

- A user with super permissions to install and configure P4 Server Extensions.

#### To install the P4 Server extension

There are two ways to install the P4 Server extension:

- Run the interactive post-installation configuration script. See Install process using the interactive post-installation configuration script.

  The P4 Code Review post-installation configuration script can be used in a few different ways. The steps below outline the most straightforward configuration using an interactive install, but you can review the options by running:

  sudo /opt/perforce/swarm/sbin/configure-swarm.sh -h

- Alternatively, use the swarm-extctl.sh script file located in /opt/perforce/swarm/sbin directory. The swarm-extctl.sh script file specifically handles the extension upgrade. See Install process using the swarm-extctl.sh script.

Install process using the interactive post-installation configuration script

1. Run the interactive post-installation configuration script to install the P4 Server extension:

   sudo /opt/perforce/swarm/sbin/configure-swarm.sh

   The configuration script displays a summary for your P4 Code Review instance:

       ------------------------------------------------------------
       configure-swarm.sh: Thu Feb 17 14:20:49 PDT 2021: commencing configuration of Swarm
       Summary of arguments passed:
       Interactive?       [yes]
       Force?             [no]
       P4PORT             [(not specified, will prompt)]
       Swarm user         [(not specified, will prompt, will suggest swarm)]
       Swarm password     [(not specified, will prompt)]
       Email host         [(not specified, will prompt)]
       Use Extensions?    [(not specified, will prompt)]
       Swarm host         [(not specified, will prompt, will suggest myhost)]
       Swarm port         [(default (80))]
       Swarm base URL     [(default (empty))]
       Create Swarm user? [yes]
       Super user         [(not specified, will prompt)]
       Super password     [(not specified, will prompt)]

2. The configuration script prompts you for your P4 Code Review configuration details.

   Enter your P4 Code Review user password when prompted, all of the other details are pre-filled with your existing P4 Code Review configuration. Press the [Enter] key to accept each of them.

3. The script prompts you to use the P4 Server extension.

       Do you want to use Swarm's Helix Core server extension?
       Configuring Server extensions requires super user access to the Helix Server.
       If you install the Swarm server extension, do not install the Swarm triggers.
       Server extensions are supported for:
       * Linux: Helix server 19.2 and later.
       * Windows: Helix server 21.2 and later.

       Use server extensions? (y/n) [n]

Type y to use P4 Server Extensions.

4. Sign in as a user with super permissions when prompted.

5. The script checks that P4 Server Extensions can be installed. The script will:

- Check your P4 Server supports P4 Server Extensions

- Check if P4 Server Extensions are installed and configured on your P4 Server. If they are, P4 Code Review does not need to do anything

- Check if P4 Code Review triggers are installed on the server

If any of these checks fail, P4 Code Review will not install the P4 Server extension and will report the issues on the configuration summary screen.

6. If P4 Code Review triggers are installed, you are prompted to remove them.

    P4 Code Review triggers are installed on this server and must be removed
    before installing extensions. You can either have this script
    automatically remove them, or you can quit and do it manually.
    Do you want to automatically remove the triggers? (y/n) [n]

- Recommended: Type y to get the script to automatically remove the P4 Code Review triggers.

The P4 Code Review triggers are not deleted immediately, the triggers to be removed are listed so you can review them before removing them.

- Type n to manually remove the P4 Code Review triggers from the trigger spec file.

7. The script requests confirmation that it is okay to remove the triggers:

    Are you sure it is okay to remove these triggers? (y/n) [n]

- Recommended: Type y to automatically remove the triggers if the list of triggers looks correct. The script will:

- Save a timestamped copy of your old trigger spec to /opt/perforce/swarm/triggers.saved.yyyymmdd-hhmmss

- Save a timestamped copy of the new trigger spec to /opt/perforce/swarm/triggers.noswarm.yyyymmdd-hhmmss

- Remove the P4 Server triggers from the trigger spec and save it

If either of the trigger specs contain sensitive information, move them to a secure location.

- Type n if you see something wrong with the P4 Code Review triggers marked for removal or if you want to remove the triggers from the trigger spec manually. You are offered the option of automatically opening your trigger spec file in your default text editor or opening the file manually in a text editor. Save your changes and rerun the post-installation configuration script to complete the installation of the P4 Serverextension.

8. The script will now install and configure the P4 Server extension for you. When it has completed the configuration, the configuration summary screen is displayed, for example:

    ...........
    - installing instance configuration
    Extension config swarm saved
    configure-swarm.sh: Thu Feb 17 14:31:36 PDT 2021: completed configuration of Helix Swarm

    ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
    ::
    ::  Swarm is now configured and available at:
    ::
    ::      http://myhost/
    ::
    ::  Ensure that you have configured the P4 Code Review hostname in your
    ::  network's DNS, or have added an IP address-to-hostname
    ::  mapping to your computer's hosts configuration so that you
    :: can access P4 Code Review.
    ::
    ::  You may login as the Swarm user [swarm] using the password
    ::  you specified.
    ::
    ::  Server side extensions are installed and configured
    ::  on your P4D server.
    ::
    ::  Documentation for optional post-install configuration, such as
    ::  configuring Swarm to use HTTPS, operate in a sub-folder, or on a
    ::  custom port, is available:
    ::
    ::  https://www.perforce.com/perforce/doc.current/manuals/swarm/setup.post.html
    ::
    ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

9. The P4 Code Review upgrade is now complete.

Install process using the swarm-extctl.sh script

1. Navigate to the the swarm-extctl.sh script file located in /opt/perforce/swarm/sbin directory.

2. Run the following commands as root:

   1. Backup the current configuration. Ensure that the current configuration is correctly backed up before continuing.

      sudo ./swarm-extctl.sh -p <masterserverIp:port> -u <username> save

   2. Remove the existing extension from the master.

      sudo ./swarm-extctl.sh -p <masterserverIp:port> -u <username> delete

   3. Install the latest version of P4 Server extension located on the P4 Code Review server on the master. The following command will check for all saved configurations and apply them during install.

      sudo ./swarm-extctl.sh -p <masterserverIp:port> -u <username> install

3. The P4 Code Review upgrade is now complete.

#### Next step

Now Validate your upgrade.

### Updating your triggers

Do not install the P4 Code Review extension on your P4 Server if you intend on using P4 Code Review triggers.

1. Copy the new P4 Code Review trigger script to your P4 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 P4 Server machine. If P4 Code Review is using SSL, then the triggers also require the `IO::Socket::SSL` Perl module.

   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 P4 Code Review trigger script by creating, in the same directory on the P4 Server machine, `swarm-trigger.conf`. It should contain:

   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 P4 Code Review trigger script, typically `swarm-trigger.pl`.

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

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

   P4 Code Review 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:

   ren swarm-trigger-new.pl swarm-trigger.pl

5. Update the triggers in your P4 Server.

   - The swarm.shelvedel shelve-delete trigger line was added to P4 Code Review in version 2018.1 and updated in version 2020.1.

     - Upgrading from P4 Code Review 2017.4 and earlier: add the `swarm.shelvedel shelve-delete` trigger line to the P4 Server trigger table if it is not already present.
       - If you are using windows, see Update the P4 Server triggers table.
       - If you are using Linux, see Update the P4 Server triggers table.
     - Upgrading from P4 Code Review 2018.x and 2019.x: replace the existing `swarm.shelvedel shelve-delete` trigger line in the P4 Server trigger table with the one supplied in the P4 Code Review version you are upgrading to.

   - Workflow feature:

     The Workflow feature is enabled by default in P4 Code Review 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 P4 Server trigger table if they are present.
       - Add the `swarm.enforce change-submit`, `swarm.strict change-content`, and `swarm.shelvesub shelve-submit` trigger lines to the P4 Server trigger table if they are not already present.
       - If you are using windows, see Update the P4 Server triggers table.
       - If you are using Linux, see Update the P4 Server triggers table.
     - Workflow feature disabled:

       Comment out the `swarm.enforce change-submit`, `swarm.strict change-content`, and `swarm.shelvesub shelve-submit` trigger lines in the P4 Server trigger table if they are present.

       - If you are using windows, see Update the P4 Server triggers table.
       - If you are using Linux, see Update the P4 Server triggers table.

   1. Run the P4 Code Review trigger script to capture (using Ctrl+C on Windows and Linux) the trigger lines that should be included in the Perforce trigger table:

      On Linux:

      ./swarm-trigger.pl -o

      On Windows:

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

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

#### Next step

Now Validate your upgrade.

## Validate your upgrade

When P4 Code Review starts it verifies the Redis cache, during this time you cannot log in to P4 Code Review. The time taken to verify the Redis cache depends on the number of users, groups, and projects P4 Code Review has. 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 in the redis-server.conf file, see Redis server configuration file.

Check that your upgraded P4 Code Review 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...

Do not select Request New Review... because this method uses the API and will not fully test the P4 Server extension.

This is also true if you are using P4 Code Review triggers instead of the P4 Server extension.

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

- If a review is created, the P4 Server extension is working. If you are using P4 Code Review triggers instead of the P4 Server extension and the review is created, the triggers are working.
- If a review is not created, see Troubleshooting: Review not created.

## P4 Code Review index upgrade

If you are upgrading from P4 Code Review 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.

If you are upgrading from P4 Code Review version 2017.3 or later, the index upgrade step is not required.

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

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

    http://SWARM-HOST/upgrade

After the P4 Code Review upgrade, on the first visit to some P4 Code Review pages, users might see a message to perform a browser hard refresh. This happens because we are updating the UI and content of some P4 Code Review pages, so the user's page cache is no longer valid and requires a hard refresh to load the upgraded page. For example, for Chrome on Windows/Linux [CTRL]+[F5].

## Secure your P4 Code Review installation

To make your P4 Code Review installation more secure apply the following recommendations for HTTP and P4 Code Review implementation through security groups.

### HTTP

Here is a list of best practices to use when port 80 is exposed for HTTP traffic:

- Redirect to HTTPS: If Port 80 needs to be open to support legacy systems or specific use cases, ensure that all HTTP traffic is redirected to HTTPS to encrypt data in transit.

- Use HSTS (HTTP Strict Transport Security) headers: Implement HSTS headers to force browsers only to use secure HTTPS connections when interacting with your server.

- Close port 80: If there is no requirement to use HTTP, Port 80 must be closed entirely to prevent any unencrypted data transmission.

- Implement SSL/TLS (secure sockets layer and transport layer security) certificates: Ensure that your server is configured with a valid SSL/TLS certificate to enable secure HTTPS connections.

- Firewall configuration: Configure firewalls to block or filter access to Port 80, particularly from untrusted networks.

- Continuous monitoring and auditing: Regularly monitor network traffic and audit server configurations to ensure that unnecessary ports are not exposed and that data is transmitted securely.

When you implement HTTPS, you must make the following changes:

1. Modify your cron job for the P4 Code Review workers.

   Edit the cron configuration file to point to your HTTPS URL, for example, https://HOSTNAME/. For more information about how to edit the cron configuration file, see Set up a recurring task to spawn workers.

   To verify if the cron configuration file points to your HTTPS URL, run the following curl statement:

   curl https://myswarm.host/queue/worker

2. Modify the P4 Code Review Extension or Trigger configuration with the following:

   1. If you are using the P4 Code Review extension run the following command and change ExtConfig’s P4 Code Review URL to be your new HTTPS URL:

      p4 extension --configure Perforce:helix-swarm

   2. In the ExtConfig block, find SSL-CA-File and set the absolute path of the Certificate Authority (CA) Privacy-Enhanced Mail (PEM) file to validate the P4 Server's certificate for P4 Code Review. Ensure that this file is accessible to the P4 Server process owner. By default, the local certificate stored in the default CA file is used if the absolute path for the Certificate Authority (CA) is not specified.

      If a suitable certificate is not found in the local SSL certificate store maintained by the operating system or if there are verification issues from using a self-signed certificate then the default CA file is used.

   If you are using triggers, edit swarm-trigger.pl configuration file and set your SWARM_HOST to be https.

3. Edit the external_url in the `SWARM_ROOT/data/config.php` file’s environment block to point to your HTTPS URL. This URL is used in emails, Jira links, and P4 Code Review test’s pass-and-fail outgoing URL parameters.

   If you make a configuration change, P4 Code Review will not use it until the configuration cache has been reloaded, this forces P4 Code Review to use the new configuration.

   You must be an admin or super user to reload the P4 Code Review config cache. Navigate to the User id dropdown menu, select System Information, click the Cache Info tab, and click the Reload Configuration button.

4. Modify the P4 Server's P4.Swarm.URL property. For more information about P4 Server integration, see Client integration.

   If your Apache server is listening on both HTTPS and HTTP in perforce-swarm-site.conf file, you must set the auto_register_urlconfigurable in the p4 block to false and correctly configure the P4.Swarm.URL property .

   If your Apache server is listening only on HTTPS and if the auto_register_urlconfigurable in the p4 block is set to true (default value), an Apache restart will correct the property.

   To get all your current values for P4.Swarm.URL property, run:

   p4 -Ztag property -A -l -n P4.Swarm.URL

   Ensure that the P4.Swarm.URL property points to your HTTPS URL.

5. Modify the URL of all applications. Any other applications that reference the URL should be switched to using the HTTPS URL.

### P4 Code Review implementation through security groups

You can implement security headers by using security groups or the user's preferred setup.

Review the following guidelines:

- Use a trusted proxy: Use a trusted proxy, such as allow lists, Content Delivery Networks (CDN), or API Gateways.

- Disable backend servers and other proxies or load balancers: Ensure that direct access to backend servers and other proxies or load balancers is disabled, except through the trusted proxy. In this way, you can help to prevent unauthorized access while ensuring that all requests are filtered through the trusted proxy.

- Implement continuous monitoring and logging of the X-Forwarded-For header: Implement monitoring and logging on the X-Forwarded-For header to track and identify any suspicious activities. Continuous monitoring can help to identify and prevent potential malicious activity or security threats.

- Use a secure protocol: Implement a secure protocol such as HTTPS to encrypt the communications between the client and the load balancers, and between the load balancer and backend server to prevent eavesdropping or tampering with the X-Forwarded-For header.

- Configure the X-Forwarded-For header: Configure the processing mode of the X-Forwarded-For header (append, preserve, or remove) based on specific technical or security requirements.

All done!

Your search for returned results