Host Health Check - Diagnostics and troubleshooting guide
Summary
To receive a detailed host diagnostic report, create a client 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.
Host Diagnostics Summary
| ||||||||
| ||||||||
|
- [1] Diagnostic is LINUX specific. Not applicable to Windows or MAC.
- [2] Diagnostic is only available on Graphic Agents on Linux or Windows. Not applicable to agents running on a MAC. Not available on Linux or Windows systems running Standard Agents.
Host Health Checks
Host Report Timeline
Shows the time period that the report covers including the session ids and the timezone used. The diagnostic returns:
Pass: | Logs were found |
Fail: | Logs were not found. |
Data Collected:
Session: <X>, <Y>, <Z>. Time are reported in UTC. The local time on the client is: <date> |
Implementation Details:
Category:
This diagnostic is checked at install time.
Implementation Steps:
- Step 1: Final all pcoip_service files. The files in scope are the 6 most recent sessions. Every time a session is established, a pcoip_server is created. See example (a)
- Step 2: Find all pcoip_agent* files. Usually just one file however if the start date above is not found in the first agent file, then additional agent files will need to be collected.
- Step 2: Record the session IDs associated with the 6 sessions. Put the session Ids into the DATA area
- Step 3: Put the local start time in the Data area. See log pattern (d)
Time Period:
- The diagnostic start time is the log timestamp in the first line of the first file that is in scope. See example (b)
- The diagnostic end time is the log timestamp in the last line of the last file that is in scope. See example (c)
Example (a) how to find the files that are in scope.
Example (b) find the start time: First line of the oldest file in scope.
2021-07-08T00:40:48.635Z ff0eb200-c1b2-1039-84d6-000000000000 > LVL:2 RC: 0 COMMON :local time 2021-07-07T17:40:48.635-08:00 2021-07-08T00:40:48.635Z ff0eb200-c1b2-1039-84d6-000000000000 > LVL:2 RC: 0 COMMON :-- pcoip_server begins. 2021-07-08T00:40:48.635Z ff0eb200-c1b2-1039-84d6-000000000000 > LVL:2 RC: 0 COMMON :--------------------------
Example (c) find the end time: Last line of the newest pcoip_agent file.
2021-07-08T00:54:46.176Z 00000000-0000-0000-0000-000000000000 ...
Example (d) find the local start time: first line of the oldest file in scope.
2021-07-08T00:40:48.635Z ff0eb200-c1b2-1039-84d6-000000000000 > LVL:2 RC: 0 COMMON :local time 2021-07-07T17:40:48.635-08:00
Agent Type
Shows the type of Agent installed on the host. The diagnostic returns:
Pass: | Agent found and agent server has launched successfully. |
Fail: | Agent server was unable to launch. |
Data Collected:
PCoIP Graphics Agent for Windows | PCoIP Graphics Agent for Linux | PCoIP Standard Agent for Windows | PCoIP Graphics Agent for Linux | PCoIP Graphics Agent for MacOS |
Corrective Actions (if diagnostic does not pass)
|
Implementation Details:
Category:
This diagnostic is checked at install time.
Once the first diagnostic is displayed, subsequent matches should only be displayed if the value changes from the previous displayed value.
Implementation Steps:
- Step 1: Find Agent Type. See log pattern (a)
- Step 2: Ensure that the server has started correctly. See log pattern (b)
- Timeout: Step 2 should occur within 10 seconds of Step 1.
Time Period:
- The diagnostic starts time is associated with Step 1. The end time is associated with Step 2.
Example (a) of agent type as reported by the PCoIP Agent Log:
LVL:2 RC: 0 AGENT :Agent type: PCoIP Graphics Agent for Windows
Example (b) of agent server starting as reported by the PCoIP Agent Log:
LVL:2 RC: 0 AGENT :Prepare launch succeeded.
Example (c) of agent not started due to VMWare PCoIP agent. Log is in log:"C:\ProgramData\VMware\VDM\logs\":
2020-09-28T21:21:36.599Z 00000000-0000-0000-0000-000000000000 > LVL:2 RC: 0 SERVER :PCoIP server launched with parameters, mbx:1 adr:127.0.0.1 session_type:vdi ip_family:IPv4
SW Version
Shows the software version of Agent installed on the host. The diagnostic returns:
Pass: | Agent version found is fully supported. |
Warning: | Agent version found is old and out of support. Recommend upgrading |
Data Collected:
21.03.4 |
Corrective Actions (if diagnostic does not pass)
|
Implementation Details:
Category:
This diagnostic is checked at install time.
Once the first diagnostic is displayed, subsequent matches should only be displayed if the value changes from the previous displayed value.
Implementation Steps:
- Step 1: Find Agent Type. See log pattern (a)
Time Period:
- The diagnostic starts time is associated with Step 1. The end time is associated with Step 1.
Example (a) of agent type and software versions numbers as reported by the PCoIP Agent Log:
LVL:2 RC: 0 AGENT :Software package version: 20.10.2 (use this when reporting problems)
Operating System
Shows details on the host OS. Diagnostic returns:
Pass: | OS is compatible with the installed Agent |
Warning: | OS upgrade is recommended. |
Data Collected:
Apple MacOS (version) | Windows 10 (10.0 build 18363) | Linux (version) |
Corrective Actions (if diagnostic does not pass)
The administration guides provide details on the minimum requirements for the host. To ensure that your host is healthy, compare the OS values found in the PCoIP Agent logs to ensure that your host does conform to the latest recommendations.
|
Implementation Details:
Category:
This diagnostic is checked at install time.
Once the first diagnostic is displayed, subsequent matches should only be displayed if the value changes from the previous displayed value.
Implementation Steps:
- Step 1: Find OS Type and version. See log pattern (a)
- Step 2: Determine if OS is supported.
- Timeout: Step 2 should be within 2 seconds for step 1.
Time Period:
- The diagnostic starts time is associated with Step 1. The end time is associated with Step 1.
Example (a) of OS information in the PCoIP Agent logs:
LVL:2 RC: 0 COMMON :Linux 3.10.0-862.9.1.el7.x86_64 (Generic) LVL:2 RC: 0 COMMON :24 processors detected LVL:2 RC: 0 COMMON :62670MB/63910MB of physical memory available
LVL:2 RC: 0 TBD
Memory Check
Shows details on the client OS. Diagnostic returns:
Pass: | Agent has enough memory for basic is compatible with the installed agent |
Warning: | OS may not be compatible with the installed agent |
Fail: | Memory found on the agent is below recommended minimum |
Data Collected:
Windows 10 Professional (10.0 build 18363) | Darwin 20.3.0 (Apple MacOS) | Linux 5.8.0-48-generic (Generic) 3848MB/8191MB of physical memory available: 8MB |
Corrective Actions (if diagnostic does not pass)
|
Implementation Details:
Category:
This diagnostic is checked at install time.
Once the first diagnostic is displayed, subsequent matches should only be displayed if the value changes from the previous displayed value.
Implementation Steps:
- Step 1: Find Client Memory available. See log pattern (a) or (b) or (c).
Time Period:
- The diagnostic starts time is associated with Step 1. The end time is associated with Step 1.
Example (a) OS information (Windows)
LVL:2 RC: 0 COMMON :**** System Info
LVL:2 RC: 0 COMMON :3551MB/8065MB of physical memory available
LVL:2 RC: 0 COMMON :134213460MB/134217727MB of virtual memory available
LVL:2 RC: 0 COMMON :***
Example (b) OS information (MAC)
LVL:2 RC: 0 COMMON :**** System Info
LVL:2 RC: 0 COMMON :8543MB/40960MB of physical memory available
LVL:2 RC: 0 COMMON :****
Example (c) OS information (Linux)
LVL:2 RC: 0 COMMON :**** System Info
LVL:2 RC: 0 COMMON :6668MB/7961MB of physical memory available
LVL:2 RC: 0 COMMON :*****
Host Certificate Validation
Shows the status of your certificate. Diagnostic returns:
Pass: | Certificate was successfully verified |
Warning: | Certificate was not successfully verified |
Fail | Certificate was not found |
Data Collected:
BROKER : thumbprint hash comparison succeeded | BROKER : Certificate 10.0.158.109 fails verification |
Corrective Actions (if diagnostic does not pass)
| ||||
| ||||
|
Implementation Details:
Category:
This diagnostic is checked at install time.
Once the first diagnostic is displayed, subsequent matches should only be displayed if the value changes from the previous displayed value.
Implementation Steps:
- Step 1: Find certificate result. See log pattern (a) or (b)
- Timeout: Not Applicable.
Time Period:
- The diagnostic starts time is associated with Step 1. The end time is associated with Step 1.
Example (a) The PcoIP logs will show the following when the client was able to successfully open a secure channel with the remote server/host:
LVL:2 RC: 0 SCNET :(scnet_validate_by_thumbprint_hash): thumbprint hash comparison succeeded
The PCoIP logs also show the certificate details as provided by the server/host:
LVL:2 RC: 0 CERTIFICATE :(scnet_client_open_ssl): Certificate sent by the Janus server to open the SSL connection: LVL:2 RC: 0 CERTIFICATE : --> Signature Algorithm: sha256WithRSAEncryption LVL:2 RC: 0 CERTIFICATE : --> Issuer: C=in,ST=mh,L=pune,O=teradici,OU=gss,CN=jt LVL:2 RC: 0 CERTIFICATE : --> Not Before: May 13 04:30:19 2020 GMT LVL:2 RC: 0 CERTIFICATE : --> Not After : May 13 04:30:19 2021 GMT LVL:2 RC: 0 CERTIFICATE : --> Subject: C=in,ST=mh,L=pune,O=teradici,OU=gss,CN=*.domain.local LVL:2 RC: 0 CERTIFICATE : --> Subject Public Key Info: LVL:2 RC: 0 CERTIFICATE : --> Public Key Algorithm: rsaEncryption LVL:2 RC: 0 CERTIFICATE : --> RSA Public-Key: (3072 bit) LVL:2 RC: 0 CERTIFICATE : --> keyid:26:C5:60:A5:CA:C2:E4:8B:AD:22:40:BD:86:8A:59:A0:2E:F8:5E:32 LVL:2 RC: 0 CERTIFICATE : --> CA:TRUE LVL:2 RC: 0 CERTIFICATE : --> Digital Signature, Non Repudiation, Key Encipherment, Data Encipherment LVL:2 RC: 0 CERTIFICATE : --> email:test@mycompany.com LVL:2 RC: 0 SCNET :(scnet_validate_by_thumbprint_hash): thumbprint hash comparison succeeded LVL:2 RC: 0 SCNET :(scnet_client_open): Connected to 10.0.158.109:4172
Example (b) of the PcoIP logs when the client certificates are unknown or not valid:
LVL:1 RC:-500 CERTIFICATE :verify_certificate: Certificate 10.0.158.109 fails verification
Is host Ultra compatible?
Shows if the Host CPU is compatible with PCoIP ULTRA .
If you desire to use PCoIP Ultra then both the host and client must use a CPU that has a AVX2 instruction set.
Diagnostic returns:
Pass: | Host can be used with PCoIP Ultra. |
Warning: | Host cannot be used with PCoIP Ultra. |
Data Collected:
CPU supports AVX2 | CPU does not support AVX2 |
Corrective Actions (if diagnostic does not pass)
If AVX2 is not supported and you want to use ULTRA, then upgrade the host CPU or alternatively connect to a host that does support AVX2. See Advanced Vector Extension (AVX2) history for processors that support AVX2.
Implementation Details:
Category:
This diagnostic is checked at install time.
Once the first diagnostic is displayed, subsequent matches should only be displayed if the value changes from the previous displayed value.
Implementation Steps:
- Step 1: Find AVX2 details. See log pattern (a) or (b)
Time Period:
- The diagnostic starts time is associated with Step 1. The end time is associated with Step 1.
Example (a): host logs showing AVX2 as supported:
LVL:0 RC: 0 COMMON :cpu_intrinsics_report: CPU supports AVX2
Example (b): host logs showing AVX2 as not supported:
LVL:0 RC: 0 COMMON :cpu_intrinsics_report: CPU does not supports AVX2
Client time zone
Shows details of the client time zone. Diagnostic returns:
Pass: | Client time zone information is available in the logs |
Fail: | <TBD> E.g., Client time zone is not available in the logs |
Data Collected:
Client time zone setting is India Standard Time |
Corrective Actions (if diagnostic does not pass)
<TBD>
License Configuration
Shows if the Agent is configured to use either the cloud licensing service or a local license server.
Diagnostic returns:
Pass: | Host is setup to be used with either the cloud licensing service or a local license server. |
Fail: | Licensing is not configured. |
Data Collected:
Host ID: [ <id> | unavailable | unknown] Server ID: [ <id> | unknown] PCoIP License is: [not configured | using a Cloud Server | using a local license server] URL: [https://.....] Root Cause: (if diagnostic fails) [Host Id allocated to a different organization | Host Id has changed | Host Id is unavailable | Host Id is unknown | Licensing is not configured] |
Corrective Actions (if diagnostic does not pass)
| ||||||||||||||||
| ||||||||||||||||
| ||||||||||||||||
| ||||||||||||||||
| ||||||||||||||||
|
Implementation Details:
Category:
This diagnostic is checked at install time.
Once the first diagnostic is displayed, subsequent matches should only be displayed if the value changes from the previous displayed value.
Implementation Steps:
- Step 1: Set default values
- set Status = Failed.
- set ConfigStatus = "Not Configured"
- set Host id = "id unknown"
- set Server id = "id unknown"
- Step 2: Is the URL defined?
- If URL matches pattern (a)
- ConfigStatus = "using a Cloud Server" otherwise
- Status = Passed
- else if URL matches pattern (b)
- ConfigStatus = "using a Local License Server"
- Status = Passed
- If URL matches pattern (a)
- Step 3: Find FNE debug dump where server IDs is kept.
- If FNE debug dump is found then
- Server id = <value of the License Server ID> in pattern (c)
- If FNE debug dump is found then
- Step 4: Find the Host ID
- If pattern is found. See pattern (d-success)
- host id = <value found>.
- If pattern is not found. See pattern (d-failure)
- host id = "ID is unavailable"
- If pattern is found. See pattern (d-success)
- Step 5: Find specific error conditions for failures
- If Status == Failed then try and find pattern (e). If found,
- Reason = "Host Id is registered to a different organization".
- if Status == Failed then try and find pattern (f). If found,
- Reason = "Host Id has changed"
- If Status == Failed then try and find pattern (e). If found,
Time Period:
- The diagnostic starts time is not in the logs.
- Since this diagnostic is from data in PcoIP Support Log, the diagnostic should appear after the initial Host Report diagnostic.
- This diagnostic should always appear in the health check.
Example (a): License Server URL (Cloud licensing)
- Windows: in log file: PCoIPSupport_Log
- Linux/MAC: in the log file found in the out folder: file pcoip-validate-license --verbose
Licenses available from https://teradici.compliance.flexnetoperations.com/instances/XXXXXXXXXX/request
Example (b): License Server URL (Local License Server)
- Windows: in log file: PCoIPSupport_Log
- Linux/MAC: In the log file found in the out folder: file pcoip-validate-license --verbose (Linux)
Licenses available from http://10.8.0.24:7070/request
Example (c): Licensing server id information (from FNE license dump)
- Windows: in log file: PCoIPSupport_Log
- Linux/MAC:in the log file found in the out folder: file: @@usr@local@bin@pcoip-license-tool_dump_-v.out
- If the file is not found or the value is empty or 0, then licensing has NOT been configured.
- The server id is XXXXXXX. This info hsould be put in the comment area.
BEGIN FNE debug dump
virtual machine type: 1
client version: 2020.12.0.274198.2020.11.26-11.53.54.6
licensing version: 2020.12.0.274198.2020.11.26-11.53.54.6
host type: <empty>
current host ID: type = 0, value = <empty>
floating server ID: type = 8, value = XXXXXXXXXXX
....
END FNE debug dump
Example (d-success): Licensing host id information is found
- Windows: in log file: PCoIPSupport_Log
- Linux/MAC:in the log file found in the out folder: file: pcoip-validate-license_--verbose
Set host ID to type = Z, value = YYYYYYYYYY
Example (d-failure): Licensing host id information is not found
- Windows: in log file: PCoIPSupport_Log
- Linux/MAC:in the log file found in the out folder: file: pcoip-validate-license_--verbose
Could not set either VM UUID or ethernet for host ID, using default behaviour
Example (e): Cloud Licensing Registration Failure due to machine being used in a different org
- Windows: in log file: pcoip_control_pannel
- Linux/MAC:in the log file found in the out folder: file: @@usr@local@bin@pcoip-license-tool_dump_-v.out
- If the file is not found or the value is empty or 0, then licensing has NOT been configured.
Running: C:\Windows\system32\WindowsPowerShell\v1.0\powershell.exe -InputFormat None -ExecutionPolicy AllSigned -NonInteractive -WindowStyle Hidden -Command "& { &'C:\Program Files\Teradici\PCoIP Agent\pcoip-register-host.ps1' -RegistrationCode %PCOIP_REG_CODE% ; Exit $LastExitCode; }"
Powershell command stderr: Failed to register with the cloud license server "https://teradici.compliance.flexnetoperations.com/instances/XXXXXXXXXXX/request". Host "NAME" may already be registered with "https://teradici.compliance.flexnetoperations.com/instances/ZZZZZZZZZZ/request" under a different registration. For resolution, contact Teradici support at support.teradici.com. Provide the name of your machine "NAME" and the support bundle.
Example (f): Cloud Licensing Registration Failure due to a host id machine changing
- Windows: in log file: PCoIPSupport_Log
- Linux/MAC:in the log file found in the out folder: file: @@usr@local@bin@pcoip-license-tool_dump_-v.out
BEGIN FNE debug dump virtual machine type: 1 client version: 2020.12.0.274198.2020.11.26-11.53.54.6 licensing version: 2020.12.0.274198.2020.11.26-11.53.54.6 host type: <empty> current host ID: type = 0, value = <empty> floating server ID: type = 8, value = YYYYYYYYYYY Available host IDs: 3 - XXXXXXXXXXXX 3 - F02F7493D935 11 - 192.168.10.110 5 - Administrator virtual machine info dictionary was not set floating features: Session 1.0 21-Jul-2036 23:59:59 EXPIRES=21-Jul-2036 23:59:59 AVAILABLE=uncounted HOSTID=ZZZZZZZZZZ VENDOR_STRING="****-****-****-****" ISSUER="Teradici Corporation" ISSUED=08-Oct-2021 00:00:00 NOTICE="COMPANY NAME" SN="xxxxx-xxx-xxx-xxxxx" START=21-Jul-2021 00:00:00 Not valid for acquisition: Trusted storage hostid does not match system hostid. trial features: Grace_Availability 1.0 05-Jan-2022 23:59:59 EXPIRES=permanent AVAILABLE=uncounted HOSTID=ANY START=08-Oct-2021 00:00:00 Valid for acquisition Customer ID = YYYYYYYYYYYY END FNE debug dump