Multiple P4 Server instances

A single P4 Code Review server can be connected one or more P4 Server (P4D) instances. This section describes how to configure P4 Code Review to connect 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.

Known limitations, only applies if you want to use Global Dashboard:

  • Issue: If P4 AS is enabled for P4 Code Review and the Try to login to all available servers with these credentials checkbox or the All available servers option is selected in a login dialog, P4 Code Review will not try to log in to any of the other P4 Server instances that are configured for P4 AS.

    • Workaround: Log in to them individually using the instance Log in button Image of the global dashboard log in button in the sidebar or by including the server instance name in the URL, for example: https://swarm.company.com/serverA.

  • P4 Code Review must be installed in its own virtual host.

Complete the following steps to connect P4 Code Review to multiple P4 Server instances:

Set up the P4 Code Review configuration file for the P4 Servers

The P4 Code Review P4 Server connection details are configured using the p4 item in the <swarm_root>/data/config.php configuration file.

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.

When P4 Code Review is configured for a single P4 Server instance the p4 item looks like this: 

<?php
    return array(
        'p4' => array(
            'port'     => 'my-helix-core-server:1666',
            'user'     => 'admin_userid',
            'password' => 'admin user ticket or password',
            'sso'      => 'disabled', // ['disabled'|'optional'|'enabled'] default value is 'disabled' 
         ),
    );

Where:

  • port is the P4PORT for your P4 Server.
  • user is a userid that has admin privileges for the P4 Server.
  • password is the ticket or password for the P4 Server user.
  • sso if the P4 Server is configured for the P4 AS, set to one of the following:

    • enabled all users must use P4 AS to log in to P4 Code Review.

    • optional P4 AS is available for users to log in to P4 Code Review but is not enforced.

    • disabled P4 AS is not available to P4 Code Review. This is the default value.

    • From P4 Code Review 2021.1, the sso_enabled configurable is deprecated but remains supported. It is replaced with the more flexible sso configurable. If the sso_enabled configurable and sso configurable are both present in the p4 configuration block, P4 Code Review uses the sso configurable value.

Multiple P4 Server instances can be added to the p4 item in config.php but each P4 Server instance must have a label to identify the server instance. This enables P4 Code Review to connect to the P4 Servers in the p4 item.

The P4 Server instances do not have to all be at the same version but they must all be versions that P4 Code Review supports. For a list of P4 Server versions supported by P4 Code Review, see P4 Server requirements.

The first P4 Server in the p4 item is the primary P4 Server, this instance renders the global dashboard. If P4 Code Review fails to connect to the primary P4 Server, P4 Code Review cannot display any of the P4 Server instances in the global dashboard. You can still connect directly to the other P4D instances by including the P4 Server label in the URL for each instance, for example: https://swarm.company.com/serverA.

Configure the P4 Code Review configuration file for multiple P4 Server instances:

Enter a label for each P4 Server instance and enter the server connection details under the server label.

For example:

<?php
    return array(
        'p4' => array(
            'serverA' => array(
                'port'     => 'p4d-A:1666',
                'user'     => 'admin_userid_serverA',
                'password' => 'admin user ticket or password for serverA',
                'sso'      => 'disabled', // ['disabled'|'optional'|'enabled'] default value is 'disabled' 
            ),
            'serverB' => array(
                'port'     => 'p4d-B:1666',
                'user'     => 'admin_userid_serverB',
                'password' => 'admin user ticket or password for serverB',
                'sso'      => 'disabled', // ['disabled'|'optional'|'enabled'] default value is 'disabled' 
            ),		
        );

Where:

  • serverA and serverB are labels that identify the individual P4 Servers.
    • The labels must be URL-friendly labels.
    • The labels must not contain any spaces or any characters that require URL encoding, and
    • The total length of the server label and Redis namespace combined is limited to ≤ 127 characters. The default namespace is Swarm.
  • The port, user, password, and sso items are specific to the P4 Server instance they are nested under.

Configure a specific P4 Server

The root element in the <swarm_root>/data/config.php configuration file contains default values for all P4 Server instances. You can override the default values by using a server specific configuration file. For example, to override the global value of jira configuration for a specific server, you can provide a different value for jira configuration in the server specific configuration file.

To configure a specific P4 Server instance, add a config.php file in the <swarm_root>/data/servers/<serverid> directory. For the new P4 Server configuration to take effect, the configuration cache must be deleted and reloaded. For more information on how to delete and reload cache, see Cache Info.

  • You must include a global config.php file to specify the multiple P4 Server instances.

  • You must ensure that a p4 item is not included in the P4 Server specific configuration. If the p4 item is included, no error message is displayed and the p4 item is ignored by the P4 Server.

P4 Server specific configuration overrides the global configuration.

Configure event notification for each P4 Server

You must use either P4 Server Extensions (recommended) or P4 Server Triggers to notify P4 Code Review about events on the P4 Servers. You cannot use a mixture of the two methods.

Triggers are still supported, but we recommend you use P4 Server Extensions. P4 Server Extensions are easier to install and maintain than Triggers.

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 (recommended) or P4 Server Triggers. P4 Code Review installs include the P4 Code Review 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 and configure the P4 Code Review P4 Server extension or Triggers to complete the P4 Code Review configuration.

Do one of the following so that P4 Code Review is notified about events on the P4 Servers it is connected to:

Install and configure the P4 Code Review P4 Server extension (recommended)

  • If you are using the P4 Code Review P4 Server extension, P4 Code Review P4 Server Triggers must not be installed.

  • The following commands must be run on each P4 Server instance P4 Code Review is connected to.

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

Prerequisites

To install the P4 Code Review P4 Server extension you need:

A compatible version of P4 Server for P4 Server Extensions:

  • 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:

  • Extensions installed and configured on your P4 Server.

  • A user with super permissions to install and configure the P4 Code Review P4 Server extension.

P4 Code Review P4 Server extension installation

The P4 Code Review P4 Server extension file is included for all of the P4 Code Review installation types. The helix-swarm.p4-extension file is located in swarm_root/p4-bin/extensions

On each P4 Server you are connecting P4 Code Review to, run the following commands as a P4 Server user with super permissions:

  1. Install the P4 Code Review P4 Server extension on the P4 Server with:

    2. p4 extension --yes --install helix-swarm.p4-extension

    Example response: 

    Extension 'Perforce::helix-swarm' version '2022.1.20221215' installed successfully.
Perform the following steps to turn on the Extension:

# Create a global configuration if one doesn't already exist.
p4 extension --configure Perforce::helix-swarm

# Create an instance configuration to enable the Extension.
p4 extension --configure Perforce::helix-swarm --name Perforce::helix-swarm-instanceName

For more information, visit: https://www.perforce.com/manuals/extensions/Content/Extensions/Home-extensions.html

  2. Create a global configuration if one doesn't already exist:

    p4 extension --configure Perforce::helix-swarm

    The spec file opens in your text editor, for example: 

    ExtName:        helix-swarm
ExtDescription:
        Helix Swarm Extension
 
ExtVersion:     2022.1.DEV.20220120
 
ExtUUID:        4532BC59-7BC8-478F-ADF6-0A563C42563D
 
ExtRev: 1
 
ExtMaxScriptTime:       unset
 
ExtMaxScriptMem:        unset
 
ExtAllowedGroups:
 
ExtEnabled:     true
 
ExtP4USER:      sampleExtensionsUser
 
Name:   helix-swarm
 
Owner:  super
 
Update: 2022/01/21 10:43:46
 
Description:
        The description of your config.
 
ExtConfig:
        Debug:
                2
        Swarm-Secure:
                true
        Swarm-Token:
                SWARM-TOKEN
        Swarm-URL:
                http://localhost/

  3. Edit the spec file to match your system:

    • ExtP4USER: Set to an existing user with super permissions.

    • ExtConfig: Check and edit the values in this block:

      • Debug:

        Debug levels 0 to 3 control the amount of debug information sent to the P4 Server Extensions log.

        A debug level of 10 and higher sends all debug information to the client. This is useful for debugging, but should not be run in a production environment.

      • SSL-CA-File: (optional) Set the absolute path of the Certificate Authority (CA) Privacy-Enhanced Mail (PEM) file to validate the P4 Code ReviewP4 Server's certificate. Ensure that this file is accessible to the Helix Core Server process owner.

        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.

        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.

      • Swarm-Secure:

        • true will only accept secure SSL certificates.

        • false will accept insecure SSL certificates.

      • Swarm-Token: Set to the P4 Code Review trigger token value.

        To set multiple P4 Server token settings for Extensions, repeat the following steps for each P4 Server. The process to obtain an extension token of your P4 Code Review instance is similar to obtaining a trigger token of your P4 Code Review instance.

        To obtain the trigger token of your P4 Code Review instance:

        1. Log in to P4 Code Review as a super user.

        2. Click your userid, found at the right of the main toolbar.

        3. Select About P4 Code Review.

        4. The About P4 Code Review dialog is displayed and P4 Code Review generates an API token if it doesn't already exist.

        5. Copy the trigger token value displayed at the bottom of the dialog and paste the token into the spec file.

      • Swarm-URL: Set to the URL of your P4 Code Review instance.

  4. When you have finished editing the spec file, save it in your text editor.

  5. Create an instance configuration to enable the extension:

    p4 extension --configure Perforce::helix-swarm --name swarm

    The spec file opens in your text editor, for example: 

    ExtName:        helix-swarm
 
ExtDescription:
        Helix Swarm Extension
 
ExtVersion:     2022.1.DEV.20220120
 
ExtUUID:        4532BC59-7BC8-478F-ADF6-0A563C42563D
 
ExtRev: 1
 
ExtMaxScriptTime:       unset

ExtMaxScriptMem:        unset
 
ExtEnabled:     true
 
ExtDebug:       none
 
Name:   swarm
 
Owner:  super
 
Update: 2022/01/21 10:58:41

Description:
        The description of your config.

ExtConfig: 
        depot-path:
                //...
        enableStrict:
                true
        enableWorkflow:
                true
        httpTimeout:
                30
        ignoreErrors:
                false

    We recommend that these settings are left at their default values, but the configuration needs to be run to set the default values.

    • enableStrict: Enable strict checking of reviews for workflow. Verifies that the file content in a commit matches the file content of its associated approved review. If one or more files in a commit do not match the content of the file in its associated review, the commit is rejected.

    • enableWorkflow: Enable workflow.

    • httpTimeout: Timeout (in seconds) when communicating with the P4 Code Review server.

    • ignoreErrors: If the server returns an error (timeout, not there), then default to allowing a request. It means workflow rules can be skipped, but if the P4 Code Review server is down it will not block submits.

  6. Save the spec file in your text editor.

  7. Confirm your P4 Code Review P4 Server extension is installed and configured by running the following command on the P4 Server:

    8. p4 extension --run swarm ping

    • If the P4 Code Review P4 Server extension is working, the P4 Server responds with OK

    • If the P4 Code Review P4 Server extension is not working, the P4 Server responds with an error message. For example, BAD (Cannot reach https://swarm-example.com/)

      • For more information about P4 Server Extensions, see:

  8. Repeat these steps for each P4 Server.
  9. When you have configured all of the P4 Servers, configure a cron job to start P4 Code Review workers for each P4 Server instance, see Configure a cron job for each P4 Server instance.

Set the P4 Code Review trigger token and P4 Code Review host variable for each P4 Server

If you are using P4 Code Review P4 Server Triggers, the P4 Code Review P4 Server extension must not be installed.

P4 Server uses a P4 Code Review trigger token to confirm that trigger requests from P4 Code Review are valid. Each P4 Server instance must have a valid P4 Code Review trigger token in its swarm-trigger.conf file. The swarm-trigger.conf file also contains the P4 Code Review host URL for the P4 Server instance.

Set the P4 Code Review trigger token and P4 Code Review host variable for each P4 Server instance:

  1. Navigate to the P4 Code Review URL for the instance.

    2. For example: https://swarm.company.com/serverA

  2. Log in to P4 Code Review as a super user.
  3. Click your userid, in the main toolbar and select About P4 Code Review.

    4. The About P4 Code Review dialog is displayed with a Trigger Token. P4 Code Review generates the trigger token if it doesn't already exist.

  4. Copy the trigger token value from the dialog.
  5. Open the swarm-trigger.conf file for the P4 Server instance.

    6. For more information about the location of the swarm-trigger.conf file, see Set up P4 Code Review triggers with a Windows or Linux-hosted P4 Server.

  6. In the swarm-trigger.conf file:
    1. Set the SWARM_HOST URL.
    2. Set the SWARM_TOKEN by pasting the P4 Code Review trigger token you copied in the steps above.

    7. For example:

    # SWARM_HOST (required)
# Hostname of your Swarm instance, with leading "http://" or "https://".
SWARM_HOST="https://swarm.company.com/serverA"

# 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="TRIGGER-TOKEN-FOR-SERVERA"

  7. Save the swarm-trigger.conf file.
  8. Repeat these steps for each P4 Server.
  9. When you have configured all of the P4 Servers, configure a cron job to start P4 Code Review workers for each P4 Server instance, see Configure a cron job for each P4 Server instance.

Alternatively, you can simply touch a file in each <Swarm root>/data/servers/<serverid>/tokens folder. The file content is ignored, the filename itself is the token.

This allows you to specify a common token that is used by all of the P4 Server instances.

However, we recommend that you use a separate token for each P4 Server instance. This makes it easier to invalidate a token for a specific P4 Server by deleting the file in the tokens folder for that server if you need to.

Configure a cron job for each P4 Server instance

To automatically spawn workers for each of the servers connected to P4 Code Review, you must manually configure a cron job for each of the servers.

Swarm package installations only

The swarm-cron-hosts.conf file specifies the connection type (HTTP or HTTPS), hostname, port number and, server label for P4 Code Review cron jobs.

If you have installed P4 Code Review via packages, you must specify all of the P4 Server URLs within /opt/perforce/etc/swarm-cron-hosts.conf.

  1. Edit the swarm-cron-hosts.conf file so that it contains the actual P4 Code Review hostname, ports, and server labels you have configured for P4 Code Review.

    2. The following format is used with one P4 Server on each line: 

    [http[s]://]<swarm-host>[:<port>][/<base-url>]

    Default if value not specified:

    • [http[s]://] http
    • <swarm-host> must be specified
    • [:<port>] 80
    • [/<base-url>] server label, must be specified

    For example, for serverA and serverB configured earlier on a P4 Code Review host of https://swarm.company.com with a default port value of 80. The entries in the swarm-cron-hosts.conf file would be:

    https://swarm.company.com/serverA
https://swarm.company.com/serverB
  2. Save the swarm-cron-hosts.conf file.
  3. P4 Code Review is now configured to connect to multiple P4 Server instances.

    4. To check or modify P4 Code Review worker configuration, see Worker configuration.

P4 Code Review Tarball installation only

If you have installed P4 Code Review from a tarball or configured cron manually, you need create a file called helix-swarm and add all of the P4 Server instances connected to P4 Code Review.

  1. Create a file named helix-swarm in /etc/cron.d if it does not already exist.
  2. Edit the helix-swarm file so that it has the following content: 

    3. #
# Cron job to start Swarm workers every minute
#
* * * * * nobody [ -x /opt/perforce/swarm/p4-bin/scripts/swarm-cron.sh ] && /opt/perforce/swarm/p4-bin/scripts/swarm-cron.sh

  3. Save the helix-swarm file.
  4. Edit the swarm-cron-hosts.conf file so that it contains the actual P4 Code Review hostname, ports, and server labels you have configured for P4 Code Review.

    5. The following format is used with one P4 Server on each line: 

    [http[s]://]<swarm-host>[:<port>][/<base-url>]

    Default if value not specified:

    • [http[s]://] http
    • <swarm-host> must be specified
    • :<port> 80
    • [/<base-url>] server label, must be specified

    For example, for serverA and serverB configured earlier on a P4 Code Review host of https://swarm.company.com with a default port value of 80. The entries in the swarm-cron-hosts.conf file would be:

    https://swarm.company.com/serverA
https://swarm.company.com/serverB
  5. Save the swarm-cron-hosts.conf file.
  6. P4 Code Review is now configured to connect to multiple P4 Server instances.

    7. To check or modify P4 Code Review worker configuration, see Worker configuration.

Further information

Users

  • To visit the Global Dashboard, enter the basic P4 Code Review URL without a P4 Server instance name, for example: https://swarm.company.com.
  • To visit a specific P4 Server instance in P4 Code Review without going via the global dashboard, include the server name in the URL, for example: https://swarm.company.com/serverA.

Once you are viewing the P4 Server in P4 Code Review, P4 Code Review works as a standard single P4 ServerP4 Code Review system.

  • To browse jobs on serverA, navigate to: https://swarm.company.com/serverA/jobs
  • To browse reviews on serverB, navigate to: https://swarm.company.com/serverB/reviews
  • To view the dashboard for serverB, navigate to https://swarm.company.com/serverB/#actionable-reviews
  • If you don't include the server label in the URL you will be taken to the specified page for the primary P4 Server.

    • For example: navigating to https://swarm.company.com/reviews will redirect you to https://swarm.company.com/serverA/reviews because serverA is the Primary P4 Server in the p4 configuration item.

Administrators

On the web server hosting P4 Code Review, P4 Code Review automatically creates a data folder for each P4 Server instance in <Swarm_root>/data/servers. This is because each P4 Server request is a field.

For example:

# ls -la /opt/perforce/swarm/data/servers/serverA
total 362296			
drwx------ 6 apache apache    4096 Sep  8 17:15 .
drwx------ 6 apache apache    4096 Sep  6 15:41 ..
drwx------ 2 apache apache    4096 Sep 20 18:08 cache
drwx------ 3 apache apache    4096 Sep  7 13:25 clients
-rw-r--r-- 1 apache apache 3709543 Sep 26 14:19 log
-r-------- 1 apache apache      84 Sep  6 15:41 p4trust
drwx------ 4 apache apache    4096 Sep 20 14:27 queue
drwx------ 2 apache apache    4096 Sep 20 11:18 sessions

It is important to understand that there will be a P4 Code Review log file for each P4 Server instance.

Developers

To get a list of projects via the P4 Code Review API for serverA, run bash:

  • If you are using wget:

    $ wget -u "apiuser:password" https://swarm.company.com/serverA/api/v11/projects

  • If you are using curl:

    $ curl -u "apiuser:password" https://swarm.company.com/serverA/api/v11/projects

If you don't include the server label in the URL you will be taken to the projects page for the primary P4 Server.

For example: navigating to https://swarm.company.com/api/v11/projects will redirect you to https://swarm.company.com/api/v11/serverA/projects because serverA is the Primary P4 Server in the p4 configuration item.