Set up a recurring task to spawn workers

To ensure that incoming Helix Core Server events are automatically processed by Swarm, it is important to set up a cron job to do this. We recommend that the cron job is installed on the Swarm host machine.

Install curl or wget

You must install either curl or wget on the Swarm server machine to run the recurring task that spawns the Swarm workers:

Install curl

  1. Download curl from: curl download page
  2. Install curl.
  3. Verify that curl is installed, see Verify that curl or wget is installed.
Warning

If curl cannot execute as expected, trigger execution may block or fail. Prior to configuring the triggers, verify that curl executes, run:

$ curl -h

The start of the output should be similar to:

Usage: curl [options...] <url>
Options: (H) means HTTP/HTTPS only, (F) means FTP only
     --anyauth       Pick "any" authentication method (H)
 -a, --append        Append to target file when uploading (F/SFTP)
     --cacert FILE   CA certificate to verify peer against (SSL)
     --capath DIR    CA directory to verify peer against (SSL)
...[truncated for brevity]...

For a more thorough test that actually fetches content over a network, try the following test:

$ curl https://www.perforce.com/

The output should look like HTML.

Install wget

  1. Download wget from: wget download page
  2. Install wget.
  3. Verify that wget is installed, see Verify that curl or wget is installed.

Verify that curl or wget is installed

Warning

curl or wget must be installed or workers do not spawn and Swarm cannot process any events.

Verify that curl or wget is installed:

  1. Use the which command.

    2. For example to verify that curl is installed:

    $ which curl

  2. If you see any output, the referenced command is installed.

Create a recurring task to spawn workers

Note

Swarm package installation:

  • The helix-swarm, swarm-cron-hosts.conf, and swarm-cron.sh files are automatically created with the correct content including the correct URL for Swarm. They do not need to be edited.
  • If you want to run Swarm in a sub-folder of an existing website, or with a custom port, the swarm-cron-host.conf file must be edited. For instructions on how to configure Swarm to run in a sub-folder, or with a custom port, see Run Swarm in a sub-folder of an existing web site, or Run Swarm's virtual host on a custom port.

helix-swarm cron file

The helix-swarm file is located in the /etc/cron.d and points to the swarm-cron.sh script file.

  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: 

    3. #
# 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.

swarm-cron.sh script

The swarm-cron.sh file in /opt/perforce/swarm/p4-bin/scripts ensures that a worker is fired up every minute.

By default, the DEFAULT_CONFIG_FILE= configuration line is set to /opt/perforce/etc/swarm-cron-hosts.conf. The swarm-cron.sh script takes the Swarm hostname from the swarm-cron-hosts.conf file.

The swarm-cron.sh script contains the correct content for Swarm installations using wget, or curl.

Tip

You must leave the wget, and curl configuration lines in the script. The script is written so that it can be used with Swarm installations that use wget, and Swarm installations that use curl. The wget configuration line is tried first, if that fails the curl configuration line is tried.

  • wget configuration line for HTTP, and HTTPS:

    wget --quiet --no-check-certificate --output-document /dev/null --timeout 5 "${SWARM_HOST}/queue/worker"

  • curl configuration line for HTTP, and HTTPS:

    curl --silent --insecure --output /dev/null --max-time 5 "${SWARM_HOST}/queue/worker"

In the wget and curl configuration lines above, where you see --timeout 5 or --max-time 5, the 5 is the number of seconds that the cron task will wait for a response from the Swarm host. When the cron task is installed on the Swarm host, that value could be reduced to 1 second (e.g. --timeout 1 or --max-time 1).

Note

If you configure Swarm to use HTTPS, and you install a self-signed certificate, the cron jobs avoid the certificate validity test which could cause silent failures to process events. The command to avoid the certificate validity test is included by default for wget, and curl:

  • wget command: --no-check-certificate
  • curl command: --insecure

If you have configured an HTTP connection to Swarm, the avoid validity check command is ignored. For more information about the risks of using a self-signed SSL certificate, see Security risks of using a self-signed certificate.

swarm-cron-hosts.conf configuration file

The swarm-cron-hosts.conf file in /opt/perforce/etc specifies the connection type (HTTP or HTTPS), hostname, and port number for Swarm cron jobs.

  1. Edit the swarm-cron-hosts.conf file so that is contains the actual Swarm hostname, and port you have configured for Swarm (which may include a sub-folder or a custom port). The following format is used: 
    2. [http[s]://]<swarm-host>[:<port>]

    Default if value not specified:

    • [http[s]://] http
    • <swarm-host> must be specified
    • :<port> 80
  2. Save the edited file.
    3. Tip

    To check or modify Swarm worker configuration, see Workers.

    Note

    If the recurring task is disabled, or stops functioning for any reason, logged-in users see the following error message when Swarm detects that no workers are running:

  3. The basic Swarm configuration is now complete.

    Important

    If your Helix Core Server is configured for Helix Authentication Service, you can force all of your users to authenticate via your Identity Provider (IdP) by disabling fall-back to passwords. To disable fall-back to passwords on the Helix Core Server, run the following command:

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

  4. Review the post-install configuration options to customize your Swarm installation, see Post-install configuration options.