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

# Install and configure P4 Code Review on Ubuntu

P4 Code Review is available as a package for Ubuntu 22.04 LTS and 24.04 LTS. Using distribution packages greatly simplifies the installation, updating, and removal of software, as the tools that manage these packages are aware of the dependencies for each package.

## Prerequisites

- Review the runtime dependencies before you install P4 Code Review, see Runtime dependencies.

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

- Review the P4 Server requirements before you install P4 Code Review, see P4 Server requirements.
- Ensure the automated user has `admin` or `super` privileges in the P4 Server to enable P4 Code Review to run against the P4 Server. For more information, see P4 Server automated user requirements for P4 Code Review.

P4 Code Review can be connected to P4 Servers (P4D) and commit servers:

- To configure P4 Code Review to connect to more than one P4 Server, see Multiple P4 Server instances.
- To configure P4 Code Review to connect to a P4 Server configured to use commit-edge architecture, see Commit-edge deployment.

Do not connect P4 Code Review to P4 Broker, P4 Proxy, an edge server, forwarding replica, or read-only replica servers.

P4 Code Review does not support P4 Servers that are configured to use P4AUTH. For more information, see Centralized authorization server (P4AUTH).

## Installation

1. Configure the Perforce package repository, on the server to host P4 Code Review and on the server hosting your P4 Server.

   If the server hosting your P4 Server cannot use packages, for example when it is running Windows, skip this step on that server.

   Follow the instructions for your OS distribution:

   - Ubuntu 22.04: As root, create the file `/etc/apt/sources.list.d/perforce.list` with the following content:

     deb [signed-by=/usr/share/keyrings/perforce.gpg] https://package.perforce.com/apt/ubuntu jammy release

   - Ubuntu 24.04: As root, create the file `/etc/apt/sources.list.d/perforce.list` with the following content:

     deb [signed-by=/usr/share/keyrings/perforce.gpg] https://package.perforce.com/apt/ubuntu noble release

2. Import the Perforce package signing key, on the server to host P4 Code Review and the server hosting your P4 Server.

   If the server hosting your P4 Server cannot use packages, for example when it is running Windows, skip this step on that server.

   If you are using an older version of OpenSSL that does not support TLSv1.2 or higher, replace 'https' with 'http' in the wget command.

   Run the following commands as root for your OS distribution. The same command works on either Ubuntu 22.04 or 24.04:

   wget -qO - https://package.perforce.com/perforce.pubkey | gpg --dearmor | sudo tee /usr/share/keyrings/perforce.gpg

   sudo apt-get update

   For information about how to verify the authenticity of the signing key, see Perforce Packages.

3. Install the main P4 Code Review package on the server to host P4 Code Review.

   sudo apt-get install helix-swarm

When the P4 Code Review installation has completed, you are prompted to run the configure-swarm.sh post-installation script.

Do not run this script until you have completed the rest of these Installation instructions. Instructions for running the configure-swarm.sh post-installation script are in the Post-Installation configuration section referenced in the final step of the Installation instructions.

4. P4 Code Review needs to know about some P4 Server events to operate correctly. Use P4 Server Extensions (recommended) or P4 Server Triggers to notify P4 Code Review about these events. The P4 Server extension can be installed automatically by the P4 Code Review configure-swarm.sh post-installation script, but Triggers must be manually installed. To use P4 Server Extensions, ignore this step and skip to the next step.

   Trigger installation only (not recommended): Install the P4 Code Review triggers package on the server hosting your P4 Server. This might be the server hosting P4 Code Review or elsewhere on your network.

   - If the server hosting your P4 Server cannot use packages, for example when it is running Windows, you need to copy the appropriate P4 Code Review trigger script from `/opt/perforce/swarm/p4-bin/scripts` to the server hosting your P4 Server. The `swarm-trigger.pl` is for both Linux and Windows systems. Once copied, the trigger script needs to be configured. See Installing triggers for details.

   - The package installs a config file at `/opt/perforce/etc/swarm-trigger.conf` that you will need to modify. See Installing triggers for more details on configuring that file.

   Install the P4 Code Review triggers package on the server hosting your P4 Server

   sudo apt-get install helix-swarm-triggers

5. Optional: Install the P4 Code Review optional package, on the server hosting P4 Code Review.

   While not required, installing this package installs the dependencies required to use the ImageMagick and LibreOffice P4 Code Review modules. These modules provide previews of a variety of image and office documents.

   sudo apt-get install helix-swarm-optional

6. Make your P4 Code Review installation more secure by applying recommendations related to HTTP and P4 Code Review implementation through security groups. See Secure your P4 Code Review installation .

7. Complete the Post-installation configuration steps.

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

## Post-installation configuration

Once the helix-swarm package has been installed, additional configuration is required. Perform the following steps:

1. Use the P4 Code Review post-installation script to configure P4 Code Review on the server hosting P4 Code Review.

   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

   - If your P4 Server is configured for P4 AS, the P4 Server must be temporarily configured to allow fall-back to passwords while you establish a connection to the P4 Server. Run the following command on the P4 Server to enable fall-back to passwords:

     p4 configure set auth.sso.allow.passwd=1

   - To use P4 ServerExtensions, make sure that Extensions are installed and configured on your P4 Server before running the configuration script. For information about P4 ServerExtensions , see p4 extension in P4 CLI Reference and Extensions overview in P4 Server Administration Documentation.

   Run the interactive post-installation configuration script:

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

   The configuration script displays the following summary:

       ------------------------------------------------------------
       configure-swarm.sh: Thu Aug 26 11:29: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)]
       Create depot       [(not specified, will prompt)]
       Bypass Lock        [(not specified)]
       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. Provide information to the configuration script.

   After the summary, the configuration script prompts for the following information:

   1. Specify a value for `P4PORT` in the form: my-helix-core-server:1666

          No P4PORT specified

          P4 Code Review requires a connection to a Helix Core Server.
          Please supply the P4PORT to connect to.

          Helix Core Server address (P4PORT):

      Specify the hostname and port for your P4 Server. If defined, the value for P4PORT is used as the default. The configuration script verifies that it can connect:

          -response: [myp4host:1666]

          Checking P4PORT [myp4host:1666]...
          -P4 command line to use: [/opt/perforce/bin/p4 -p myp4host:1666]
          Attempting connection to [myp4host:1666]...
          -connection successful:
            Server address: myp4host:1666
            Server version: P4D/LINUX26X86_64/2021.1/2179737 (2021/04/24)
            Server license: 10000 users (support ends 2022/05/16)
            Server license-ip: 192.168.0.1

      If your P4 Server is deployed using the commit-edge architecture, ensure that the P4 Code Review port value points to the commit server.

      For more information, see the Commit-edge chapter in the P4 Server Administration Documentation.

   2. Specify the userid and password of a normal user with admin-level privileges in the P4 Server.

          Checking Swarm user credentials...
          No Swarm user specified

          Swarm requires a Helix user account with 'admin' rights.
          Please provide a username and password for this account.
          If this account does not have 'admin' rights, it will
          be set for this user.

          Helix username for the Swarm user [swarm]:

      Enter the userid. The default is swarm.

          -response: [swarm]

          Helix password or login ticket for the P4 Code Review user (typing hidden):

      To allow users to clean up reviews created by other users when the review is committed, the P4 Server user account must have super permissions.

      See Review cleanup.

      Enter the login ticket, or password, for the userid.

      You must use a long-lived login ticket for the P4 Code Review user.

      You can obtain a login ticket by running (in another shell):

      p4 -p myp4host:1666 -u userid login -p

      If the login ticket you provide expires in less than a year, you will receive a warning. If you receive this warning, ask your P4 Server administrator to make sure the swarm user is in a P4 Server group that has the Timeout field set to a year or more. See p4 group in the P4 CLI Reference.

          Checking Swarm user credentials...
          -checking if user [swarm] exists in [myp4host:1666]...
          -user exists
          Obtaining Helix login ticket for [swarm] in [myp4host:1666]...
          -login ticket obtained
          Checking user [swarm]'s ticket against [myp4host:1666]...
          -login ticket is good
          Checking user [swarm] has at least access level [admin]...
          -user has maximum access level [admin]
          -user meets minimum access level [admin]

   3. Specify the hostname for the P4 Code Review UI.

          swarm needs a distinct hostname that users can enter into their browsers to
          access Swarm. Ideally, this is a fully-qualified domain name, for example
          'swarm.company.com', but it can be just a hostname, for example 'swarm'.

          Whatever hostname you provide should be Swarm-specific and not shared with
          any other web service on this host.

          Note that the hostname you specify typically requires configuration in your
          network's DNS service. If you are merely testing Swarm, you can add a
          hostname->IP mapping entry to your computer's hosts configuration.

          Hostname for this Swarm server [myhost]:

      The default is the current hostname

      The configuration script does not verify that the hostname actually works (DNS configuration may not exist yet).

   4. Specify a mail relay host or leave empty to use your local mail handler.

          P4 Code Review can use a mail relay host to send email notifications. Leave empty if
          you want to use the local mail handler (for example Sendmail, Postfix etc),
          or enter a hostname (for example mx.yourdomain.com) to use a relay host.

          Mail relay host:

      The configuration script does not verify that the mail relay host you provide actually accepts SMTP connections.

   5. To enable file attachments on comments, P4 Code Review must have a depot location to save the attachment files in. P4 Code Review can create this depot and set the depot protections for you automatically or you can manually set it up later.

      You must be a user with super user permissions to create the .swarm depot and set protections.

          - checking depot

          P4 Code Review has the ability to store attachments against review comments. To
          do this, it needs to have a depot where they are stored. By default,
          this is //.swarm. We can create the depot for you automatically, and
          set the protections on it to the following:

          list user * * -//.swarm/...
          admin user swarm * //.swarm/...
          super user super * //.swarm/...

          If you want to enable attachments, and for the depot and protections
          to be set up for you, then say yes here. If you say no, then you can
          still do this manually later.
          Do you want to create a .swarm depot and set protections? (y/n) [n]

      When prompted to automatically create the depot, select one of the following:

      - Type y to automatically create the .swarm depot and set protections.

      - Type n skip depot creation. You can create the depot and set the protections manually later if you want to, see Comment attachments.

      If you choose to automatically create the depot, the script will create the depot, set the protections, and report when completed.

          Depot //.swarm successfully created. Protections have been set so
          that only the 'swarm' and 'super' have permissions to
          access it directly.

   6. Configure the following to enable communication between P4 Code Review and P4 Server.

      - Configure the P4 Server to promote all shelved changes. For more information, see Configure the P4 Server to promote all shelved changes.

      - Configure the `p4 key` access on P4 Server. For more information on `p4 key` and their access levels, see Hiding P4 Code Review storage from regular users.

      - Allow P4 Code Review to work with 'exclusive open' files. For more information about exclusive locks, see Handling Exclusive Locks.

      Run the following to set these three configurations:

          p4 configure dm.shelve.promote=1
          p4 configure set dm.keys.hide=2
          p4 configure set filetype.bypasslock=1

   If this setting is not enabled in P4 Server, P4 Code Review will report exceptions when working with exclusively opened files similar to Cannot unshelve review (x). One or more files are exclusively open, and that you must have the filetype.bypasslock configurable enabled.

   7. P4 Code Review needs to know about some P4 Server events to operate correctly. Use P4 Server Extensions (recommended) or P4 Server Triggers to notify P4 Code Review about these events. P4 Server Extensions are easier to install and maintain than triggers.

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

          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?

      When prompted to Use server Extensions, choose one of the following:

      - Recommended: Type y to use P4 Server Extensions. The configuration script will try and install and configure the P4 Server extension.

      - Type n to use P4 Server Triggers. Triggers must be installed manually, P4 Code Review will prompt you to do this when the P4 Code Review configuration script completes.

      If you choose to install the P4 Server Extensions, 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

      - install and configure the P4 Server extension on your P4 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.

   Once all of the information has been provided, the configuration script configures P4 Code Review. When it has completed the configuration, the configuration summary screen is displayed, for example:

       ...........
       -restarting Apache...
       -Apache restarted
       configure-swarm.sh: Thu Aug 26 11:31:36 PDT 2021: completed configuration of Helix Swarm

       ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
       ::
       ::  Swarm is now configured and available at:
       ::
       ::      http://myhost/
       ::
       ::  You may login as the Swarm user [swarm] using the password
       ::  you specified.
       ::
       ::  Ensure that you have configured the Swarm 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 Swarm.
       ::
       ::  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
       ::
       ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

If you have installed P4 Code Review on a host that does not provide other web services, you may wish to disable Apache's default site configuration. Doing so means that regardless of the hostname a user might use to reach the web server hosting P4 Code Review, P4 Code Review would be presented.

Be aware that disabling Apache's default site configuration could disable existing web services or content.

To disabling Apache's default site configuration on Ubuntu, run:

$ sudo a2dissite 000-default

To add Swarm as an HTML tab in the P4 Visual Client (P4V), see HTML Tabs section in the P4VJS Developer Guide.

3. The basic P4 Code Review configuration is now complete.

   If your P4 Server is configured for P4 AS, you can force all of your users to authenticate via your Identity Provider (IdP) by disabling fall-back to passwords.

   To disable fall-back to passwords on the P4 Server, run the following command:

   p4 configure set auth.sso.allow.passwd=0

4. Do one of the following:

   - If the P4 Server extension was installed by the configuration script: Review the post-install configuration options to customize your P4 Code Review installation, see Post-install configuration options.

   - If the P4 Server extension was not installed, you must install triggers: Configure P4 Server for P4 Code Review, see Installing triggers.

## Upgrading

See Upgrading a Ubuntu package installation for details.

## Uninstall

1. Depending on how you have configured your Helix Core Server events, do one of the following:

   - Uninstall the P4 Server extension. To do this, run the following command on your P4 Server:

     p4 extension --delete Perforce::helix-swarm --yes

   - Uninstall the P4 Code Review triggers. As a super user, run the p4 triggers command from your P4 Server and manually remove all the P4 Code Review trigger code lines.

2. Uninstall the P4 Code Review main package, the P4 Code Review triggers package, and the P4 Code Review optional package. The following example assumes that the packages are all installed on the same server:

   sudo apt-get remove helix-swarm helix-swarm-triggers helix-swarm-optional

3. Remove the P4 Code Review trigger scripts from the server hosting your P4 Server.

   If you manually installed the trigger script, you must manually remove the script.

Your search for returned results