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.
Helix Versioning Engine can refer to a Helix server
machine (p4d), proxy, broker, replica, edge server, or commit server. It does not refer to a service user;
service users are used to coordinate replication in a Helix Versioning Engine.
For simplicity, the term Helix server
is used to refer to any configuration of a Helix Versioning Engine 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-hosted Helix server
Ensure that the required Trigger dependencies have been installed on the machine hosting Helix server.
Install the Swarm trigger script on the Helix server.
If the Swarm trigger script has not already been installed on your Helix server machine, you need to copy p4-bin/scripts/swarm-trigger.pl from your Swarm install to the Helix server machine so that it can be executed by the Helix server.
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
swarm-trigger.pl can be configured directly, but the preferred approach is to create a configuration file called swarm-trigger.conf, as using the configuration file greatly simplifies upgrades. swarm-trigger.conf should be created in the same directory as swarm-trigger.pl.
If your Helix server is configure using a commit-edge configuration, copy swarm-trigger.pl and swarm-trigger.conf 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)
# 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)
# 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
You may need to edit the trigger script to specify the full path to curl.exe.
Important
If you specify ADMIN_USER, the ticket contained in %USERPROFILE%/p4tickets.txt (or the ticket file specified with 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-versioning-engine:1666 ...
then the ticket for the admin user specified with ADMIN_USER should be established with:
Use the full path to perl if it is not available in your command path.
You should expect to see no output. If the trigger is misconfigured, such as using an invalid trigger token, you would see an error.
Warning
Installation of the triggers may cause a security warning dialog to appear when curl.exe executes:
If this occurs, the triggers hang, creating zombie perl processes. Due to the way triggers are invoked by Helix server, the dialog is normally not visible even though Windows is waiting on interaction.
To resolve this:
Clear the Always ask before opening this file check box and click Run.
Right-click curl.exe, select Properties, and click Unblock.
Update the Helix Core triggers table to run the trigger script.
As a Helix Core user with super privileges, edit the Helix Core 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 above to reflect the actual paths on your Helix server.
Important
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 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.
Note
The last four trigger lines are commented out as they are optional, and 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 their depot paths as necessary.
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:
C:\> perl "C:\path\to\swarm-trigger.pl" -o
Configure the Helix server to promote all shelved changes.
C:\> p4 configure set dm.shelve.promote=1
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.
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.
Setup Swarm triggers with a Linux-hosted Helix server
Ensure that the required Trigger dependencies have been installed on the machine hosting Helix server.
Copy the perl trigger to the Helix server.
If your Helix server is version 2014.1 (or later), we recommend submitting the trigger file, p4-bin/scripts/swarm-trigger.pl, to Helix Core and running it from the depot. The recommended depot location would be //.swarm/triggers/swarm-trigger.pl, especially if you have already setup Comment attachments.
If your Helix server is older than version 2014.1, or prefer that the trigger 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
swarm-trigger.pl can be configured directly, but the preferred approach is to create a configuration file called swarm-trigger.conf, as using the configuration file greatly simplifies upgrades.
If you are using the Swarm triggers package described in Swarm packages, the 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 path 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 it exists 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="https://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)
# 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)
# 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.
# 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
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
If you specify ADMIN_USER, the ticket contained in $HOME/.p4tickets (or the ticket file specified with ADMIN_TICKET_FILE) must use the port that was used to start the Helix server. For example, if p4d is started with:
$ p4d -p my-helix-versioning-engine:1666 ...
then the ticket for the admin user specified with ADMIN_USER should be established with:
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.
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.
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 Core triggers table to run the Perl trigger.
As a Helix Core user with super privileges, edit the Helix Core triggers table by running the p4 triggers command and add the appropriate set of lines (including the initial tab character):
If you have committed both the trigger script and the configuration file to the Helix server:
Update the trigger script and configuration file paths in each line above to reflect the actual paths on your Helix server.
Important
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 last four trigger lines in either block are commented out as they are optional, and 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 their depot paths as necessary.
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:
$ /path/to/swarm-trigger.pl -o
Configure Helix server to promote all shelved changes.
$ p4 configure set dm.shelve.promote=1
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.
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.
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.
