Swarm configuration

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

Important

Swarm does not support Helix Servers configured to use P4AUTH, see Centralized authentication server (P4AUTH) in the Helix Core Server Administrator Guide.

Note
  • Swarm can be connected to Helix Servers (P4D) and commit servers.

    • To configure Swarm to connect to more than one Helix Server (P4D), see Multiple-Helix Server instances.

    To configure Swarm to connect to a Helix Server configured to use commit-edge architecture, see Commit-edge deployment.

  • Swarm must not be connected to Helix Broker, Helix Proxy, Helix Edge, forwarding replica, or read-only replica servers.

Swarm configuration file

Important

  • If your Helix Server is configured for Helix Authentication Service, 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

Edit the SWARM_ROOT/data/config.php file so that it contains the following configuration block:

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

port

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.

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.

user

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.
  • Helix Server 2020.1 and later, permissions have changed for viewing and editing stream spec files in Swarm. To view and edit stream spec files in Swarm, the Swarm user must have admin permissions for the entire depot //...

password

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 Authentication Service.

  • You must use a long-lived login ticket for the Swarm user.

You can determine when the admin userid 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.

sso

Swarm can be configured for the Helix Authentication Service when the Helix Server is also configured for the Helix Authentication Service.

Set sso to one of the following:

  • enabled all users must use Helix Authentication Service to log in to Swarm.

  • optional Helix Authentication Service is available for users to log in to Swarm but is not enforced.

  • disabled Helix Authentication Service is not available to Swarm. This is the default value.

Important

From Swarm 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, Swarm uses the sso configurable value.

host

For the host value, replace my.mx.host with the hostname of the mail exchange 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.

Next step

Configure the Helix Server to notify Swarm about Helix Server events, see Configuring Helix Core Server event notification.