Helix Swarm Guide (2018.3)

Helix Core Server configuration for Swarm

Now that you have a configured instance of Swarm, the last piece is to configure your Helix Server to tell Swarm about interesting events. This is accomplished through the use of triggers.

For more information about Helix Server triggers, see Using triggers to customize behavior in Helix Core Server Administrator Guide: Fundamentals.

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.

Using triggers to push events to Swarm

Helix Server provides a facility called triggers to customize the operation of the server, or to invoke additional processing for specific kinds of versioning operations. Swarm provides a trigger script written in Perl that notifies Swarm about activity within the Helix Server.

See Trigger options for more information on configuring the Perl trigger.

Set up Swarm triggers with a CentOS/RHEL 6 hosted Helix Server

The latest updates to the trigger script require dependencies which are not available on version 6 of the CentOS/RHEL platform. If you are running the triggers on CentOS 6, then the triggers have a dependency on curl which may not be installed by default on a minimal install of CentOS 6.

Set up Swarm triggers with a Windows or Linux-hosted Helix Server

Tip

Many of the steps in this procedure are common to both Windows and Linux-hosted Helix Servers. When there is a difference between the Windows and Linux operating systems, this is indicated in the procedure.

Ensure that the required Trigger dependencies have been installed on the machine hosting the Helix Server.
Copy the Swarm trigger to the Helix Server

If your Helix Server is version 2014.1 (or later), we recommend submitting the trigger script, p4-bin/scripts/swarm-trigger.pl, to Helix Server and running it from the depot. The recommended depot location is //.swarm/triggers/swarm-trigger.pl, especially if you have already setup Comment attachments.
If your Helix Server is older than version 2014.1, or you prefer that the trigger file exist in the filesystem, you must copy the p4-bin/scripts/swarm-trigger.pl script to the server hosting Helix Server. If your Helix Server deployment uses the commit-edge architecture, the script must also be copied to all edge servers, and it must exist in the same path on all servers.

Note

If you are using the Swarm OVA, the full path to the trigger script within the OVA's filesystem is: /opt/perforce/swarm/p4-bin/scripts/swarm-trigger.pl

Configure the trigger.

You need to use the API token established in the Establish trigger token.

swarm-trigger.pl can be configured directly, but the preferred approach is to create a configuration file called swarm-trigger.conf. Using the configuration file greatly simplifies upgrades.

If you are using the Swarm triggers package described in Install and configure Swarm from a package, the configuration file is available at /opt/perforce/etc/swarm-trigger.conf, otherwise create swarm-trigger.conf in the same directory as swarm-trigger.pl.

If you submitted the trigger script to the depot in the previous step, you should similarly submit the configuration file to the depot. The recommended depot location is //.swarm/triggers/swarm-trigger.conf.
If you copied the trigger script to the commit server and all edge servers in the previous step, also copy the configuration file to the commit server and all edge servers, making sure that they exist in the same path on all servers.

The following is a sample of what your swarm-trigger.conf should contain:

# SWARM_HOST (required)
# Hostname of your Swarm instance, with leading "http://" or "https://".
SWARM_HOST="http://my-swarm-host"

# 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="MY-UUID-STYLE-TOKEN"

# ADMIN_USER (optional) Do not use if the Workflow technology preview feature is enabled:
# For enforcing reviewed changes, optionally specify the normal Perforce user
# with admin privileges (to read keys); if not set, will use whatever Perforce
# user is set in environment.
ADMIN_USER=

# ADMIN_TICKET_FILE (optional) Do not use if the Workflow technology preview feature is enabled:
# For enforcing reviewed changes, optionally specify the location of the
# p4tickets file if different from the default ($HOME/.p4tickets).
# Ensure this user is a member of a group with an 'unlimited' or very long
# timeout; then, manually login as this user from the Perforce server machine to
# set the ticket.
ADMIN_TICKET_FILE=				
				
# VERIFY_SSL (optional)
# If HTTPS is being used on the Swarm web server, then this controls whether
# the SSL certificate is validated or not. By default this is set to 1, which
# means any SSL certificates must be valid. If the web server is using a self
# signed certificate, then this must be set to 0.
VERIFY_SSL=1

Modify the swarm-trigger.conf configuration file to set the SWARM_HOST and the SWARM_TOKEN variables appropriately.

Note

Windows only:

You may need to edit the trigger script to specify the full path to curl.exe if the HTTP::Tiny module is not installed.

Note

Linux only:

swarm-trigger.pl looks for configuration in the following files. Variables defined in the later files will override the earlier defined variables of the same name:

Variables set inside the swarm-trigger.pl script itself
/etc/perforce/swarm-trigger.conf
/opt/perforce/etc/swarm-trigger.conf
The swarm-trigger.conf file stored in the same directory as swarm-trigger.pl
Any file passed to the swarm-trigger.pl script using the -c command line argument

Important

Windows and Linux:

If you specify ADMIN_USER, the ticket contained in %USERPROFILE%/p4tickets.txt (Windows), $HOME/.p4tickets (Linux), or the optional ticket file specified with the ADMIN_TICKET_FILE must use the port that was used to start Helix Server. For example, if p4d is started with:

C:\> p4d -p my-helix-core-server:1666 ...

then the ticket for the admin user specified with ADMIN_USER should be established with:

C:\> p4 -p my-helix-core-server:1666 -u admin_userid login

If the ticket was established using the wrong port, the error message you encounter includes the port that the trigger is attempting to use:

'swarm.strict.1' validation failed: Invalid login credentials to [port] within this trigger script; please contact your administrator.

Linux only: Ensure that the script has execute permissions.

Important
Skip this step if you have committed the script to the Helix Server.
```
$ chmod +x /path/to/swarm-trigger.pl
```
Verify that the trigger script executes correctly.
- For Windows:

For Linux:

Important

Skip this step if you have committed the script to the Helix Server.

$ /path/to/swarm-trigger.pl -t ping -v 0

You should expect to see no output. If the trigger is misconfigured, such as using an invalid trigger token, you would see an error.

Note

Run the trigger script without any arguments to see additional usage information.

Update the Helix Server triggers table to run the trigger script.

Important

The swarm.shelvedel shelve-delete trigger line was added to Swarm in version 2018.1 and later. Add the swarm.shelvedel shelve-delete trigger line to the Helix Server trigger table if it is not already present.
Workflow technology preview feature: If the workflow technology preview feature is disabled these trigger lines must be commented out:

The swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit trigger lines were added to support workflow for Swarm 2018.2 and later. If workflow is enabled, add the swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit trigger lines to the Helix Server trigger table if they are not already present.

Tip

The trigger script can provide the list of trigger lines that should work, with little to no adjustment, by executing it with the -o option:

Windows

C:\> perl "C:\path\to\swarm-trigger.pl" -o

Linux

$ /path/to/swarm-trigger.pl -o

As a Helix Server user with super privileges, edit the Helix Server trigger table by running the p4 triggers command and add the following lines (including the initial tab character). Update the perl.exe, trigger script, and configuration file paths in each line below to reflect the actual paths on your Helix Server:

Warning

Windows and Linux:

Workflow technology preview feature disabled (default):

The swarm.enforce.1, swarm.enforce.2, swarm.strict.1, and swarm.strict.2 trigger lines are commented out because they are optional. They require that the DEPOT_PATH1 and DEPOT_PATH2 values are configured appropriately.
- The first two lines configure the enforce feature, which rejects any submitted changes that are not tied to an approved review.
- The second two lines configure the strict feature, which rejects any submitted changes when the contents of the changelist do not match the contents of its associated approved review.
If you need to apply enforce or strict to more depot paths, copy the lines and tweak the depot paths as necessary.
The swarm.enforce, swarm.strict, and swarm.shelvesub triggers must be commented out when workflow is disabled.

Workflow technology preview feature enabled:

The swarm.enforce, swarm.strict, and swarm.shelvesub triggers must be used and the #s must be removed when workflow is enabled.
The swarm.enforce.1, swarm.enforce.2, swarm.strict.1, and swarm.strict.2 trigger lines must be commented out when workflow is enabled.

Note

The %quote%c:\path\to\perl.exe%quote% entry is only required for Windows-hosted systems.

If you have committed both the trigger script and the configuration file to the Helix Server:

	swarm.job        form-commit   job    "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t job        -v %formname%"
	swarm.user       form-commit   user   "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t user       -v %formname%"
	swarm.userdel    form-delete   user   "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t userdel    -v %formname%"
	swarm.group      form-commit   group  "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t group      -v %formname%"
	swarm.groupdel   form-delete   group  "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t groupdel   -v %formname%"
	swarm.changesave form-save     change "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t changesave -v %formname%"
	swarm.shelve     shelve-commit  //...  "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t shelve     -v %change%"
	swarm.commit     change-commit  //...  "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t commit     -v %change%"
	swarm.shelvedel  shelve-delete  //...  "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t shelvedel  -v %change% -w %client% -u %user% -d %quote%%clientcwd%%quote% -a %quote%%argsQuoted%%quote% -s %quote%%serverVersion%%quote%"
#	The following triggers are only used to prevent a commit without an approved review.
#	See the Swarm trigger documentation before enabling these.
#	They should be commented out if workflow is enabled.
#	swarm.enforce.1 change-submit  //DEPOT_PATH1/... "%c:\path\to\perl.exe% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t enforce -v %change% -p %serverport%"
#	swarm.enforce.2 change-submit  //DEPOT_PATH2/... "%c:\path\to\perl.exe% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t enforce -v %change% -p %serverport%"
#	swarm.strict.1  change-content //DEPOT_PATH1/... "%c:\path\to\perl.exe% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t strict -v %change% -p %serverport%"
#	swarm.strict.2  change-content //DEPOT_PATH2/... "%c:\path\to\perl.exe% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t strict -v %change% -p %serverport%"
#	The swarm.enforce, swarm.strict, and swarm.shelvesub triggers below must be used when the Workflow
#	technical preview feature is enabled. The enforce and strict triggers above must be commented out
#	if the Workflow feature is enabled.
#	swarm.enforce    change-submit  //...  "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t checkenforced -v %change% -u %user%"
#	swarm.strict     change-content //...  "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t checkstrict   -v %change% -u %user%"
#	swarm.shelvesub  shelve-submit  //...  "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t checkshelve   -v %change% -u %user%"

If you have copied the trigger script and configuration file to common paths on all servers:

	swarm.job        form-commit   job    "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t job        -v %formname%"
	swarm.user       form-commit   user   "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t user       -v %formname%"
	swarm.userdel    form-delete   user   "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t userdel    -v %formname%"
	swarm.group      form-commit   group  "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t group      -v %formname%"
	swarm.groupdel   form-delete   group  "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t groupdel   -v %formname%"
	swarm.changesave form-save     change "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t changesave -v %formname%"
	swarm.shelve     shelve-commit  //...  "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t shelve     -v %change%"
	swarm.commit     change-commit  //...  "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t commit     -v %change%"
	swarm.shelvedel  shelve-delete  //...  "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t shelvedel  -v %change% -w %client% -u %user% -d %quote%%clientcwd%%quote% -a %quote%%argsQuoted%%quote% -s %quote%%serverVersion%%quote%"
#	The following triggers are only used to prevent a commit without an approved review.
#	See the Swarm trigger documentation before enabling these.
#	They should be commented out if workflow is enabled.
#	swarm.enforce.1 change-submit  //DEPOT_PATH1/... "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t enforce -v %change% -p %serverport%"
#	swarm.enforce.2 change-submit  //DEPOT_PATH2/... "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t enforce -v %change% -p %serverport%"
#	swarm.strict.1  change-content //DEPOT_PATH1/... "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t strict -v %change% -p %serverport%"
#	swarm.strict.2  change-content //DEPOT_PATH2/... "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t strict -v %change% -p %serverport%"
#	The swarm.enforce, swarm.strict, and swarm.shelvesub triggers below must be used when the Workflow
#	technical preview feature is enabled. The enforce and strict triggers above must be commented out
#	if the Workflow feature is enabled.
#	swarm.enforce    change-submit  //...  "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t checkenforced -v %change% -u %user%"
#	swarm.strict     change-content //...  "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t checkstrict   -v %change% -u %user%"
#	swarm.shelvesub  shelve-submit  //...  "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t checkshelve   -v %change% -u %user%"

Warning

Windows and Linux:

The use of %quote% is not supported on 2010.2 servers (it is harmless though); if you are using this version, ensure that you do not have any spaces in the path to perl.exe or the script's path.

Important

Windows and Linux:

If your Helix Server has SSL enabled and is older than the 2014.1 release, the %serverport% trigger variable does not include the necessary transport indicator, which can cause the enforce and strict triggers to fail.

To solve this problem, add ssl: immediately before %serverport% in the trigger lines. For example:

#	The following triggers are only used to prevent a commit without an approved review.
#	See the Swarm trigger documentation before enabling these.
#	They should be commented out if workflow is enabled.
#	swarm.enforce.1 change-submit  //DEPOT_PATH1/... "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t enforce -v %change% -p ssl:%serverport%"
#	swarm.enforce.2 change-submit  //DEPOT_PATH2/... "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t enforce -v %change% -p ssl:%serverport%"
#	swarm.strict.1  change-content //DEPOT_PATH1/... "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t strict -v %change% -p ssl:%serverport%"
#	swarm.strict.2  change-content //DEPOT_PATH2/... "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t strict -v %change% -p ssl:%serverport%"

Configure the Helix Server to promote all shelved changes.

When this configurable is set, Swarm has access to all shelved changelists, which is a requirement for pre-commit reviews. When it is not set, users connected to an edge server must remember to use the -p option when shelving files to promote their shelves to the commit server when initiating a pre-commit review.

Windows:
```
C:\> p4 configure set dm.shelve.promote=1
```
Linux:
```
$ p4 configure set dm.shelve.promote=1
```
Optionally forward logins to the commit server.

If you intend to use P4V and its Swarm integration, you should consider forwarding logins to the commit server. See P4V Authentication for details.
You can now configure additional functionality for Swarm:

Optional: Hide Swarm storage from regular users, see Hiding Swarm storage from regular users.
Optional: Handle exclusive locks, see Handling Exclusive Locks.

Depending on your installation type, do one of the following:

Swarm package installation: Review the post-install configuration options to customize your Swarm installation, see Post-install configuration options.
Swarm OVA installation: Review the post-install configuration options to customize your Swarm installation, see Post-install configuration options.
Swarm tarball installation: Set up a recurring task to spawn workers, see Set up a recurring task to spawn workers.

Hiding Swarm storage from regular users

Swarm information storage uses Helix 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 Helix 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 Helix Server. When dm.keys.hide is set to 1, only the p4 keys command requires admin-level access in the Helix 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

Handling Exclusive Locks

Swarm takes copies of files when it is creating reviews. Some of the files managed by Helix 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 Swarm to work with these 'exclusive open' files, you must enable filetype.bypasslock in the Helix 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

If this setting is not enabled in Helix Server, Swarm will report exceptions when working with exclusively opened files similar to "Cannot unshelve review (x). One or more files are exclusively open", and noting that you must have the filetype.bypasslock configurable enabled.

Your search for returned result(s).