Helix Core is now P4 and Helix Swarm is now P4 Code Review. Learn more >>

Documentation | 2025.2

# Post-install configuration options

There are a few options for customizing your P4 Code Review installation's operation. This section covers the options that are officially supported.

This section contains:

- No customization required
- Back up your P4 Code Review virtual host first
- HTTPS
- Run P4 Code Review in a sub-folder of an existing web site
- Run the P4 Code Review virtual host on a custom port
- Use your own Redis server
- Hiding P4 Code Review storage from regular users
- Handling Exclusive Locks

## No customization required

If you do not need to customize your P4 Code Review installation, your P4 Code Review installation is complete but you must check that it is working correctly before using it in production. For instructions on how to check your P4 Code Review installation, see Validate your P4 Code Review installation.

## Back up your P4 Code Review virtual host first

Before undertaking any of the following customization options, ensure that you have backed up your P4 Code Review virtual host configuration. Choose the most appropriate option:

- If your Apache configuration directory contains the directories `sites-available` and `sites-enabled`:

      $ cd /path/to/apache/configuration/..
      $ cp -a sites-available sites-available.bak

  If the `sites-enabled` directory contains files, and not just symbolic links, you need to backup this folder as well:

      $ cd /path/to/apache/configuration/..
      $ cp -a sites-enabled sites-enabled.bak

- For RHEL systems, if you used the P4 Code Review packages to install P4 Code Review:

      $ cd /path/to/apache/configuration/..
      $ cp -a conf.d conf.d.bak

- Otherwise, back up your Apache configuration.

## HTTPS

Back up your P4 Code Review virtual host configuration before customizing your P4 Code Review installation, see Back up your P4 Code Review virtual host first.

This section describes how to make your P4 Code Review installation more secure by using HTTPS.

Before you begin the following procedure, locate your system's Apache configuration. Common configuration directories include:

- /etc/httpd/conf/
- /etc/apache2/
- /usr/local/apache2/conf/
- /Applications/XAMPP/etc/

Within the Apache configuration path, the main Apache configuration file is usually named one of the following:

- httpd.conf
- apache2.conf

A longer discussion on the possible locations and names of Apache configuration files is available here: DistrosDefaultLayout

1. Enable SSL in Apache.

   If the Apache utility `a2enmod` is installed:

       $ sudo a2enmod ssl

   Without the `a2enmod` utility, edit the Apache configuration file by hand. Locate your Apache configuration file for modules and either uncomment or add the following lines:

       LoadModule  ssl_module  libexec/apache2/mod_ssl.so

2. Create a directory to store certificates.

       $ sudo mkdir -p /etc/apache2/ssl

3. Create a certificate/key pair.

       $ cd /etc/apache2/ssl
       $ sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout apache.key -out apache.crt

   This command generates a private key and a certificate. To form the certificate, `openssl` prompts you for several details:

       Generating a 2048 bit RSA private key
       ...................+++
       ....................................+++
       writing new private key to 'apache.key'
       -----
       You are about to be asked to enter information that will be incorporated
       into your certificate request.
       What you are about to enter is what is called a Distinguished Name or a DN.
       There are quite a few fields but you can leave some blank
       For some fields there will be a default value,
       If you enter '.', the field will be left blank.
       -----
       Country Name (2 letter code) [AU]:CA
       State or Province Name (full name) [Some-State]:British Columbia
       Locality Name (eg, city) []:Victoria
       Organization Name (eg, company) [Internet Widgits Pty Ltd]:Perforce Software
       Organizational Unit Name (eg, section) []:P4 Code Review development team
       Common Name (e.g. server FQDN or YOUR name) []:myswarm.host
       Email Address []:admin@myswarm.host

   The output above includes some example details. You should replace anything in italics with your own details. Since the certificate request details that can help users determine whether your certificate is valid, enter legitimate information whenever possible.

   The Common Name field must match the hostname for your P4 Code Review installation exactly.

4. Secure the certificate directory.

       $ sudo chmod 600 /etc/apache2/ssl

5. Edit the virtual host configuration.

   The virtual host configuration should be in the file you backed up initially.

   Edit the virtual host configuration to match:

       <VirtualHost *:80>
       	ServerName myswarm
       	AllowEncodedSlashes NoDecode
       	ServerAlias myswarm.host
       	ErrorLog "/path/to/apache/logs/myswarm.error_log"
       	CustomLog "/path/to/apache/logs/myswarm.access_log" common
       	DocumentRoot "/path/to/swarm/public"
       	<Directory "/path/to/swarm/public">
       		AllowOverride All
       		Require all granted
       	</Directory>

              Redirect / https://myswarm.host/
       </VirtualHost>

       <VirtualHost *:443>
       	SSLEngine on
       	SSLCertificateFile /etc/apache2/ssl/apache.crt
       	SSLCertificateKeyFile /etc/apache2/ssl/apache.key

       	ServerName myswarm.host
       	AllowEncodedSlashes NoDecode
       	ServerAlias myswarm
       	ErrorLog "/path/to/apache/logs/myswarm.error_log"
       	CustomLog "/path/to/apache/logs/myswarm.access_log" common
       	DocumentRoot "/path/to/swarm/public"
       	<Directory "/path/to/swarm/public">
       		AllowOverride All
       		Require all granted
       	</Directory>
       </VirtualHost>

   See Apache's virtual host documentation for details: Apache Virtual Host documentation

6. Customize the virtual host definition.

   1. Replace `myswarm.host` with the hostname for P4 Code Review on your network.

   2. Replace `myswarm` with the name of the subdomain hosting P4 Code Review. Many administrators choose swarm.

      The string myswarm in the log file paths: this should match the subdomain name and prefix for the log files, to help coordinate the active host with the log files for that host. Doing this is particularly useful when your Apache server hosts multiple instances of P4 Code Review.

   3. Replace `/path/to/apache/logs` with the path where your Apache store its log files. Apache's log files are typically named `access_log` and `error_log`.
   4. Replace `/path/to/swarm` with the path to the P4 Code Review directory.

7. Restart your web server.

   $ sudo apachectl restart

8. Adjust your firewall configuration to allow connections to the standard SSL port for web servers.

   - For RHEL:

         $ sudo firewall-cmd --zone=public --add-port=443/tcp --permanent
         $ sudo systemctl reload firewalld

   - For other distributions, consult with your network administrator or operating system documentation to determine how to adjust your firewall configuration.

9. Test your HTTPS URL from a web browser.

   If the `myswarm.host` value in the virtual host configuration and the certificate do not match, the P4V integration with P4 Code Review fails with the message `SSL handshake failed`.

   Also, when a reverse DNS lookup is performed, `myswarm.host` should be the answer when querying for the P4 Code Review server's IP address.

10. Validate that P4 Code Review is working correctly before using it in production, see Validate your P4 Code Review installation.

### Secure your P4 Code Review installation

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.

## Run P4 Code Review in a sub-folder of an existing web site

Multiple P4 Server instances on a single P4 Code Review instance: You cannot run P4 Code Review in a sub-folder if P4 Code Review is connected to multiple P4 Servers.

Issue: P4 Code Review will lose connection to all of the P4 Servers if you edit the base_url configurable value in the environment block of <swarm_root>/data/config.php. This will stop your system working.

Fix: Remove the base_url configurable from the environment block of <swarm_root>/data/config.php.

Back up your P4 Code Review virtual host configuration before customizing your P4 Code Review installation, see Back up your P4 Code Review virtual host first.

If you cannot run P4 Code Review in its own virtual host, which might be necessary when you do not control the hostname to be used with P4 Code Review, installing P4 Code Review in a sub-folder of an existing virtual host configuration can be a good solution.

Installing P4 Code Review in a sub-folder requires modification of the previous installation steps covered in this chapter:

- The Apache configuration is entirely different; instead of establishing a new virtual host, you need to modify an existing virtual host configuration. Often, this would be Apache's default site.
- P4 Code Review's configuration file requires an extra item.

The following sections cover the specifics of sub-folder installation.

See base_url for more details.

If you used the P4 Code Review packages to install P4 Code Review, you can adjust P4 Code Review's configuration using the package configuration script `/opt/perforce/swarm/sbin/configure-swarm.sh`.

`configure-swarm.sh` does not read any existing P4 Code Review configuration; you must provide all of the configuration details each time you execute `configure-swarm.sh`:

    $ sudo /opt/perforce/swarm/sbin/configure-swarm.sh -n -p myp4host:1666 -u swarm -w password -e mx.example.com -H myhost -B /swarm

In the example above, the `-B` option is used to specify the name of the sub-folder.

If you use `configure-swarm.sh` to adjust the Swarm configuration, you only need to follow the Apache configuration steps described below; all of the changes listed in the P4 Code Review configuration section below have been completed by `configure-swarm.sh`.

### Apache configuration

1. Ensure that the `SWARM_ROOT` is not within the document root of the intended virtual host.

   This step ensures that P4 Code Review's source code and configuration is impossible to browse, preventing access to important details such as stored credentials, and active sessions and workspaces.

2. Adjust the virtual host configuration that you are already using.

   Depending on the method used to install P4 Code Review, the filename for virtual host configuration you need to edit is:

   - For P4 Code Review package installations, edit `perforce-swarm-site.conf`.
   - For manual installations following P4 Code Review's recommended Apache configuration edit `swarm`.
   - For other installations, you may have to edit `httpd.conf` or nearby files.

   Add the following lines to the virtual host definition:

       Alias "/swarm" "SWARM_ROOT/public"

       DocumentRoot "/var/www/html"

       <Directory "SWARM_ROOT/public">
         AllowOverride All
         Require all granted
       </Directory>

   The `Alias` line configures Apache to respond to requests to `https://myhost/swarm` with content from P4 Code Review's `public` folder. You can change the `/swarm` portion of the Alias line to anything you want.

   The DocumentRoot line configures the Apache DocumentRoot directory location.

   The `<Directory>` block grants access to everything within P4 Code Review's `public` folder. Replace `SWARM_ROOT` with the actual path to P4 Code Review.

3. Restart your web server.

       $ sudo apachectl restart

### P4 Code Review configuration

To successfully operate within a sub-folder, the `swarm_root/data/config.php` file needs to be adjusted to contain the following lines (as a peer of the p4 item):

    	'environment' => array(
    		'base_url' => '/swarm'
    	),

Ensure that `/swarm` matches the first item in the `Alias` line in the virtual host configuration.

See Environment for more details.

### P4 Code Review trigger configuration

The swarm-trigger.conf file must be updated to include the base_url in the SWARM_HOST path.

The location of the swarm-trigger.conf depends on your installation. For information on the location of the swarm-trigger.conf file, see Set up P4 Code Review triggers with a Windows or Linux-hosted P4 Server.

1. Edit the swarm-trigger.conf file.
2. Replace:

SWARM_HOST="http://my-swarm-host"

With:

SWARM_HOST="http://website-hostname/swarm"

3. Save the file.

### Cron configuration

P4 Code Review's recurring task configuration must be updated to reflect the sub-folder that you have configured in Apache's and P4 Code Review's configurations. This is configured in the swarm-cron-hosts.conf file.

1. Edit `/opt/perforce/etc/swarm-cron-hosts.conf`.

2. Replace:

       https://swarm-host

   with:

       https://swarm-host/swarm/

   Where `swarm-host` is the hostname of your P4 Code Review installation, and `swarm` is the sub-folder you want to use.

3. Save the edited file.

   New workers should be started at the start of the next minute.

4. Validate that P4 Code Review is working correctly before using it in production, see Validate your P4 Code Review installation.

## Run the P4 Code Review virtual host on a custom port

Back up your P4 Code Review virtual host configuration before customizing your P4 Code Review installation, see Back up your P4 Code Review virtual host first.

If you cannot run Swarm on port 80 (or port 443 for HTTPS), perhaps because you do not have root access, it is possible to run P4 Code Review on a custom port.

Installing P4 Code Review to use a custom port requires modification of the previous installation steps covered in this chapter: The Apache configuration is slightly different, requiring modification of P4 Code Review's virtual host definition.

The following section covers the specifics of the custom port configuration.

In addition to the following instructions, you may also need to apply the `external_url` item described in the Environment section if your P4 Code Review is behind a proxy, or you have multiple P4 Code Review instances connected to P4 Server.

If you used the P4 Code Review packages to install P4 Code Review, you can adjust P4 Code Review's configuration using the package configuration script `/opt/perforce/swarm/sbin/configure-swarm.sh`.

`configure-swarm.sh` does not read any existing P4 Code Review configuration; you must provide all of the configuration details each time you execute `configure-swarm.sh`:

    $ sudo /opt/perforce/swarm/sbin/configure-swarm.sh -n -p myp4host:1666 -u swarm -w password -e mx.example.com -H myhost -P 8080

In the example above, the `-P` option is used to specify the custom port that P4 Code Review should use.

If you use `configure-swarm.sh` to adjust P4 Code Review's configuration, follow the additional steps that it describes. Once those steps are complete, do not perform any of the steps described below.

### Apache configuration

1. Edit the virtual host configuration.

   Depending on the method used to install P4 Code Review, the filename for virtual host configuration you need to edit is:

   - For P4 Code Review package installations, edit `perforce-swarm-site.conf`.
   - For manual installations following P4 Code Review's recommended Apache configuration, edit `swarm`.
   - For other installations, you may have to edit `httpd.conf` or nearby files.

   1. Add the following line outside of the `<VirtualHost>` block:

          Listen 8080

   2. Edit the `<VirtualHost *:80>` line to read:

          <VirtualHost *:8080>

   For both lines, replace `8080` with the custom port you wish to use.

   If you choose a port that is already in use, Apache refuses to start.

2. Restart your web server.

       $ sudo apachectl restart

3. Adjust your firewall configuration to allow connections to the custom port.

   - For RHEL:

         $ sudo firewall-cmd --zone=public --add-port=8080/tcp --permanent
         $ sudo systemctl reload firewalld

     Replace `8080` with the custom port you wish to use.

   - For other distributions, consult with your network administrator or operating system documentation to determine how to just your firewall configuration.

### Cron configuration

P4 Code Review's recurring task configuration must be updated to reflect the custom port that you have configured in Apache's configuration. This is configured in the swarm-cron-hosts.conf file.

1. Edit `/opt/perforce/etc/swarm-cron-hosts.conf`.

2. Replace:

       https://swarm-host:80

   with:

       https://swarm-host:8080

   Where `swarm-host` is the hostname of your P4 Code Review installation, and `8080` is the custom port you want to use.

3. Save the edited file.

   New workers should be started at the start of the next minute.

4. Validate that P4 Code Review is working correctly before using it in production, see Validate your P4 Code Review installation.

## Use your own Redis server

By default P4 Code Review uses its own Redis server on the P4 Code Review machine.

This section describes how to connect P4 Code Review to your own Redis server.

To use your own Redis server:

1. Add the redis block to the `SWARM_ROOT/data/config.php` file, it contains the password, namespace, host, and port details of your 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' => 'MyRedisServerHostname', // Defaults to 'localhost' or enter your Redis server hostname
                    'port' => 'MyRedisServerPortNumber', // 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.
        ),

- password: set to the password of your Redis server, defaults to null
- namespace: the prefix used for key values in the Redis cache. Defaults to Swarm.

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

If one or more of your P4 Code Review instances is connected to multiple P4 Servers, the Redis namespace includes the server label and the character limit is reduced to ≤ 127 characters, see Multiple P4 Server instances.

- host MyRedisServerHostname: Redis server host name
- port MyRedisServerPortNumber: Redis server port number
- 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.

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 P4 Server when P4 Code Review is down or if errors occur during updates, the Redis cache can get out of sync with the P4 Server. P4 Code Review can run a regular integrity check to make sure that the Redis caches and P4 Server are in sync. If an integrity check finds an out of sync cache file, P4 Code Review 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 P4 Code Review system, increase this time if the initial cache population times out. Defaults to 300 seconds.

2. Edit the Redis server configuration in the /opt/perforce/etc/redis-server.conf file:

    bind MyRedisServerHostname
    port MyRedisServerPortNumber
    supervised auto
    save ""
    dir /MyRedis/CacheDatabase/Directory/Location

- bind MyRedisServerHostname - Redis server host name
- port MyRedisServerPortNumber - 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 /MyRedis/CacheDatabase/Directory/Location - the directory the Redis cache database is stored in

- The redis-server.conf file contains more detailed information about the Redis configuration for P4 Code Review.
- On P4 Code Review 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.

P4 Code Review is now connected to your Redis server and your P4 Code Review installation is complete.

3. Validate that P4 Code Review is working correctly before using it in production, see Validate your P4 Code Review installation.

## Hiding P4 Code Review storage from regular users

P4 Code Review information storage uses P4 Server's `keys` facility. By default, users with list-level access can search keys and potentially obtain information they would not otherwise have access to, and users with review-level access can write or modify keys potentially corrupting or destroying data.

We recommend that you set the `dm.keys.hide` configurable to 2 to require admin-level access for searching and modifying keys. Note that `dm.keys.hide` is available in P4 Server versions 2013.1 and newer.

When `dm.keys.hide` is set to 2, both the `p4 keys` and `p4 key` commands require admin-level access in the P4 Server. When `dm.keys.hide` is set to 1, only the `p4 keys` command requires admin-level access in the P4 Server. When `dm.keys.hide` is set to 1, or is not set, users who know (or can deduce) key names can read values (if they have list-level access) or write values (if they have review-level access) with the `p4 key` command.

To set `dm.keys.hide`:

p4 configure set dm.keys.hide=2

To confirm the current value of `dm.keys.hide`:

p4 configure show dm.keys.hide

To unset `dm.keys.hide`:

p4 configure unset dm.keys.hide

### Next step

Validate that P4 Code Review is working correctly before using it in production, see Validate your P4 Code Review installation.

## Handling Exclusive Locks

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.

P4 Code Review takes copies of files when it is creating reviews. Some of the files managed by P4 Server may be limited to 'exclusive open' by having the filetype modifier '+l' set. This file-level setting ensures only one user at a time can open the file for editing.

To allow P4 Code Review to work with these 'exclusive open' files, you must enable `filetype.bypasslock` in the P4 Server configuration.

To set filetype.bypasslock:

p4 configure set filetype.bypasslock=1

To confirm the current value of `filetype.bypasslock`:

p4 configure show filetype.bypasslock

To unset `filetype.bypasslock`:

p4 configure unset filetype.bypasslock

### Next step

Validate that P4 Code Review is working correctly before using it in production, see Validate your P4 Code Review installation.

Your search for returned results