Skip to content

Using a Failover PCoIP License Server

You can add a second standalone PCoIP License Server to your system, which will act as a backup in case the main PCoIP License Server fails. The two servers are registered as a pair called a failover pair, in which the main server periodically updates the backup server to keep it in sync.

In a failover situation, when the main PCoIP License Server is down or is unreachable, the backup PCoIP License Server can validate sessions.

Important: Failover requires manual changes in PCoIP Connection Managers and PCoIP Agents

Switching from the main to the backup PCoIP License Server requires manual configuration changes in your PCoIP Connection Managers and your PCoIP agents. The change is not automatic. See Failover behavior for more information.

Note: Backup PCoIP License Servers do not synchronize data

The backup PCoIP License Server does not synchronize data with the main PCoIP License Server, so information about usage will be unreliable as long as failover lasts.

Installing and Configuring a Failover Pair

A failover pair consists of a primary (main) PCoIP License Server and its backup. Creating a failover pair involves the following steps:

Enable HTTPS/TLS

The examples that follow assume that you have enabled HTTPS/TLS, as described here. If you have not, use http:// instead of https://.

  1. Install the backup PCoIP License Server

  2. Set the host ID of the backup server on the main server

  3. Register the PCoIP License Servers with Teradici

  4. Enable failover support on the backup server

  5. Configure response reference information on the main server

  6. Activate licenses on the main server

  7. Verify failover configuration

1: Install the Backup PCoIP License Server

First, install the new PCoIP License Server that will act as your backup. Do not register it with Teradici yet (we'll do that later). Keep the following guidelines in mind:

  • The two PCoIP License Servers must be the same version.

  • Both PCoIP License Servers should be configured identically, with some allowable differences. For example, you can specify different PORT values for the two PCoIP License Servers.

  • The two servers should be in different physical locations if possible, or at least on independent hypervisors. One incident or failure should not be able to take down both servers.

  • The clocks of the main PCoIP License Server and backup PCoIP License Server must be accurate, synchronized, and in the same time zone. If they are not, unpredictable behavior can occur.

  • You must configure the main PCoIP License Server with the failover information before the backup server is registered with Teradici. If the backup PCoIP License Server is registered with Teradici before configuration is complete, create a ticket with Teradici Support for assistance.

2: Set the Host ID of the Backup Server on the Main Server

The main PCoIP License Server needs to know the backup server's ID, which will be used to register with Teradici and create a failover pair. We'll get the ID from the backup server and then add that ID to the configuration file on the main server.

  1. Start the backup PCoIP License Server.

  2. On the backup PCoIP License Server, run the following command and note the backup server's host ID in the response:

    pcoip-get-license-server-id
    
  3. Stop the backup PCoIP License Server.

    sudo systemctl stop flexnetls-TERADICI.service
    
  4. Switch to the main PCoIP License Server and start it.

    sudo systemctl start flexnetls-TERADICI.service
    
  5. On the main PCoIP License Server, use a text editor to edit /opt/flexnetls/TERADICI/local-configuration.yaml. Set the backup-hostid to the backup server's host ID you recorded in step 2.

    Host IDs must be of the same type

    The host ID for both the main server and backup server must be the same type (for example, you can use two VM UUIDs or two Ethernet MAC addresses, but not one of each).

  6. Save and exit the editor.

  7. Shut down the main PCoIP License Server.

    sudo systemctl stop flexnetls-TERADICI.service
    

At the end of this process, both PCoIP License Servers should be shut down.

3: Register the PCoIP License Servers

Next we'll create the failover pair by registering the servers with Teradici.

  1. Start the main PCoIP License Server.

    sudo systemctl restart flexnetls-TERADICI.service
    
  2. Run the following command:

    pcoip-list-licenses
    

    You don't need the output of this command; we're using it to push the configuration to Teradici, which will find the new backup server ID in your configuration and create a failover pair association.

  3. Once you see a valid response from pcoip-list-licenses, start the backup PCoIP License Server.

4: Enable Failover Support on the Backup Server

Next, we'll change a few settings on the backup server, configuring it to act as a backup and sync with the main server.

Important: About flexnetlsadmin.sh

The following sections use the PCoIP License Server Administrator command-line tool, which is a utility provided at /opt/flexnetls/TERADICI/admintools/flexnetlsadmin.sh. You can invoke it by providing its full file path on the command line.

If you'd like to invoke the tool as flexnetlsadmin.sh (omitting the full path), add /opt/flexnetls/TERADICI/admintools to your machine's $PATH variable and restart your console application.

The examples that follow use the shorter command form, as if you had modified your system $PATH. If you haven't, replace flexnetlsadmin.sh with /opt/flexnetls/TERADICI/admintools/flexnetlsadmin.sh in all of these sample commands.

Passwords

You will be prompted for a password when using these commands. The password is the PCoIP License Server administrative password, as set by pcoip-set-password.

On the backup server, use flexnetlsadmin.sh to set the following PCoIP License Server policy settings:

  • fne.syncTo.mainUri: Set this to the URI of the main PCoIP License Server, using the format: https://<licenseServerHostName>:<port>/fne/bin/capability.

    For example (replace the backup host name, main PCoIP License Server host name, and port numbers in this example with your own):

    flexnetlsadmin.sh -server https://localhost:7071 -authorize admin -passwordConsoleInput -config -set fne.syncTo.mainUri=https://<MainLicenseServerHostName>:7071/fne/bin/capability
    
  • fne.syncTo.enabled: Set this value to true. For example (replace the host name and port number in this example with your own):

    flexnetlsadmin.sh -server https://localhost:7071 -authorize admin -passwordConsoleInput -config -set fne.syncTo.enabled=true
    

5: Configure Response Reference Information on the Main Server

Capability responses returned to client devices can include the URI for the main and backup PCoIP License Servers. Configure one or both of these policy settings to include the corresponding URIs in the response reference information:

  • To include the main PCoIP License Server URI in client reponses: set the licensing.main.uri value using flexnetlsadmin.sh. For example (replace these host names and port numbers with your own):

    flexnetlsadmin.sh -server https://localhost:7071 -authorize admin -passwordConsoleInput -config -set licensing.main.uri =https://<MainLicenseServerHostName>:7071/fne/bin/capability
    
  • To include the backup PCoIP License Server URI in client reponses: set the licensing.backup.uri value using flexnetlsadmin.sh. For example (replace these host names and port numbers with your own):

    flexnetlsadmin.sh -server https://localhost:7071 -authorize admin -passwordConsoleInput -config -set licensing.backup.uri=https://<BackupLicenseServerHostName>:7071/fne/bin/capability
    

6: Activate Licenses on the Main Server

If no licenses were activated on the main PCoIP License Server at startup, activate them now. The active licenses will be automatically synced to backup PCoIP License Server.

Synchronizing changes from the main server to the backup

If you make changes on the main server that need to be synchronized with the backup, restart the flexnetls-TERADICI.service on the backup:

systemctl restart flexnetls-TERADICI.service

7: Verify Failover Configuration

After both servers have received their license rights, verify the failover scenario role of each PCoIP License Server. Each server's failover role is included in capability responses delievered to it.

Use the flexnetlsadmin.sh tool from each server machine to verify its failover role. As usual, replace the URI and port information here with your own.

  • From the main PCoIP License Server:

    flexnetlsadmin.sh -server https://localhost:7071 -authorize admin -passwordConsoleInput -status
    

    You should see a backup server specified in the response to this command.

  • From the backup PCoIP License Server:

    flexnetlsadmin.sh -server https://localhost:7071 -authorize admin -passwordConsoleInput -status
    

    This response should not contain a backup server item.

Failover Behavior

If the primary PCoIP License Server fails or loses connectivity, the backup PCoIP License Server will automatically begin validating PCoIP sessions.

PCoIP Connection Managers and PCoIP agents do not automatically switch to a backup PCoIP License Server; they must be configured to point to the backup server for the duration of the failover event, and then reverted once normal service is restored.

For detailed PCoIP License Server configuration information, see the following documentation: