Licensing The Graphics Agent for macOS¶
The Graphics Agent for macOS must be assigned a valid PCoIP session license before it will work. Until you've registered it, you can't connect to the desktop using a PCoIP client.
You receive a registration code when you purchase a pool of licenses from Teradici. Each registration code can be used multiple times; each use consumes one license in its pool.
Note: Registration code format
Registration codes look like this: ABCDEFGH12@AB12-C345-D67E-89FG
PCoIP agent license registrations are managed automatically by Teradici's Cloud Licensing service. If necessary, you can manage them yourself, using your own locally-installed PCoIP license server instead.
If you need to purchase licenses, contact Teradici.
Troubleshooting Licensing Issues¶
If you're encountering problems with Teradici licensing, refer to Troubleshooting License Issues.
Using Teradici Cloud Licensing¶
To use Cloud Licensing, all you need to do is provide a registration code for each PCoIP agent in your deployment (the same registration code can be used multiple times).
To provide the registration code:
SSH into the agent machine, and invoke pcoip-register-host
with the license registration code and proxy settings if required:
sudo pcoip-register-host --registration-code=<XXXXXX@YYY-YYYY-YYY> [--proxy-server=<proxy-server-address>] [--proxy-port=<proxy-port-number>]
Important: Allowlist network blocks for Teradici Cloud Licensing
If you are using Teradici Cloud Licensing, you will need to add the following to your allowlist:
- teradici.flexnetoperations.com
- teradici.compliance.flexnetoperations.com
If you use an IP-based allowlist, we recommend your IT team add the following network blocks to your allowlist:
-
IPv4: 185.146.155.64/27
-
IPv6: 2620:122:f005::/56
Important: Migrating from the previous specification
Previously, our allowlist specification looked like this:
- Production: 64.14.29.0/24
- Disaster Recovery: 64.27.162.0/24
If you have an existing implementation using an IP-based allowlist like this, we recommend you leave it in place until the new allowlist is active and tested.
Licensing PCoIP Agents With a Local License Server¶
In deployments where PCoIP agents cannot access the internet, or where cloud-based licensing is not permitted or desired, a local PCoIP License Server can be used instead. The PCoIP License Server manages PCoIP session licenses within your private environment.
Configuring PCoIP agents to use a local license server is done in one of two ways, depending on whether your deployment uses a PCoIP Connection Manager, or whether your PCoIP clients connect directly to PCoIP agents.
Brokered Environment Licensing¶
In brokered deployments, the license server address is configured in the Connection Manager, which passes it through to its managed PCoIP agents.
Local license validation using a Graphics Agent for macOS and a brokered connection
When using a Connection Manager, the license server address is only configured once no matter how many PCoIP agents are behind the Connection Manager.
To set the License Server URL in the Connection Manager:
-
On the Connection Manager machine, use a text editor to open /etc/ConnectionManager.conf.
-
Set the
LicenseServerAddress
parameter with the address of your local license server:- http://
{license-server-address}
:{port}
/request
- http://
-
Save and close the configuration file.
-
Restart the Connection Manager.
Verifying Your Brokered Licensing Configuration¶
To verify your system's licensing configuration, run pcoip-validate-license
from the console on the Graphics Agent for macOS machine. The command will ping the license server and attempt to retrieve information on an available license:
sudo pcoip-validate-license ‑‑license-server-url <license-server-address> [‑‑proxy-server <proxy-server-address>] [‑‑proxy-port <proxy-port-number]
Where <license-server-address>
is the address of the license server to ping, formatted as http://{license-server-address}
:{port}
/request
If the license server is behind a proxy server, provide the proxy information via the ‑-proxy-server
and ‑-proxy-port
parameters.
If successful, the response will show that a valid license was found on the license server, and its expiration date.
If the connection is unsuccessful, investigate the following possibilities:
-
The license server address is incorrect, or formatted incorrectly.
-
The license server is inaccessible.
-
There are no available licenses on the license server.
pcoip-validate-license
will only return a positive response if there is at least one available session license. -
If you have only one license on the license server and run
pcoip-validate-license
from a PCoIP session, the command will fail because you are currently using the single license. In this scenario, disconnect your PCoIP session and try again from an SSH session instead.
Unbrokered Environment Licensing¶
In direct, or unbrokered, deployments, each PCoIP agent is configured with the license server address via a local agent setting. When a client initiates a new PCoIP session, the PCoIP agent uses its local configuration to communicate with the license server.
Local license validation using a Graphics Agent for macOS and a direct (unbrokered) connection
Each PCoIP agent in your environment must be individually configured with the license server's URL.
To configure the License Server URL on the Graphics Agent for macOS machine:
-
Add or modify the
pcoip.license_server_path
directive.In this command, replace
{LICENSE_SERVER_PATH}
and{LICENSE_SERVER_PORT}
with your own values:sudo defaults write "/Library/Preferences/com.teradici.pcoip-agent.plist" pcoip.license_server_path "https://{LICENSE_SERVER_PATH}:{LICENSE_SERVER_PORT}/request";
-
If the license server is behind a proxy server, provide the proxy information.
In this command, replace
{PROXY_SERVER_PATH}
and{PROXY_PORT}
with your own values:sudo defaults write "/Library/Preferences/com.teradici.pcoip-agent.plist" pcoip.license_proxy_server {PROXY_SERVER_PATH} sudo defaults write "/Library/Preferences/com.teradici.pcoip-agent.plist" pcoip.license_proxy port {PROXY_PORT};
The changes will take effect on the next PCoIP session.
Verifying Your Unbrokered Licensing Configuration¶
To verify your system's licensing configuration, run pcoip-validate-license
from the console on the Graphics Agent for macOS machine. The command will ping the license server and attempt to retrieve information on an available license:
sudo pcoip-validate-license ‑‑license-server-url <license-server-address> [‑‑proxy-server <proxy-server-address>] [‑‑proxy-port <proxy-port-number]
Where <license-server-address>
is the address of the license server to ping, formatted as http://{license-server-address}
:{port}
/request
If the license server is behind a proxy server, provide the proxy information via the ‑-proxy-server
and ‑-proxy-port
parameters.
If successful, the response will show that a valid license was found on the license server, and its expiration date.
If the connection is unsuccessful, investigate the following possibilities:
-
The license server address is incorrect, or formatted incorrectly.
-
The license server is inaccessible.
-
There are no available licenses on the license server.
pcoip-validate-license
will only return a positive response if there is at least one available session license. -
If you have only one license on the license server and run
pcoip-validate-license
from a PCoIP session, the command will fail because you are currently using the single license. In this scenario, disconnect your PCoIP session and try again from an SSH session instead.