Connection Manager Session Health Check - Diagnostics and troubleshooting guide
Summary
To receive a detailed connection manager diagnostic report, create a CM support/log file bundle and then submit this bundle to the PCoIP health check tool. Once the files are submitted, it will take 5-10 minutes to produce a detailed report. The report will be sent to your registered e-mail address.
Table of Contents
| Diagnostic or Test | Remedy if failure or error detected |
| Step 1 to 3 - Initialize/Authenticate/Get list of hosts | |
| Start session | Corrective Action: Fix IP or Domain Name issues |
| Authenticate client | Corrective Action: Fix authentication issues |
| Get a list of hosts | Corrective Action: Fix host entitlement issue |
| Step 4 - Allocate resources and Connect to Hosts | |
| Select a host | Corrective Action: Fix host entitlement issue |
| Contact host | Corrective Action: Fix host IP or Domain Name issues |
| Authenticate on host | Corrective Action: Fix host authentication issues |
| Get host ready | Corrective Action: Host is not ready |
| Host setup completed | Corrective Action: Host is not ready |
| Host allocation completed | Corrective Action: Fix host allocation issues |
| Session setup completed | |
Connection Manager Session Health Check
Initiate session ("Hello" and "Hello-resp")
A connection manager will receive a hello message from the client and it will send a hello message to the broker.
Expected Results
| Diagnostic | Results | Timestamp | SessionID | Data |
| Initiate Session | Pass | Fail | <Timestamp> |
<SessionID> |
Requests a brokered PCoIP Session | |
Corrective Action: Fix IP or Domain Name issues
- Make sure the client is able to communicate with the connection manager. If unreachable, check your ports settings (TCP port 443 may be blocked by your firewall) or your DNS/AD setting to ensure that the hostname is converted to the expected IP address and that the AD provides the expected fully qualified domain name (FQDN)
- Ensure that TCP port 636 is not blocked on the Domain Controller/ Broker
Example Logs
Example Hello Message
Received request from client (hello): <hello> <client-info> <product-name>Teradici PCoIP Desktop Client</product-name> <product-version>20.10.2</product-version> <platform>Windows Server 2016 (10.0) winnt 10.0.14393 x86_64</platform> <hostname>my-client.teradici.local</hostname> <locale>en_US</locale><serial-number>0a:dc:e5:92:ac:86</serial-number> <device-name>some-name</device-name> <pcoip-unique-id>0a:dc:e5:92:ac:86</pcoip-unique-id> </client-info> <caps> <cap>CAP_DISCLAIMER_AUTHENTICATION</cap> <cap>CAP_NO_AUTHENTICATION</cap> <cap>CAP_DIALOG_AUTHENTICATION</cap> <cap>CAP_ALTERNATE_PROVISIONING</cap> </caps> </server-address> </hello>
Example Hello Message
Sending request to PCoIP broker (hello): <hello> <client-info> <product-name>Teradici CAC Health Check</product-name> <product-version>CACv2</product-version> <platform>Docker</platform> <hostname>healthCheck</hostname> <device-name>healthCheck</device-name> <serial-number>healthCheck</serial-number> <locale>en_US</locale> </client-info> <pcm-info><product-name>PCoIP Connection Manager</product-name> <product-version>UNKNOWN</product-version> <hostname>cm1.example</hostname></pcm-info> <caps><cap>CAP_HEALTH_CHECK</cap><cap>CAP_ALTERNATE_CREDENTIALS</cap></caps> </hello>
Example Hello Response
Received response from PCoIP broker (hello-resp):
<hello-resp>
<brokers-info>
<broker-info>
<product-name>"PCoIP Broker"</product-name>
<product-version>v29.843.0.3.1199c7fffc</product-version>
<platform>"Ubuntu 18.04 LTS"</platform>
<locale>en_US</locale>
<ip-address>CHANGE_ME</ip-address>
<hostname>"broker.example"</hostname>
</broker-info></brokers-info>
<next-authentication>
<authentication-methods>
<method>AUTHENTICATE_VIA_PASSWORD</method>
</authentication-methods>
<domains><domain>domain1.example</domain></domains>
</next-authentication>
</hello-resp>
Example Hello Response
Sending response to client (hello-resp): <hello-resp> <brokers-info><broker-info> <product-name>"PCoIP Broker"</product-name><product-version>v29.843.0.3.1199c7fffc</product-version> <platform>"Ubuntu 18.04 LTS"</platform><locale>en_US</locale> <ip-address>CHANGE_ME</ip-address> <hostname>"broker.example"</hostname> </broker-info></brokers-info> <pcm-info> <product-name>PCoIP Connection Manager</product-name> <product-version>UNKNOWN</product-version><platform>GNU/Linux x86_64</platform> <ip-address>10.101.0.12</ip-address> <hostname>e29766ce435a</hostname> </pcm-info> <next-authentication> <authentication-methods> <method>AUTHENTICATE_VIA_PASSWORD</method> </authentication-methods> <domains> <domain>domain-1</domain> </domains> </next-authentication> </hello-resp>
Example Hello Error Response
Sending response to client (error-resp):
pcoip-client version="2.1">
<error-resp>
<result>
<result-id>ERR_BROKER_SYS_FAILED</result-id>
<result-str>Communication to the domain controller was not successful</result-str>
</result>
<detected-by>Broker</detected-by>
</error-resp>
</pcoip-client>
Session authentication ("authenticate" and "authenticate-resp")
The connection manager will authenticate the user using the user name and credentials provided in the "authenticate" message.
Expected Results
| Diagnostic | Results | Timestamp | SessionID | Data |
| Session Authentication | Pass | Fail | <Timestamp> |
<SessionID> |
User authenticated successfully | |
Corrective Action: Fix Authentication Issues
If the authenticate steps fails, then the authentication systems are not setup correctly, or the authentication check took to long to complete on either the connection manager or the remote host.
- Ensure the username, password and domain name is correct.
- If you are using Radius MFA, ensure TCP/UDP port 1812 is not blocked. Refer to the following article to read more about configuring MFA with PCoIP HP Anyware Manager, MFA with HP Anyware Connector
Example Logs
Example Authenticate Message
Received request from client (authenticate): <authenticate method="password"> <username>****</username> <password>****</password> <domain>domain-1</domain> </authenticate>
Example Authenticate Message
Sending request to PCoIP broker (authenticate): <authenticate method="password"> <username>****A</username> <password>****</password> <domain>domain-1</domain> </authenticate>
Example Authenticate Response Message
Received response from PCoIP broker (authenticate-resp):
<authenticate-resp method="password">
<result>
<result-id>AUTH_SUCCESSFUL_AND_COMPLETE</result-id>
<result-str>Password authentication was successful and user authentication has been completed</result-str>
</result>
</authenticate-resp>
Example Authenticate Response Message
Sending response to client (authenticate-resp): <authenticate-resp method="password"> <result> <result-id>AUTH_SUCCESSFUL_AND_COMPLETE</result-id> <result-str>Password authentication was successful and user authentication has been completed</result-str> </result> </authenticate-resp>
Example authenticate Error Response
Received response from PCoIP broker (authenticate-resp):
<authenticate-resp method="password">
<result>
<result-id>AUTH_FAILED_UNKNOWN_USERNAME_OR_PASSWORD</result-id>
<result-str>Authentication failed, please enter valid Username & Password</result-str></result>
</authenticate-resp>
Sending response to client (authenticate-resp):
<authenticate-resp method="password">
<result>
<result-id>AUTH_FAILED_UNKNOWN_USERNAME_OR_PASSWORD</result-id>
<result-str>Authentication failed, please enter valid Username & Password</result-str></result>
</authenticate-resp>
Get a List of Hosts ("get-resource-list" and "get-resource-resp")
The connection manager will ask the broker for the list of hosts that the authenticated client can connect to.
Expected Results
| Diagnostic | Results | Timestamp | SessionID | Data |
| Get a list of hosts | Pass | Fail | <Timestamp> |
<SessionID> |
Successfully retrieved the list of resources | |
Corrective Action: Fix entitlement issue
If the CM does not return the list of hosts, probably the hosts are not being added to workstations list or no user has been assigned to the workstation. Refer to the admin guide link for information on adding workstations, adding Remote Workstations
Example Logs
Example get-resource-list Message from Client to CM
Received request from client (get-resource-list): <get-resource-list> <protocols><protocol>PCOIP</protocol></protocols> <resource-types><resource-type>DESKTOP</resource-type></resource-types> </get-resource-list>
Example get-resource-list Message
Received request from client (get-resource-list): <get-resource-list> <protocols><protocol>PCOIP</protocol></protocols> <resource-types> <resource-type>DESKTOP</resource-type> </resource-types> </get-resource-list>
Example get-resource-list Message
Sending request to PCoIP broker (get-resource-list): <get-resource-list> <protocols><protocol>PCOIP</protocol></protocols> <resource-types> <resource-type>DESKTOP</resource-type> </resource-types> </get-resource-list></pcoip-broker>
Example get-resource-list-resp message
Received response from PCoIP broker (get-resource-list-resp): <get-resource-list-resp> <result><result-id>LIST_SUCCESSFUL</result-id> <result-str>Successfully retrieved the list of resources</result-str></result> <resource> <resource-name>My-Desktop</resource-name> <resource-id>600b5fb4bc906288e9b08f84</resource-id> <resource-type session-type="VDI">DESKTOP</resource-type> <resource-state>UNKNOWN</resource-state> <protocols><protocol is-default="true">PCOIP</protocol></protocols> </resource> <resource> <resource-name>My-Desktop2</resource-name> <resource-id>6015b54657035ebc622426e9</resource-id> <resource-type session-type="VDI">DESKTOP</resource-type> <resource-state>UNKNOWN</resource-state> <protocols><protocol is-default="true">PCOIP</protocol></protocols> </resource> </get-resource-list-resp>
Example get-resource-list-resp message to Client
Sending response to client (get-resource-list-resp): <?xml version="1.0" encoding="UTF-8"?><pcoip-client version="2.1"> <get-resource-list-resp> <result><result-id>LIST_SUCCESSFUL</result-id> <result-str>Successfully retrieved the list of resources</result-str> </result> <resource> <resource-name>My-Desktop1</resource-name> <resource-id>600b5fb4bc906288e9b08f84</resource-id> <resource-type session-type="VDI">DESKTOP</resource-type> <resource-state>UNKNOWN</resource-state> <protocols> <protocol is-default="true">PCOIP</protocol> </protocols> </resource> <resource> <resource-name>My-Desktop2</resource-name> <resource-id>6015b54657035ebc622426e9</resource-id> <resource-type session-type="VDI">DESKTOP</resource-type> <resource-state>UNKNOWN</resource-state> <protocols> <protocol is-default="true">PCOIP</protocol> </protocols> </resource> </get-resource-list-resp>
Example entitlement Error Response
Received response from PCoIP broker (get-resource-list-resp):
<pcoip-broker version="2.1">
<get-resource-list-resp>
<result><result-id>LIST_FAILED_NO_ENTITLEMENT</result-id>
<result-str>User has not been assigned any remote workstations</result-str>
</result>
</get-resource-list-resp>
</pcoip-broker>
Sending response to client (get-resource-list-resp):
<pcoip-client version="2.1">
<get-resource-list-resp>
<result><result-id>LIST_FAILED_NO_ENTITLEMENT</result-id>
<result-str>User has not been assigned any remote workstations</result-str>
</result>
</get-resource-list-resp>
</pcoip-client>
Prepare Host ("allocate-resource" and "allocate-resource-resp")
The connection manager will ask the host to prepare the desktop for a PCoIP session.
Expected Results
| Diagnostic | Results | Timestamp | SessionID | Data |
| Allocate Resource | Pass | Fail | <Timestamp> |
<SessionID> |
Successfully allocated remote workstation | |
Corrective Action: Fix remote host not ready issues
If the allocate-resource-resp is not received or an error message is not ALLOC_SUCCESSFUL then the problem is likely due to an issue on the host. Either the host is not active, or TCP 60443 is not open on host machine.
Example Logs
Example allocate-resource Message from Client to CM
Received request from client (allocate-resource): <allocate-resource> <resource-id>601c331ec3691f36182bfc48</resource-id> <protocol>PCOIP</protocol> <client-info> <time-zone-windows>Pacific Standard Time</time-zone-windows> <ip-address>xx.xx.xx.xx</ip-address> <mac-address>0a:dc:e5:92:ac:86</mac-address> </client-info> </allocate-resource>
Example allocate-resource Message
Sending request to PCoIP broker (allocate-resource): <allocate-resource> <resource-id>601c331ec3691f36182bfc48</resource-id> <protocol>PCOIP</protocol> <client-info> <time-zone-windows>Pacific Standard Time</time-zone-windows> <ip-address>xx.xx.xx.xx</ip-address> <mac-address>0a:dc:e5:92:ac:86</mac-address> </client-info> </allocate-resource>
Example allocate-resource-resp Message
Received response from PCoIP broker (allocate-resource-resp):
<allocate-resource-resp>
<result>
<result-id>ALLOC_SUCCESSFUL</result-id>
<result-str>Successfully allocated remote workstation</result-str>
</result>
<target>
<ip-address>xx.xx.xxx.xx</ip-address>
<hostname>My-Desktop1</hostname>
</target>
<resource-id>601c331ec3691f36182bfc48</resource-id>
<protocol>PCOIP</protocol>
</allocate-resource-resp>
Example allocate-resource-resp Error Response
Received response from PCoIP broker (allocate-resource-resp):<pcoip-broker version="2.1">
<allocate-resource-resp>
<result><result-id>ALLOC_FAILED_INVALID_PARAMETER</result-id>
<result-str>Resource does not exist in CAM Service</result-str>
</result>
</allocate-resource-resp>
</pcoip-broker>
Example allocate-resource-resp Error Response
Received response from PCoIP broker (allocate-resource-resp):
<pcoip-broker version="2.1">
<allocate-resource-resp>
<result>
<result-id>ALLOC_PENDING_TRY_AGAIN</result-id>
<result-str>The PCoIP agent on 10.0.4.4 is unreachable. Please try to connect again.</result-str>
</result>
</allocate-resource-resp>
</pcoip-broker>
Initiate session on host ("Hello" and "Hello-resp")
A "hello" is the message received by host and indicates the start of the connection negotiation with a particular host. The host will prepare and send the response message to the sender.
Expected Results
| Diagnostic | Results | Timestamp | SessionID | Data |
| Initiate Session | Pass | Fail | <Timestamp> |
<SessionID> |
Received hello command | |
Corrective Action: Fix remote host not ready issues
Make sure the host is able to communicate with the connection manager. If unreachable, check your ports settings (443 may be blocked by your firewall).
Example hello message
Sending request to PCoIP agent using PCoIP Broker Protocol (hello):
<hello>
<client-info><product-name>Teradici PCoIP Desktop Client</product-name>
<product-version>20.10.2</product-version>
<platform>Windows Server 2016 (10.0) winnt 10.0.14393 x86_64</platform>
<locale>en_US</locale>
<serial-number>0a:dc:e5:92:ac:86</serial-number>
<pcoip-unique-id>0a:dc:e5:92:ac:86</pcoip-unique-id>
</client-info>
<pcm-info>
<product-name>PCoIP Connection Manager</product-name>
<product-version>UNKNOWN</product-version>
<platform>GNU/Linux x86_64</platform>
<ip-address>10.101.0.12</ip-address>
<hostname>e29766ce435a</hostname>
</pcm-info>
<caps><cap>CAP_DISCLAIMER_AUTHENTICATION</cap><cap>CAP_NO_AUTHENTICATION</cap><cap>CAP_DIALOG_AUTHENTICATION</cap><cap>CAP_ALTERNATE_PROVISIONING</cap><cap>CAP_ALTERNATE_CREDENTIALS</cap></caps>
</hello>
Example hello response
Received response from PCoIP agent using PCoIP Broker Protocol (hello-resp): <hello-resp> <brokers-info><broker-info> <product-name>PCoIP Standard Agent for Windows Direct-Connect Broker</product-name> <product-version>20.10.2</product-version> <platform>Windows</platform> <locale>en_US</locale> <ip-address>10.0.4.5</ip-address> <hostname>Win-std2</hostname> </broker-info></brokers-info> <next-authentication><authentication-methods><method>AUTHENTICATE_VIA_PASSWORD</method></authentication-methods> <domains> <domain>domain-1</domain> </domains> </next-authentication> <broker-to-client-variables><variable><name>OID25071-support-url</name><value>techsupport.teradici.com</value></variable></broker-to-client-variables> </hello-resp>
Session authentication on host ("authenticate" and "authenticate-resp")
The host will authenticate the user using the user name and credentials provided in the "authenticate" message.
Expected Results
| Diagnostic | Results | Timestamp | SessionID | Data |
| Session authentication | Pass | <Timestamp> |
<SessionID> |
Received authenticate-password command| |
Corrective Action: Fix remote host not ready issues
Ensure that the AD domain is reachable from the host machine and the host is joined to the correct domain.
Example Authenticate message
Sending request to PCoIP agent using PCoIP Broker Protocol (authenticate): <authenticate method="password"> <username>****</username> <password>****</password> <domain>domain-1</domain> </authenticate>
Example Authenticate Response
Received response from PCoIP agent using PCoIP Broker Protocol (authenticate-resp):
<authenticate-resp method="password">
<result>
<result-id>AUTH_SUCCESSFUL_AND_COMPLETE</result-id>
<result-str>User authenticated successfully.</result-str>
</result>
</authenticate-resp>
Example Authenticate Error Response
Sending request to PCoIP agent using PCoIP Broker Protocol (authenticate):
<pcoip-client version="2.1" encoding="UTF-8">
<authenticate method="password">
<username>cas_admin</username>
<password>****</password>
<domain>domain-1</domain>
</authenticate>
</pcoip-client>
Received response from PCoIP agent using PCoIP Broker Protocol (authenticate-resp):
<pcoip-client version="2.1">
<authenticate-resp method="password">
<result>
<result-id>AUTH_FAILED_UNKNOWN_USERNAME_OR_PASSWORD</result-id>
<result-str>User authentication failed. Please re-enter username, password, and/or domain.</result-str>
</result>
</authenticate-resp>
</pcoip-client>
ERROR PCoIPBrokerProtocolAgent : PBP_R_ALLOC_FAILED_UNKNOWN_USERNAME_OR_PASSWORD (Failed to establish a remote session due to invalid username, password, and/or domain.) Detail: [PCoIPAgent] AUTH_FAILED_UNKNOWN_USERNAME_OR_PASSWORD: User authentication failed. Please re-enter username, password, and/or domain.
Prepare Host ("allocate-resource" and "allocate-resource-resp")
The host will prepare the desktop for a PCoIP session and will confirm that the host is healthy to the sender of the allocate-resource message.
Expected Results
| Diagnostic | Results | Timestamp | SessionID | Data |
| Prepare Host? | Pass | <Timestamp> |
<SessionID> |
Received allocate-resource command |
Example allocate resource message
Sending request to PCoIP agent using PCoIP Broker Protocol (allocate-resource):
<allocate-resource>
<resource-id>1</resource-id>
<protocol>PCOIP</protocol>
<client-info>
<client-name>my-client</client-name>
<time-zone-windows>Pacific Standard Time</time-zone-windows>
<ip-address>10.12.34.151</ip-address>
<mac-address>0a:dc:e5:92:ac:86</mac-address>
</client-info>
<license-server />
</allocate-resource>
Example allocate-resource resp from host
Received response from PCoIP agent using PCoIP Broker Protocol (allocate-resource-resp):
<allocate-resource-resp>
<result>
<result-id>ALLOC_SUCCESSFUL</result-id>
<result-str>Resource was allocated successfully.</result-str>
</result>
<target>
<ip-address>10.0.4.5</ip-address>
<hostname>My-Desktop1</hostname>
<sni>Win-std2</sni>
<port>4172</port>
<session-id>2305843009213693952
</session-id>
<connect-tag>SCS1****LknduKcwa9YA</connect-tag>
</target>
<resource-id>1</resource-id>
<protocol>PCOIP</protocol>
</allocate-resource-resp>
Example Bye message
Sending request to PCoIP agent using PCoIP Broker Protocol (bye): <pcoip-client version="2.1" encoding="UTF-8"> <bye /> </pcoip-client>
Example Bye response
Received response from PCoIP agent using PCoIP Broker Protocol (bye-resp): <pcoip-client version="2.1"> <bye-resp /> </pcoip-client>
Example allocate-resource resp to client
Sending response to client (allocate-resource-resp): <?xml version="1.0" encoding="UTF-8"?><pcoip-client version="2.1"><allocate-resource-resp> <result> <result-id>ALLOC_SUCCESSFUL</result-id> <result-str>Successfully allocated remote workstation</result-str> </result> <target> <ip-address>10.0.4.5</ip-address> <hostname>My-Desktop1</hostname> <sni>Win-std2</sni> <port>4172</port> <session-id>2305843009213693952</session-id> <connect-tag>SCS1****LknduKcwa9YA</connect-tag> </target> <resource-id>601c331ec3691f36182bfc48</resource-id> <protocol>PCOIP</protocol> </allocate-resource-resp> </pcoip-client>
Setup Session complete ("bye" and "bye-resp")
Once the host of ready, the connection manager will inform the host that the local connection preparation is complete .
Expected Results
| Diagnostic | Results | Timestamp | SessionID | Data |
| Session Setup | Pass | Fail | <Timestamp> |
<SessionID> |
Session setup completed | |
Example Logs
Example "bye" Message
Received request from client (bye): <pcoip-client version="2.1"> <bye /> </pcoip-client>
Sending request to PCoIP broker (bye): <pcoip-broker version="2.1"> <bye /> </pcoip-broker>
Example "bye-resp" Message
Received response from PCoIP broker (bye-resp): <pcoip-broker version="2.1"> <bye-resp /> </pcoip-broker>
Sending response to client (bye-resp): <pcoip-client version="2.1"> <bye-resp /> </pcoip-client>