Helix Swarm Guide (2018.3)

Swarm configuration

Now that Swarm is ready for use, you need to configure it to work in your environment.

Note

Helix Core Server can refer to a Helix Server machine (p4d), proxy, broker, replica, edge server, or commit server. For simplicity, the term Helix Server is used to refer to any configuration of a Helix Core Server machine.

Swarm configuration file

Important

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

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

Create a file named config.php under the data directory with the following contents:

<?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
         ),
         'log' => array(
             'priority'  => 3, // 7 for max, defaults to 3
         ),
         'mail' => array(
             'transport' => array(
                 'host' => 'my.mx.host',
             ),
         ),
    );

For the port value, replace my-helix-core-server:1666 with the P4PORT value used to connect to your Helix Server.

Important
If your Helix Server is deployed using the commit-edge architecture, ensure that Swarm's port value points to the commit server.

For more information, see Commit-edge in the Helix Core Server Administrator Guide: Multi-Site Deployment.

Warning
If the port points to a Helix Broker, ensure that the broker does not delegate commands to different replicas, edge servers, or proxies. Such delegation can cause odd problems or outright failures in Swarm.

Swarm needs to have a consistent, current view of the state of Helix Server, and works best when it connects to a central/commit server.
For the user value, replace admin_userid with a normal Helix Server userid that has admin-level access to Helix Server.

Note

This user is used by Swarm to communicate with the Helix Server. It should not be used to perform everyday Swarm reviewing tasks.

For the password value, while a plain-text password works, we recommend that you use a ticket value instead. Obtain the ticket value for the admin_userid during login with this command:
```
$ p4 -p my-helix-core-server:1666 -u admin_userid login -p
```
Important
If your Helix Server authentication is configured in the one of the following ways, ticket-based authentication is required:
- Authentication configured with security level 3.
- Authentication configured for LDAP.
- Authentication configured for Helix SAML.
You can determine when the admin userid's ticket will expire with:
```
$ p4 -p my-helix-core-server:1666 -u admin_userid -P ticket_value login -s
```
For more information about tickets, see the section Ticket-based authentication in the Helix Core Server Administrator Guide: Fundamentals.
Swarm can be configured for Helix SAML when the Helix Server is configured for Helix SAML.

To enable Helix SAML in Swarm, set sso_enabled to true.

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 as described on this page.
Configure the Swarm admin user to use ticket-based authentication as described on this page.
Configure Swarm for Helix SAML. For instructions on how to configure Swarm for Helix SAML, see Helix SAML authentication PHP config.

For the host value, replace my.mx.host with the hostname of the mail exchanger service that Swarm should use to send its email notifications.

Note

Since this configuration file contains the credentials for a Helix Server admin-level user, we recommend that this file's ownership and permissions be adjusted such that only the web server user can read the file, and that no user can write the file.

You can now configure some additional functionality for Swarm:
- Optional: JIRA integration, see JIRA.
- Optional: LibreOffice integration, see LibreOffice.
- Optional: Manually specify the Swarm hostname, see Swarm hostname.
Establish a trigger token, see Establish trigger token.

Optional additional Swarm configuration

Swarm provides optional functionality that could be enabled at this time:

Swarm hostname

Swarm normally auto-detects the hostname it operates under. In some system configuration, the auto-detection logic might not choose the correct hostname, such as when there are multiple virtual hosts configured for a single Swarm instance. When auto-detection chooses the wrong hostname, email notifications, worker start up, and more could be affected.

If you need to specify the Swarm hostname, see hostname for details.

Your search for returned result(s).