Multiple-Helix Server instances

Typically an organization only requires a single Helix Core Server but there are situations when you might have multiple-Helix Servers in your organization. A single Swarm server can be connected to a number of Helix Core Server (P4D) instances. This section describes how to configure Swarm to connect to multiple Helix Servers.

Complete the following steps to connect Swarm to multiple-Helix Server instances:

• Set up the Swarm configuration file for the Helix Servers
• Set the Swarm trigger token and Swarm host variable for each Helix Server
• Configure a cron job for each Helix Server instance

Set up the Swarm configuration file for the Helix Servers

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

When Swarm is configured for a single Helix 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_enabled' => false, // defaults to false
         ),
    );

Where:

• port is the P4PORT for your Helix Server.
• user is a userid that has admin privileges for the Helix Server.
• password is the ticket or password for the Helix Server user.
• sso_enabled set to true if the Helix Server is configured for Helix SAML.
Important
To use Helix SAML with Swarm:
• Helix Server version 2018.2 or later is required.
• Write a Helix Server trigger for Helix SAML. For instructions on developing the Helix Server trigger for Helix SAML, see Triggering to use external authentication in Helix Core Server Administrator Guide: Fundamentals.
• Enable Helix SAML in Swarm with the sso_enabled configurable, see Swarm configuration.
• Configure the Swarm admin user to use ticket-based authentication, see Swarm configuration.
• Configure Swarm for Helix SAML. For instructions on how to configure Swarm for Helix SAML, see Helix SAML authentication PHP config.

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

The first Helix Server in the p4 item is the primary Helix Server. If Swarm fails to connect to this Helix Server, Swarm will not be able to connect to any of the other Helix Server instances in p4.

Configure the Swarm configuration file for multiple Helix Server instances:

Enter a label for each Helix 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_enabled' => false, // defaults to false
        ),
        'serverB' => array(
            'port'      => 'p4d-B:1666',
            'user'      => 'admin_userid_serverB',
            'password'  => 'admin user ticket or password for serverB',
            'sso_enabled' => true, // defaults to false
        ),		
    );

Where:

• serverA and serverB are labels that identify the individual Helix Servers. The labels must be URL-friendly labels, the labels must not contain any spaces or any characters that require URL encoding.
• The port, user, password, and sso_enabled items are specific to the Helix Server instance they are nested under.

Set the Swarm trigger token and Swarm host variable for each Helix Server

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

Set the Swarm trigger token and Swarm host variable for each Helix Server instance:

1. Navigate to the Swarm URL for the instance.

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

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

The About Swarm dialog is displayed with a Trigger Token. Swarm 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 Helix Server instance.
Tip

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

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

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 Helix Server.

Configure a cron job for each Helix Server instance

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

Swarm package and OVA installations only

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

If you have installed Swarm via packages or you are running the Swarm OVA, you must specify all of the Helix Server URLs within /opt/perforce/etc/swarm-cron-hosts.conf.

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

The following format is used with one Helix 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 Swarm 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. Swarm is now configured to connect to multiple-Helix Server instances.
Tip

To check or modify Swarm worker configuration, see Worker configuration.

Swarm Tarball installation only

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

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:

#
# 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 Swarm hostname, ports, and server labels you have configured for Swarm.

The following format is used with one Helix 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 Swarm 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. Swarm is now configured to connect to multiple-Helix Server instances.
Tip

To check or modify Swarm worker configuration, see Worker configuration.

Further information

Users

• To visit the Global Dashboard, enter the basic Swarm URL without a Helix Server instance name, for example: https://swarm.company.com
• To visit a specific Helix Server instance in Swarm 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 Helix Server in Swarm, Swarm works as a standard single Helix ServerSwarm system.

Administrators

On the web server hosting Swarm, Swarm automatically creates a data folder for each Helix Server instance in <Swarm_root>/data/servers. This is because each Helix 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

Developers

To get a list of projects via the Swarm API for serverA, run bash:

• If you are using wget:

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

• If you are using curl:

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