Post-install configuration options

There are a few options for customizing your Swarm installation's operation. This section covers the options that are officially supported:

HTTPS
Run Swarm in a sub-folder of an existing web site
Run Swarm's virtual host on a custom port

If you do not need to customize your Swarm installation, you are all set to start using Swarm, enjoy!

Tip

To get started with Swarm, see the Quickstart chapter.

Back up your Swarm virtual host first

Before undertaking any of the following customization options, ensure that you have backed up your Swarm virtual host configuration. Choose the most appropriate option:

If your Apache configuration directory contains the directories sites-available and sites-enabled:
```
$ cd /path/to/apache/configuration/..
$ cp -a sites-available sites-available.bak
```
Important
If the sites-enabled directory contains files, and not just symbolic links, you need to backup this folder as well:
```
$ cd /path/to/apache/configuration/..
$ cp -a sites-enabled sites-enabled.bak
```
For CentOS/RHEL systems, if you used the Swarm packages to install Swarm:
```
$ cd /path/to/apache/configuration/..
$ cp -a conf.d conf.d.bak
```
Otherwise, back up your Apache configuration.

HTTPS

Important

Back up your Swarm virtual host configuration before customizing your Swarm installation, see Back up your Swarm virtual host first.

This section describes how to make your Swarm installation more secure by using HTTPS.

Before you begin the following procedure, locate your system's Apache configuration. Common configuration directories include:

/etc/httpd/conf/
/etc/apache2/
/Applications/XAMPP/etc/

Within the Apache configuration path, the main Apache configuration file is usually named one of the following:

httpd.conf
apache2.conf

A longer discussion on the possible locations and names of Apache configuration files is available here: https://wiki.apache.org/httpd/DistrosDefaultLayout

Enable SSL in Apache.

If the Apache utility a2enmod is installed:
```
$ sudo a2enmod ssl
```
Without the a2enmod utility, edit the Apache configuration file by hand. Locate your Apache configuration file for modules and either uncomment or add the following lines:
```
LoadModule  ssl_module  libexec/apache2/mod_ssl.so
```
Create a directory to store certificates.
```
$ sudo mkdir -p /etc/apache2/ssl
```

Create a certificate/key pair.

$ cd /etc/apache2/ssl
$ sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout apache.key -out apache.crt

This command generates a private key and a certificate. To form the certificate, openssl prompts you for several details:

Generating a 2048 bit RSA private key
...................+++
....................................+++
writing new private key to 'apache.key'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:CA
State or Province Name (full name) [Some-State]:British Columbia
Locality Name (eg, city) []:Victoria
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Perforce Software
Organizational Unit Name (eg, section) []:Swarm development team
Common Name (e.g. server FQDN or YOUR name) []:myswarm.host
Email Address []:[email protected]

The output above includes some example details. You should replace anything in italics with your own details. Since the certificate request details that can help users determine whether your certificate is valid, enter legitimate information whenever possible.

Important

The Common Name field must match the hostname for your Swarm installation exactly.

Secure the certificate directory.
```
$ sudo chmod 600 /etc/apache2/ssl
```

Edit the virtual host configuration.

Note

The virtual host configuration should be in the file you backed up initially.

For Apache 2.2, edit the virtual host configuration to match:

<VirtualHost *:80>
	ServerName myswarm.host
	ServerAlias myswarm
	ErrorLog "/path/to/apache/logs/myswarm.error_log"
	CustomLog "/path/to/apache/logs/myswarm.access_log" common
	DocumentRoot "/path/to/swarm/public"
	<Directory "/path/to/swarm/public">
		AllowOverride All
		Require all granted
	</Directory>

	Redirect permanent / https://myswarm.host
</VirtualHost>

<VirtualHost *:443>
	SSLEngine on
	SSLCertificateFile /etc/apache2/ssl/apache.crt
	SSLCertificateKeyFile /etc/apache2/ssl/apache.key

	ServerName myswarm.host
	ServerAlias myswarm
	ErrorLog "/path/to/apache/logs/myswarm.error_log"
	CustomLog "/path/to/apache/logs/myswarm.access_log" common
	DocumentRoot "/path/to/swarm/public"
	<Directory "/path/to/swarm/public">
		AllowOverride All
		Order allow,deny
		Allow from all
	</Directory>
</VirtualHost>

For Apache 2.4, edit the virtual host configuration to match:

<VirtualHost *:80>
	ServerName myswarm
	ServerAlias myswarm.host
	ErrorLog "/path/to/apache/logs/myswarm.error_log"
	CustomLog "/path/to/apache/logs/myswarm.access_log" common
	DocumentRoot "/path/to/swarm/public"
	<Directory "/path/to/swarm/public">
		AllowOverride All
		Require all granted
	</Directory>
</VirtualHost>

<VirtualHost *:443>
	SSLEngine on
	SSLCertificateFile /etc/apache2/ssl/apache.crt
	SSLCertificateKeyFile /etc/apache2/ssl/apache.key

	ServerName myswarm.host
	ServerAlias myswarm
	ErrorLog "/path/to/apache/logs/myswarm.error_log"
	CustomLog "/path/to/apache/logs/myswarm.access_log" common
	DocumentRoot "/path/to/swarm/public"
	<Directory "/path/to/swarm/public">
		AllowOverride All
		Require all granted
	</Directory>
</VirtualHost>

See Apache's virtual host documentation for details:
https://httpd.apache.org/docs/2.2/vhosts/
https://httpd.apache.org/docs/2.4/vhosts/

Customize the virtual host definition.
1. Replace myswarm.host with the hostname for Swarm on your network.
2. Replace myswarm with the name of the subdomain hosting Swarm. Many administrators choose swarm.
  
  Note
  The string myswarm in the log file paths: this should match the subdomain name and prefix for the log files, to help coordinate the active host with the log files for that host. Doing this is particularly useful when your Apache server hosts multiple instances of Swarm.
3. Replace /path/to/apache/logs with the path where your Apache store its log files. Apache's log files are typically named access_log and error_log.
4. Replace /path/to/swarm with the path to the Swarm directory.
Restart your web server.
```
$ sudo apachectl restart
```
Adjust your firewall configuration to allow connections to the standard SSL port for web servers.
- For CentOS/RHEL 6.6+:
```
$ sudo lokkit -p 443:tcp
```
- For CentOS/RHEL 7+:
```
$sudo firewall-cmd --zone=public --add-port=443/tcp --permanent
$sudo systemctl reload firewalld
```
- For other distributions, consult with your network administrator or operating system documentation to determine how to adjust your firewall configuration.
Test your HTTPS URL from a web browser.

Important
If the myswarm.host value in the virtual host configuration and the certificate do not match, the P4V integration with Swarm fails with the message SSL handshake failed.

Also, when a reverse DNS lookup is performed, myswarm.host should be the answer when querying for the Swarm server's IP address.
You are now all set to start using Swarm, enjoy!

Tip
To get started with Swarm, see the Quickstart chapter.

Run Swarm in a sub-folder of an existing web site

Important

Back up your Swarm virtual host configuration before customizing your Swarm installation, see Back up your Swarm virtual host first.

If you cannot run Swarm in its own virtual host, which might be necessary when you do not control the hostname to be used with Swarm, installing Swarm in a sub-folder of an existing virtual host configuration can be a good solution.

Installing Swarm in a sub-folder requires modification of the previous installation steps covered in this chapter:

The Apache configuration is entirely different; instead of establishing a new virtual host, you need to modify an existing virtual host configuration. Often, this would be Apache's default site.
Swarm's configuration file requires an extra item.

The following sections cover the specifics of sub-folder installation.

See base_url for more details.

Important

If you used the Swarm OVA or Swarm packages to install Swarm, you can adjust Swarm's configuration using the package configuration script /opt/perforce/swarm/sbin/configure-swarm.sh.

configure-swarm.sh does not read any existing Swarm configuration; you must provide all of the configuration details each time you execute configure-swarm.sh:

$ sudo /opt/perforce/swarm/sbin/configure-swarm.sh -n -p myp4host:1666 -u swarm -w password -e mx.example.com -H myhost -B /swarm

In the example above, the -B option is used to specify the name of the sub-folder.

If you use configure-swarm.sh to adjust the Swarm configuration, you only need to follow the Apache configuration steps described below; all of the changes listed in the Swarm configuration section below have been completed by configure-swarm.sh.

Apache configuration

Ensure that the SWARM_ROOT is not within the document root of the intended virtual host.

This step ensures that Swarm's source code and configuration is impossible to browse, preventing access to important details such as stored credentials, and active sessions and workspaces.
Adjust the virtual host configuration that you are already using.
Note
Depending on the method used to install Swarm, the filename for virtual host configuration you need to edit is:
- For Swarm OVA or Swarm package installations, edit perforce-swarm-site.conf.
- For manual installations following Swarm's recommended Apache configuration edit swarm.
- For other installations, you may have to edit httpd.conf or nearby files.
- For Apache 2.2, add the following lines to the virtual host definition:
```
Alias /swarm SWARM_ROOT/public

<Directory "SWARM_ROOT/public">
  AllowOverride All
  Order allow,deny
  Allow from All
</Directory>
```
- For Apache 2.4, add the following lines to the virtual host definition:
```
Alias /swarm SWARM_ROOT/public
							
<Directory "SWARM_ROOT/public">
  AllowOverride All
  Require all granted
</Directory>
```
The Alias line configures Apache to respond to requests to https://myhost/swarm with content from Swarm's public folder. You can change the /swarm portion of the Alias line to anything you want.

The <Directory> block grants access to everything within Swarm's public folder. Replace SWARM_ROOT with the actual path to Swarm.
Restart your web server.
```
$ sudo apachectl restart
```

Swarm configuration

To successfully operate within a sub-folder, the swarm_root/data/config.php file needs to be adjusted to contain the following lines (as a peer of the p4 item):

	'environment' => array(
		'base_url' => '/swarm'
	),

Ensure that /swarm matches the first item in the Alias line in the virtual host configuration.

See Environment for more details.

Cron configuration

Swarm's recurring task configuration must be updated to reflect the sub-folder that you have configured in Apache's and Swarm's configurations. This is configured in the swarm-cron-hosts.conf file.

Edit /opt/perforce/etc/swarm-cron-hosts.conf.
Replace:
```
https://swarm-host
```
with:
```
https://swarm-host/swarm/
```
Where swarm-host is the hostname of your Swarm installation, and swarm is the sub-folder you want to use.
Save the edited file.

New workers should be started at the start of the next minute.
You are now all set to start using Swarm, enjoy!

Tip
To get started with Swarm, see the Quickstart chapter.

Run Swarm's virtual host on a custom port

Important

Back up your Swarm virtual host configuration before customizing your Swarm installation, see Back up your Swarm virtual host first.

If you cannot run Swarm on port 80 (or port 443 for HTTPS), perhaps because you do not have root access, it is possible to run Swarm on a custom port.

Installing Swarm to use a custom port requires modification of the previous installation steps covered in this chapter: The Apache configuration is slightly different, requiring modification of Swarm's virtual host definition.

The following section covers the specifics of the custom port configuration.

Note

In addition to the following instructions, you may also need to apply the external_url item described in the Environment section if your Swarm is behind a proxy, or you have multiple Swarm instances connected to Helix Server.

Important

If you used the Swarm OVA or Swarm packages to install Swarm, you can adjust Swarm's configuration using the package configuration script /opt/perforce/swarm/sbin/configure-swarm.sh.

configure-swarm.sh does not read any existing Swarm configuration; you must provide all of the configuration details each time you execute configure-swarm.sh:

$ sudo /opt/perforce/swarm/sbin/configure-swarm.sh -n -p myp4host:1666 -u swarm -w password -e mx.example.com -H myhost -P 8080

In the example above, the -P option is used to specify the custom port that Swarm should use.

If you use configure-swarm.sh to adjust Swarm's configuration, follow the additional steps that it describes. Once those steps are complete, do not perform any of the steps described below.

Apache configuration

Edit the virtual host configuration.
Note
Depending on the method used to install Swarm, the filename for virtual host configuration you need to edit is:
- For Swarm OVA or Swarm package installations, edit perforce-swarm-site.conf.
- For manual installations following Swarm's recommended Apache configuration, edit swarm.
- For other installations, you may have to edit httpd.conf or nearby files.
1. Add the following line outside of the <VirtualHost> block:
```
Listen 8080
```
2. Edit the <VirtualHost *:80> line to read:
```
<VirtualHost *:8080>
```
For both lines, replace 8080 with the custom port you wish to use.

Important
If you choose a port that is already in use, Apache refuses to start.
Restart your web server.
```
$ sudo apachectl restart
```
Adjust your firewall configuration to allow connections to the custom port.
- For CentOS/RHEL 6.6+:
```
$ sudo lokkit -p 8080:tcp
```
  Replace 8080 with the custom port you wish to use.
- For CentOS/RHEL 7+:
```
$ sudo firewall-cmd --zone=public --add-port=8080/tcp --permanent
$ sudo systemctl reload firewalld
```
  Replace 8080 with the custom port you wish to use.
- For other distributions, consult with your network administrator or operating system documentation to determine how to just your firewall configuration.

Cron configuration

Swarm's recurring task configuration must be updated to reflect the custom port that you have configured in Apache's configuration. This is configured in the swarm-cron-hosts.conf file.

Edit /opt/perforce/etc/swarm-cron-hosts.conf.
Replace:
```
https://swarm-host:80
```
with:
```
https://swarm-host:8080
```
Where swarm-host is the hostname of your Swarm installation, and 8080 is the custom port you want to use.
Save the edited file.

New workers should be started at the start of the next minute.
You are now all set to start using Swarm, enjoy!

Tip
To get started with Swarm, see the Quickstart chapter.