Installing for Online Environments

The following sections outline how to install the Modern Connection Manager and Security Gateway 24.07.

Before You Begin¶

Before you proceed with installation, note the following:

Docker must be installed before you begin. For instructions, see About Docker.

Make sure ports TCP:80, TCP:443, TCP:4172, and UDP:4172 are open:

sudo firewall-cmd  --add-port 80/tcp
sudo firewall-cmd  --add-port 443/tcp
sudo firewall-cmd  --add-port 4172/tcp
sudo firewall-cmd  --add-port 4172/udp

If you will be using IPv6, set up the required port forwarding rules:

# Add port forwarding rules
sudo firewall-cmd  --add-forward-port=port=443:proto=tcp:toport=8443
sudo firewall-cmd  --add-forward-port=port=80:proto=tcp:toport=8080
sudo firewall-cmd  --add-rich-rule='rule family=ipv6 forward-port protocol=tcp port=443 to-port=8443'
sudo firewall-cmd  --add-rich-rule='rule family=ipv6 forward-port protocol=tcp port=80  to-port=8080'

# Make the new settings persistent
sudo firewall-cmd --runtime-to-permanent

If your environment has podman or buildah installed, uninstall them before proceeding.
```
sudo dnf erase podman buildah -y
```

Install PCoIP Modern Connection Manager and PCoIP Security Gateway¶

On the machine that hosts the PCoIP Connection Manager and/or the PCoIP Security Gateway, open a browser and go to the PCoIP Connection Manager and PCoIP Security Gateway download page.
Click Downloads and scripts:

If you see a login button instead, click it to log into the site and then proceed.
Accept the End User License Agreement, then click Set Up Repository:

.

The window expands and show the setup scripts for each supported operating system. Copy the command for your system to the clipboard.
Open a console window and paste in the command you copied in the previous step. You may need to press Enter to execute it.

The command fetches a configuration script from our servers and runs it locally, setting up and configuring the repository on the local machine.
Install the PCoIP Connection Manager and PCoIP Security Gateway package:
```
sudo dnf install pcoip-cmsg-setup
```
After the package is installed locally, run the pcoip-cmsg-setup install command with the required flags to complete installation.
```
sudo pcoip-cmsg-setup install <installation_flags>
```
Important: Required installation flags

There are a number of options and settings available. You can invoke the install command with the --help flag to list them:
```
pcoip-cmsg-setup install --help
```
They are also listed in the next section.

The install command prompts you for required parameters that have not been supplied via flags.

Installing Components Individually¶

To install only the PCoIP Connection Manager use --enable-security-gateway=false.
To install only the PCoIP Security Gateway use --enable-connection-manager=false.
Otherwise both the PCoIP Connection Manager and PCoIP Security Gateway are installed by default.

Deployment Scenarios¶

PCoIP Connection Manager and PCoIP Security Gateway deployed together: This is the default option when installing. There is no gateway failover in this deployment.

CMSG TCP

PCoIP Connection Manager and PCoIP Security Gateways deployed separately: There is gateway failover in this scenario.

CM Multiple Gateway

PCoIP Connection Manager and PCoIP Security Gateways deployed together and separately: There is gateway failover in this scenario.

CMSG Multiple Gateway2

Installation Flags and Options¶

The following flags can be used to provide values at the command line. Flags that are required are identified in the description.

Boolean values should be provided as either true or false, lowercased, as in this example:

--example-flag=true

Flag	Type	Description
`--accept-policies`	Boolean	Automatically accepts the EULA and Privacy Policy. Required.
`--broker-url`	String	The URL of the PCoIP Broker, specified either as a https://: or https://: or https://[]:. Required.
`--ca-cert`	String	The full path and filename of the custom Certificate Authority's public certificate to be used in the PCoIP Connection Manager and PCoIP Security Gateway. Required if `--self-signed` is not used.
`--compose-file`	String	Specify the full path to a local docker-compose file.
`--darksite-bundle-path`	string	The path of darksite install bundle to be used for darksite installation
`--docker-password`	String	Password to login to private registry.
`--docker-registry`	String	Specifies the HP source for Anyware Connector images to be install from. Debugging only: This is intended to be used for debugging purposes and should not be used without guidance from HP support. Using this flag incorrectly can result in failed installations.
`--docker-username`	String	Username to login to private registry.
`--enable-collaboration`	Boolean	Allow multiple PCoIP clients to collaborate on a PCoIP agent. (Default=true)
`--enable-ipv6`	Boolean	Enables IPv6 connections (Default=false). To enable IPv6 use `--enable-ipv6=true`. To disable IPv6 use `--enable-ipv6=false`, or omit this flag.
`--external-pcoip-ip`	StringArray	Sets the public IP address of Security Gateway. If `--enable-ipv6` is true, this option may be used twice (once for IPv4 and once for IPv6). Required if PCoIP Security Gateway is enabled
`--enable-security-gateway`	Boolean	Enable and use the PCoIP Security Gateway (Default=true).
`--help`		Lists all available flags.
`--host-address`	stringArray	Sets the host FQDN/IP address. The option may be used twice (once for the IP address and once for the FQDN)
`--ignore-disk-req`	Boolean	Ignore the check for the minimum disk space requirement.
`--license-server-url`	String	The address of the locally installed PCoIP License Server. Example: `https://<license-server-address>:<port>`
`--self-signed`	Boolean	Automatically generate self-signed SSL cert and key for testing purposes. If specified, `--ssl-key` and `--ssl-cert` options are ignored.
`--ssl-cert`	String	The full path and filename of the SSL certificate to be used in the PCoIP Connection Manager and PCoIP Security Gateway. Required if `--self-signed` is not used.
`--ssl-key`	String	The full path and filename of the SSL key to be used in the PCoIP Connection Manager and PCoIP Security Gateway. Required if `--self-signed` is not used.
`--docker-network-cidr`	Sets CIDR for Connection Manager's docker network for services. If default docker network IP range is conflict with intranet, this option should be used to solve the confliction
`--debug`	String	Sets the log verbosity higher to help with debugging installation issues.
`--enable-connection-manager`	Boolean	Enable and use the PCoIP Connection Manager (Default=true).
`--external-sg-ip`	StringArray	Sets public IP addresses of external Security Gateways to enable gateway failover if a Security Gateway becomes unavailable. IP address should be provided in the format `--external-sg-ip=ipAddr1 --external-sg-ip=ipAddr2...`
`--jwt-verifying-cert`	String	The full path and filename of the certificate that the Security Gateway should use to validate the JWT token.
`--jwt-signing-key`	String	The full path and filename of the key to sign a JWT. It is used by the Connection Manager for signing the JWT token.

Federated Authentication Flags

Flag	Type	Description
`--enable-oauth`	Boolean	Enables Oauth authentication. (Default=false)
`--id-provider-url`	String	Sets the identity provider URL. Example: `--id-provider-url https://provider-1234567890.id.provider.com`. This flag is required if `--enable-oauth is true`.
`--oauth-client-id`	String	Gets the Client ID from the Identity Provider. This flag is also required if `--enable-oauth` is "true".

Federated Authentication Single Sign-On Flags

Flag	Type	Description
`--fa-url`	String	Override the fhe Federated Auth Broker URL provided to the PCoIP Agent. This flag can be used if auto-detection is not correcting determining the connector address. for example https://cac-vm-fqdn:port
`--enable-sso`	Boolean	Enables SSO. (Default=False)
`--sso-signing-csr-ca`	String	Path to copy intermediate CA Certificate.
`--sso-signing-csr-key`	String	Path to the intermediate key.
`--sso-signing-crl`	String	Path to a certificate revocation list.
`--sso-enrollment-url`	String	Gets the URL to the Active Directory Certification Authority Web Enrollment Service.
`--sso-enrollment-domain`	String	Domain of the user to access Active Directory Certification Authority Web Enrollment Service.
`--sso-enrollment-username`	String	Username for accessing Active Directory Certification Authority Web Enrollment Service.
`--sso-enrollment-password`	String	Password for the username to access Active Directory Certification Authority Web Enrollment Service.
`--sso-enrollment-certificate-template-name`	String	Name of the certificate template that Active Directory Certification Authority Web Enrollment Service uses to sign CSR.

About Docker¶

The PCoIP Connection Manager and PCoIP Security Gateway depends on Docker 20.10.0 or higher, which must be installed on the machine before you install the PCoIP Connection Manager and PCoIP Security Gateway.

If you have not installed Docker yet, install it now.

If you are not sure if Docker is installed, or are not sure what Docker version you have, verify your Docker version first.

Verifying Docker Version¶

To verify your Docker installation and version:

SSH into the machine.
Open a console window and run the following command:
```
sudo docker -v
```
- If Docker is not installed, this command will produce an error. Installation instructions are provided in the next section.
- If you see a version number that is lower than 20.10.0, you must uninstall Docker and then re-install the supported version. Instructions for uninstalling and installing are provided in the next section.
- If you see a version number that is equal to or higher than 20.10.0, you have a compatible version of Docker already installed and can skip to PCoIP Connection Manager and PCoIP Security Gateway installation.

Uninstalling Docker¶

You'll only need to do this if you have an unsupported version of Docker already on the machine. If you haven't installed Docker yet, skip this section.

To uninstall Docker:

SSH into the machine.

Open a console window and run the following command:

sudo dnf remove docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-engine docker-ce docker-ce-cli containerd.io runc

When uninstalling is complete, proceed to Installing Docker.

Installing Docker¶

To install Docker:

If you do not have Docker installed, or if the Docker version is too low, install it using the following procedure:

SSH into the machine that hosts the PCoIP Connection Manager and/or PCoIP Security Gateway.
Open a console window, and run the following command. This removes the podman and buildah packages if they are installed (these packages conflict with Docker):
```
sudo dnf remove podman buildah
```
Run the following commands in the same console window. Note that if you copy and paste these commands into the console, you may need to press Enter again to execute the last command:
```
sudo dnf install -y dnf-utils
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install docker-ce docker-ce-cli containerd.io
```
Confirm installation:
```
sudo docker -v
```