Skip to content

Installing Connector on Ubuntu

The Anyware Connector can be installed on Ubuntu 18.04, Rocky Linux 8 or RHEL 8. The section's below outline how to download and install the Connector on these operating systems.

Upgrading a Connector

It is not possible to upgrade a Connector installed on Ubuntu to a Connector installed on RHEL or Rocky Linux. To replace a Connector installed on Ubuntu, you must install the RHEL/Rocky Linux Anyware Connector on a new virtual machine and configure it exactly the same as the existing Connector on Ubuntu.

Installing the Connector on Ubuntu

The following section outlines how to download and install the Connector on Ubuntu 18.04. There are three main steps involved in this process:

  • Downloading the Connector installer files.
  • Generating a Connector token.
  • Installing the Connector.

Prerequisite Steps

For instructions and documentation on the Connector prerequisite steps when installing on Ubuntu, see Connector System Requirements.

It is important to read and address all the prerequisites outlined.

Downloading the Connector

The following section outlines how to download the installer files for the Connector. First, connect to the machine and download the Connector files. The commands below will download the Connector archive, and extract it.

You need to ensure that you have a customer account created on our website to access the download information.

Downloading the Installer from our website

The following steps outline the current process that enables you to download the installer directly from our webiste as a tar.gz file or else run the shell script:

  1. SSH into the machine:
    ssh <username>@<server-ip-address>
    
  2. Download the installer from HP:
    • Open a web browser and navigate to the Downloads and Scripts tab on the HP support site.
    • Download the installer and upload it to the machine or run the shell script provided to download the installer to the machine.
  3. Unpackage the installer:
    • Previously the installer was extracted into the ~/v2connector directory. This location has now changed. Run the following command to extract the installer to /usr/sbin/:
      sudo tar xzvf <PATH TO FILE>/cloud-access-connector_<version>_Linux.tar.gz -C /
      

Generating a Connector Token

You are required to have a Connector token when installing the Connector. You need to create or have created a deployment prior to obtaining a token. For information on how to log into the Admin Console, see Admin Console Connection. The following section outlines how to obtain a Connector token using the Admin Console:

  1. Click Connectors from the console sidebar.
  2. Click the add connector button (+ sign located beside Connectors heading) to display the connector creation panel.
  3. Enter the following information:
    • Select the deployment you want to add the Connector to. If you do not have an existing deployment you need to create one.
    • Enter the name of the Connector.
    • Follow the step by step instructions outlined below. Alt Text
  4. Click GENERATE.
  5. Copy the Connector token by click the copy icon.
  6. Click CLOSE the exit the panel.

You can now use this Connector token when prompted during installation.

Installing the Connector

Once the files are downloaded and the access token is set, you can install the Connector. If you are not already connected, connect to the machine via SSH and navigate to the /usr/sbin directory. For information on installing the Connector for Anyware Manager and Anyware Manager as a Service, see:

If you are installing a Connector into a Anyware Manager deployment that has other Connectors already deployed, the configuration of the latest Connector installed will take precedence.

Latest Installer Version

Ensure that you are using the latest installer prior to installing or upgrading the Connector. If you are not using the latest installer, you may see one of the following errors or warnings:

  • The installer is out of date. Please obtain the latest version and try again. See Downloading the Connector for instructions.
  • The installer is out of date. Please download the latest version from teradici.bintray.com/cloud-access-connector/cloud-access-connector-0.1.1.tar.gz and try again.
  • A newer version is available. Please go to Downloading the Connector to obtain the latest.

For information on troubleshooting Connector installer issues related to this distribution change, see Installer Issues.

DNS and Name Resolution

You must ensure that you can resolve your AD domain and controller. For information on how to install and edit resolve.conf, and configure DNS name resolution, see Configuring DNS Name Resolution.

Installing the Connector for Anyware Manager

Once you have downloaded the Connector installer and have obtained a Connector token, run the following command to install Connector to the Anyware Manager instance you have just installed. The first line of this command maps the Connector token to a variable in the shell:

export token=<token from Anyware Manager admin console>
sudo cloud-access-connector install \
-t $token \
--manager-url=https://ip-address-of-cas-manager \
--external-pcoip-ip public.ipv4.clients.connect.to \
--manager-insecure

  • When you are installing the Connector for Anyware Manager you need to ensure that you enable and specify the --manager-url flag. This flag specifies the Anyware Manager URL that the Connector connects to. If it is not specified by default it will point to https://cas.teradici.com.
  • The --external-pcoip-ip flag is highly recommended to use in order to explicitly set the public IP that PCoIP Clients will connect to during PCoIP sessions. This is the public IP that the Connector is listening to on port 4172. The installer will reach out to cas.teradici.com and first try to automatically resolve the external IP; if this fails, or is not able to resolve the correct IP, this flag is required. In the case that the Connector machine doesn't have an internet connection, for example in a dark site environment, or the ingress and egress internet traffic are running through different public IPs, this flag is required.
  • The --manager-insecure flag is only required when the Connector is connecting to a Anyware Manager that is using self-signed certificates. If Anyware Manager is using trusted TLS certificates signed by a public CA, then users will not need to use the --manager-insecure command.
  • The --manager-ca-cert flag can used to provide the PEM formatted public certificate for the private CA used to sign the Anyware Manager certificate. This flag is useful if the Connector fails to fetch a certificate from the Anyware Manager.

Ensure that you use the options and flags that best suit your system architecture and requirements. If required values are not provided on the command line, you will be prompted for them. For additional flags and options, see Installation Flags and Options.

Installing the Connector for Anyware Manager as a Service

Install the Connector for Anyware Manager as a Service by running the following command:

cd /usr/sbin
sudo ./cloud-access-connector install

Ensure that you use the options and flags that best suit your system architecture and requirements. If required values are not provided on the command line, you will be prompted for them. For additional flags and options, see Installation Flags and Options.

Anyware Connector - Troubleshooting

If there is an issue installing the Anyware Connector or an existing Connector is failing, please see the troubleshooting section on Anyware Connector Connectivity. Within this section there are steps to check the following:

  • Remote Workstation connections
  • Active Directory connections
  • Anyware Connector component information

You can also view the following KB article here which provides a list of troubleshooting steps for common issues related to installing the Connector. For information on installer errors related to a change in the distribution system, see Installer Issues.

Installation Flags and Options

The following flags can be used to provide values at the command line. If they are omitted from the command and are required, you will be prompted for them:

Flag                                                        Type Description
Anyware Manager
--manager-url String Required for Anyware Manager, Specifies the Anyware Manager URL that the Connector connects to. If this is not specified it will point to https://cas.teradici.com by default, which is the URL for Anyware Manager as a Service.
--manager-ca-cert String Enables users to supply a CA certificate for Anyware Manager to enable the Connector to connect to a Anyware Manager instance using self-signed certificates.
--manager-insecure String Is required when the Connector is connecting to a Anyware Manager instance that is using self-signed certificates. If Anyware Manager is using trusted TLS certificates signed by a public CA, then users will not need to use the this command.
--ldaps-ca-cert String Enables users to supply a CA certificate for the connection to Active Directory over LDAPS.
‑‑self-signed String Installs the Connector with self-signed certificates.
This mode is not secure and is intended for testing.
The --insecure flag is still supported.
Connector
--token (-t) String Required. The token generated for Anyware Manager.
‑‑accept‑policies Automatically accept the EULA and Privacy Policy.
--force-install String Replaces any existing Connector installation.
--debug String This flag can be run if you initial install of the Connector fails. It provides a detailed output of the Connector installation. This is useful for self-troubleshooting or to provide to the HP support team when logging a support ticket.
--local-license-server-url String Sets the URL for PCoIP License Server to be used for PCoIP Sessions. If this is not provided, ensure that the Cloud License Server is registered on the PCoIP Agent. Example: --local-license-server-url http://10.10.10.10:7070/request. For more information on the PCoIP License Server, see PCoIP License Server.
--add-pool-group String Specifies one or more Active Directory groups, by entering the distinguished name (DN), to be assigned to pools for remote workstation management (eg, --add-pool-group 'CN=GroupPool1,CN=Users,DC=sample,DC=com' --add-pool-group 'CN=GroupPool2,CN=Users,DC=sample,DC=com'). By providing all the existing pools groups in the Connector settings would get replaced by the user specified ones. When running this command you need to run it with adconfig. Example: sudo ./cloud-access-connector adconfig --add-pool-group.
--setup-docker-image String Specifies the docker image to be used from the setup container. This is intended to be used for debugging purposes and is not recommended to be used without guidance from HP support. Usage without guidance could result in failed installations.
--docker-registry String This is an optional flag that enables users to specify the docker image registry that they want to use when installing or updating a Connector. If an option is not specified, the default registry docker.cloudsmith.io/teradici/cloud-access-connector will be used. This is intended to be used for debugging purposes and is not recommended to be used without guidance from HP support. Usage without guidance from HP could result in failed installations.
--prune-image Boolean Removes all unused docker images on this machine to reclaim more disk space. Warning: This command will remove all unused images under Connector and other services, if any. This is equivalent to the docker image prune command. Note: This flag is only supported for 'update' command.
--preferred-name String This is an optional flag to determine if the hostname or machine name should be displayed to identify
the remote workstations, the default is set to display machine name.
--trusted-customer-license-cert String This flag contains the filepath for Trusted customer license certificate.
--trusted-customer-license-key String This flag contains the filepath for Trusted customer license key.
--clear-trusted-customer-license Boolean Removes the Trusted customer license certificate and key.
--pull-connector-config Boolean This flag gets the Connector configuration from the Anyware Manager.
--push-connector-config Boolean This flag saves the Connector configuration into the Anyware Manager.
Firewall
--https-proxy String Specify the URL for a HTTPS proxy
(overrides related proxy settings in environment variables). Warning: HTTP Proxy support is deprecating, and it will be removed in a future release.
--connector-network-cidr String This is the CIDR to use for the Connector's docker network. The default docker network subnet is 10.101.0.0/16.
--internal-client-cidr String The CIDR for PCoIP Clients that connect to remote workstations directly. It is possible to specify multiple --internal-client-cidr networks.
--external-client-cidr String The CIDR for PCoIP Clients that connect to remote workstations through the Security Gateway. If external CIDRs settings are set, internal settings must be explicitly set. It is possible to specify multiple --external-client-cidr networks.
PCoIP Software Client
--retrieve-agent-state Boolean Enables the broker to retrieve the agent state for unmanaged and managed remote workstations.
The default value for this flag is false.
The available states are In Session, Ready, Starting, Stopping, Stopped and Unknown.
The value of this flag can either be true or false.
--show-agent-state Boolean Controls if the agent state is displayed as part of the remote workstation name in the PCoIP Client.
The default value for this flag is true.
Setting the value of this flag to true and the --retrieve-agent-state flag to false will result in no agent state displaying.
--external-pcoip-ip String Sets the public IP for PCoIP Client to PCoIP Agent connection. This is the public IP that the Connector is listening to on port 4172. The installer will reach out to cas.teradici.com and first try to automatically resolve the external IP; if this fails, or is not able to resolve the correct IP, this flag is required. In the case that the Connector machine doesn't have an internet connection, for example in a dark site environment, or the ingress and egress internet traffic are running through different public IPs, this flag is required. For more information on external network access, see Enabling External Network Access.
Domain
‑‑domain String The AD domain that remote workstations will join.
‑‑sa‑user String The Active Directory service account username.
‑‑sa‑password String The Active Directory service account password.
--domain-controller String Specifies one or more domain controllers to use with the Connector.
--users-filter String The filter to search for users within Active Directory. Specify multiple filters with multiple options. Default user filter: (&(objectCategory=person)(objectClass=user)).
--computers-filter String The filter to search for computers within Active Directory. Specify multiple filters with multiple options. Default computer filter: (&(primaryGroupID=515)(objectCategory=computer)).
‑‑users-dn StringArray The base DN to search for users within AD. Specify multiple DNs with multiple options. Newly provided base DN(s) will automatically replace previous base DN(s). This field is looking for user's within the user-defined DN and SGs.
--computers-dn StringArray The base DN to search for computers within AD. Specify multiple DNs with multiple options. Newly provided base DN(s) will automatically replace previous base DN(s).
--sync-interval uint8 The interval (in minutes) for how often to sync AD users and computers with the CASM Service.
MFA
‑‑enable‑mfa String Installs with multi-factor authentication enabled.
‑‑radius‑server String The FQDN or IP address of the RADIUS server to use for MFA.
This flag is optional.
‑‑radius‑port String The RADIUS server port.
If not specified, the default port (1812) is used.
If --radius-server is specified then this flag is optional.
‑‑radius‑secret String The shared secret used for configuring RADIUS authentication.
If --radius-server is specifed then this flag is required.
Oauth
‑‑id-provider-url String Sets the Identity Provider URL. Example: --id-provider-url https://id.provider.com
‑‑enable-oauth Boolean Enables/Disables oauth authentication (if enabled --id-provider-url and --oauth-client-id must be provided)
‑‑oauth-client-id String Sets the Oauth Application Client id
‑‑oauth-flow-code String Specify the oauth flow / grant type
‑‑oauth-server-ca String The full path and filename of Oauth Server CA certificate
‑‑fa-url String The Federated Auth Broker URL. for example https://cac-vm-fqdn:port
Single Sign-On (SSO)
--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 Certificate Services (AD CS) uses to sig CSR.
Certificates
‑‑ssl‑key String The full path and filename of the SSL key to use.
The --self-signed flag overrides this flag.
‑‑ssl‑cert String The full path and filename of the SSL certificate (in PEM format) to use.
The --self-signed flag overrides this flag.

Troubleshooting the Connector

If you encounter issues when attempting to install the Connector, please see the Troubleshooting section for information on how to potentially diagnose the specific issue. You can also view the following KB article here which provides a list of troubleshooting steps for common issues related to installing the Connector. For information on installer errors related to a change in the distribution system, see Installer Issues.

Multi-Factor Authentication

When installing the Connector you can enable multi-factor authentication (MFA) by running the ‑‑enable‑mfa flag. MFA will be disabled by default. If you want MFA to only apply to external connections, you should have separate Connectors. One Connector should be for external connections, where MFA is enabled, and one for internal or direct connections, where MFA is disabled. For steps on how to install the Connector with MFA bypassed for internal connections, see Installing the Connector for Internal Connections.

For external facing Connectors you should apply firewall and network settings, such as placing it in a DMZ for example. For external facing Connectors, ensure that you set --external-client-cidr to 0.0.0.0/0 so that everything through this Connector is treated as an external connection. It is not recommended to rely on the IP range to manage authentication levels, and for better security you should use separate Connectors.

Ensure that you use the options and flags that best suit your system architecture and requirements. If required values are not provided on the command line, you will be prompted for them. For additional flags and options, see Installation Flags and Options.

Installing the Connector for Internal Connections

The following steps outline how to install the Connector for internal connections to bypass MFA:

  1. Prepare a virtual machine in your private network that meets the system requirements with the following sub-steps:
    • Skip the step for preparing the system for external access.
    • Skip the step for setting up MFA.
  2. Install the Connector with the following sub-steps:
    • Do not set the Public IP using the --external-pcoip-ip flag. The Connector will instead return the virtual machines IP address.
    • No MFA flag is required as MFA is disabled by default.
  3. Once you have installed the Connector connect to a remote workstation with a PCoIP Software Client with the following sub-step:
    • In the Host Address or Code field enter the private IP of the internal Connector you just installed and log-in.

If you want to use the same url for an external Connector as an internal Connector, for example connector.domain.com, you must set-up an internal/private DNS. In this DNS create an entry called connector.domain.com and map it to the private IP of the internal Connector. User's will then be able to connect to this entry by entering connector.domain.com in the Host Address or Code field in the PCoIP Client. The internal connection will connect to the internal Connector, and the external connection will connect to the external Connector.

Connecting to a Remote Workstation with a PCoIP Client

After successfully installing a Connector, you can initiate a session to connect to a remote workstation with a PCoIP Software Client. We enable customers to use multi-factor authentication for these PCoIP Client sessions. The following steps outline how to connect to a remote workstation using the PCoIP Software Client:

  1. Double-click the PCoIP Client desktop icon or program file PCoIPClient to launch the application.
  2. In the Host Address or Code field, enter one of the following:
    • For direct connections, provide the address of the host machine.
    • For managed connections, provide the address of the connection manager.
  3. Click NEXT.
  4. Select your domain and enter the credentials for the remote workstation. If you have enabled MFA then you will be prompted for the 2nd factor passcode. The method of how this passcode is communicated depends on the provider you used. It is usually either a One Time Password or push notification.
  5. Click LOGIN.
  6. If your login is successful you should be able to select the remote workstation and connect to it. Please note that if you have a single remote workstation, that remote workstation is automatically selected and the connection is initiated immeadiately. In this case you will not be presented with a remote workstation selection screen.

For more information about the PCoIP Software Client, please see the following PCoIP Software Client guides: