Linux DHCP server configuration when using DHCP Discovery on PCoIP Management Console 2.x and 3.x

Answer:

This is based on PCoIP Management Console 2.x and newer only

This is an example of configuring a Linux DHCP server when using DHCP Option for device discovery. The DHCP server is configured by editing the configuration file:

 /etc/dhcpd.conf 

This is what it looks like:

The part that needs to be edited is the class section near the bottom of the example above. The first line in the definition ("match if substring..") does not need to be changed. This line checks if the first 15 characters (numbered 0 to 14) of the client's "vendor-class-identifier" match the characters in "PCoIP Endpoint". 

The second line contains the sub-codes in a hard-to-read hex format. This line describes the "option vendor-encapsulated-options" defining option 43 and is written in the dhcpd.conf file in the following format.

 "option vendor-encapsulated-options " 

This hex string is a series of bytes separated by colons. The format is a tag-length-value (TLV) format where the sub-code is used as a tag and the length is one byte. To convert from ASCII to HEX or vice versa, use a conversion tool of your choosing. This example used the rapid tables online conversion tool.

Using the above example take the HEX number:

0A:18:77:73:73:3a:2f:2f:31:30:2e:31:31:37:2e:39:2e:31:30:33:3a:35:31:37:32:00:00:0B:60:42:37:3a:36:32:3a:37:31:3a:30:31:3a:38:35:3a:32:37:3a:34:36:3a:42:42:3a:45:33:3a:45:39:3a:35:43:3a:45:32:3a:33:34:3a:32:43:3a:42:35:3a:37:36:3a:37:44:3a:37:41:3a:46:31:3a:37:46:3a:36:41:3a:34:44:3a:35:43:3a:44:42:3a:41:41:3a:32:42:3a:39:39:3a:42:44:3a:44:35:3a:41:39:3a:32:38:3a:39:31:00;

This hex number contains 2 Tags. The fist tag is the EBM URI of wss://10.0.153.242:5172 and the second Tag is the EBM x.509 Certificate SHA-256 fingerprint of B7:62:71:01:85:27:46:BB:E3:E9:5C:E2:34:2C:B5:76:7D:7A:F1:7F:6A:4D:5C:DB:AA:2B:99:BD:D5:A9:28:91

What does this string say?

• When converting the HEX number, remove the colons.
• For the first Tag (EBM URI) it is defined as:
  • The first HEX byte (blue highlight) in the example above (0A) identifies the first "Tag" which is the sub-code 10.
  • The second HEX byte (gray highlight) in the example above (18) represents the first Tags total number of defined Value bytes (“Length”) in Hex. This is represented as 0x18 (hexadecimal) or 24 bytes (decimal). The number of bytes in decimal must be converted to HEX.
  • The third group of HEX bytes, from 3 to 26 (green highlight)  in the example above 77:73:73:3a:2f:2f:31:30:2e:30:2e:31:35:33:2e:32:34:32:3a:35:31:37:32:00 represents the Value(data) for the first Tag (which is the EBM URI of wss://10.0.153.242:5172 when converted from ASCII to HEX). To convert from ASCII to HEX or vice versa, use a conversion tool of your choosing. This example used the rapid tables online conversion tool.
    The end of the Value portion of the TAG is denoted by two zeroes (orange highlight)
• The second Tag (EBM x.509 certificate fingerprint)  are similarly defined as:
  • The first HEX byte (blue highlight) in the example above (0B) identifies the second "Tag" which is the sub-code 11.
  • The second HEX byte (gray highlight) in the example above (60) represents the second Tags total number of defined Value bytes (“Length”) in Hex. This is represented as 0x60 (hexadecimal) or 96 bytes (decimal). The number of bytes in decimal must be converted to HEX.
  • The third group of HEX bytes, from 30 to 125 (green highlight)  in the example above 42:37:3a:36:32:3a:37:31:3a:30:31:3a:38:35:3a:32:37:3a:34:36:3a:42:42:3a:45:33:3a:45:39:3a:35:43:3a:45:32:3a:33:34:3a:32:43:3a:42:35:3a:37:36:3a:37:44:3a:37:41:3a:46:31:3a:37:46:3a:36:41:3a:34:44:3a:35:43:3a:44:42:3a:41:41:3a:32:42:3a:39:39:3a:42:44:3a:44:35:3a:41:39:3a:32:38:3a:39:31:00 represents the Value(data) for the second Tag (which is the EBM x.509 of B7:62:71:01:85:27:46:BB:E3:E9:5C:E2:34:2C:B5:76:7D:7A:F1:7F:6A:4D:5C:DB:AA:2B:99:BD:D5:A9:28:91 when converted from ASCII to HEX). To convert from ASCII to HEX or vice versa, use a conversion tool of your choosing. This example used the rapid tables online conversion tool.
    The end of the Value portion of the TAG is denoted by two zeroes (orange highlight)
• The end of strings is denoted by two zeroes.

Defined and configurable values from the HEX number above.

Note: The Length is the total number of bytes in the value and the 00 byte that denotes the end of the value. In the first Tag, there is 23 bytes in 77:73:73:3a:2f:2f:31:30:2e:30:2e:31:35:33:2e:32:34:32:3a:35:31:37:32 + 1 byte for the 00.

You can use a converter of your choice to create the values that you need, and then modify the dhcpd.conf file accordingly.

• Remember to include the colons between bytes, and the semicolon at the end of the line.
• Also remember the length of the string must include the null byte (00).
  • After editing the file, you must restart the DHCP server as follows.
    [root@teradici ~]# /etc/init.d/dhcpd restart

The DHCP server is now configured to provide option 43 to PCoIP endpoints.

Troubleshooting

The PCoIP Zero Client has a build in packet capture (LINK TO KB 1325). Follow all steps including setting the path environment variables otherwise conversion will fail.
To capture the DHCP process:

1. Log into the PCoIP Zero Client AWI
2. Navigate to Diagnostics -> Packet Capture
3. Start the Packet Capture
4. Remove the network cable from the back of the PCoIP Zero Client.
5. Reconnect the network cable to the PCoIP Zero Client
6. Wait until the PCoIP Zero Client gets an IP address
7. Refresh the AWI.
8. Download the packet capture.
9. Convert the packet capture with (How to use the packet capture utility in PCoIP Zero Client Firmware).
10. Open the Packet capture in Wireshark.
11. Filter for bootp
12. Find a DHCP Discover packet. Double Click to open in a new windows.
13. Find Option 43 – Vendor Specific information and expand.
14. Select Value.

When the DHCP server is configured correctly you will see the below. We should state what tool and version of it you are using in the event the format changes in future. The left side showing hexadecimal and the right side showing the ASCII equivalent. You should be able to clearly the EBI URI and the EBM x.509 certificate fingerprint values in the ASCII. You can highlight the ASCII in your packet capture to check the hexadecimal on the left hand side and vice versa. You should be able to clearly see the Tag-Length-Value portions of the hexadecimal string.

See Also: Linux DHCP server configuration when using DHCP Discovery on PCoIP Management Console 2.x and 3.x