Deploy and configure a Swarm VM from an OVA

Swarm is available as an OVA (Open Virtualization Appliance) that requires minimal configuration.

Use the Swarm OVA if you want to:

  • Simplify the installation and configuration steps
  • Experiment with Swarm without using additional hardware
  • Install Swarm without having a Linux-based server available
Important

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

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.
  • 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.

Before you begin

Important

Review the Helix server requirements before you install Swarm, see Helix Core server requirements.

You will need the following information to deploy the Swarm Virtual Machine (VM) from the OVA:

  • The Helix Core server port (P4PORT) in the form: my-helix-core-server:1666

    • Important

    If your Helix Core server is deployed using the commit-edge architecture, ensure that the Swarm port value points to the commit server.

    For more information, see the Commit-edge chapter in the Helix Core Server Administrator Guide.

  • The Userid of a normal user in the Helix server with admin privileges.
  • The Ticket, or password of the admin-level Perforce user.

    • Important

    If your Helix server is configured for Helix Authentication Service, you must use a long-lived login ticket for the Swarm user.

  • The Mail relay host address.

Deploy the Swarm OVA

To deploy the Swarm OVA:

  1. Download the Swarm OVA.
  2. Import the OVA into your virtualization environment, see VMWare OVA import or Oracle VirtualBox import for details.
  3. Set the VM network settings to Bridged so that it can connect to your network.
  4. Start the VM.

    5. Note

    If you are starting your VM in VMware Workstation, you might see an import failed error dialog. If you see this error dialog, click Retry to start your Swarm VM.

    Diagnostic and boot information is displayed when the VM starts.

    The configuration welcome screen is displayed when the boot is complete:

    Image of the OVA Configuration screen

  5. Follow the configuration script prompts to configure the perforce system user password and the hostname for the VM:

    1. Set a password for the perforce system user. The perforce system user is a sudo user.
    2. Set a hostname for the VM.

      3. Tip

      The SSH IP address of the VM is displayed when you set the hostname, make a note of it because you need this address to ssh into the VM.

  6. The configuration script displays the following prompt:

    Do you want to proceed with Swarm configuration (Y/n)?

    Choose one the following two options:

    Proceed with the Swarm VM configuration script

    1. To proceed with the Swarm VM configuration script, press the Enter key.
    2. Press the Enter key again to restart the Swarm VM configuration script.
    3. Finalize Swarm VM configuration, see Finalize Swarm configuration for details.

    Exit the Swarm VM configuration script

    1. To exit the Swarm VM configuration script, type n and press the Enter key
    2. The Swarm configuration script exits and you can log in to the VM.
    3. Log in to the VM as the perforce system user:
      • Username: perforce
      • Password: the password you set in step 4
    4. Make changes to the VM as required.

    5. When you have finished making changes to the VM, rerun the configure-swarm.sh script from the /opt/perforce/swarm/sbin directory:

      sudo /opt/perforce/swarm/sbin/configure-swarm.sh
    6. Finalize Swarm VM configuration, see Finalize Swarm configuration for details.

Finalize Swarm configuration

Follow the Swarm configuration script prompts to finalize Swarm VM configuration:

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

  1. Enter the Helix Core server port (P4PORT) number.

    Important

    If your Helix Core server is deployed using the commit-edge architecture, ensure that the Swarm port value points to the commit server.

    For more information, see the Commit-edge chapter in the Helix Core Server Administrator Guide.

  2. Enter the Userid of a normal user with admin privileges in the Helix server.
  3. Enter the Ticket, or password, of the admin-level Perforce user.

    4. Important

    If your Helix server is configured for Helix Authentication Service, you must use a long-lived login ticket for the Swarm user.

    Note

    You can obtain a login ticket by running (in another shell):

    p4 -p myp4host:1666 -u userid login -p

    If the login ticket you provide would expire in less than a year, you will receive a warning.

  4. Enter the Mail relay host address.

    5. The Swarm configuration script completes the configuration and the welcome screen is displayed.

    The welcome screen has links to the Swarm documentation, Perforce support, and the PHP website:

    Image of the Swarm VM Welcome Screen

  5. Update the VM with security updates and bug fixes:

    1. Use ssh to log into the VM as the perforce system user.

    2. Update the catalog of available packages:

      apt-get update

    3. Download and install any updated packages:

      apt-get upgrade

      4. See OVA Management for more details.

    6. Note

    Now that the Swarm VM is configured and running, you can edit the configuration by using ssh to connect to the VM as the system swarm user and editing the Swarm configuration file /opt/perforce/swarm/data/config.php. The Swarm installation folder is /opt/perforce/swarm/.

  6. The basic Swarm configuration is now complete.

    Important

    If your Helix 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 server, run the following command:

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

  7. Establish a trigger token, see Establish trigger token.

VMWare OVA import

The Swarm OVA works with several VMWare virtualization products, such as Player, Workstation, and Fusion.

  1. In the VMWare product, select File > Open.
  2. Browse to the swarm.ova file and click Open.
  3. Type a name for the virtual machine, such as Swarm, and click Import.

Oracle VirtualBox import

The Swarm OVA works with Oracle VirtualBox, version 4.x+.

  1. In VirtualBox, select File > Import Appliance.
  2. Browse to the swarm.ova file and click Open.
  3. Click Next.
  4. Click Import.