A set-top box in a Data-over-Cable Service Interface Specifications (DOCSIS) cable plant is a special case of a cable modem (CM). The set-top box uses the same procedures to come online and receive network connectivity. However, a set-top box typically has extra levels of functionality that standard CMs do not, such as television services, pay-per-view, and an electronic program guide.
For this reason, a set-top box can require that the provisioning system supply it with extra pieces of information to help initialize or configure the extra functionality.
In this document, the example of a Motorola DCT5000 set-top box is described. When this device obtains a DHCP lease from the provisioning system, it also needs to be supplied with a URL which acts as a start page for the device. Otherwise, this particular brand of set-top box does not properly use all levels of functionality.
Note: Please do not use this document as a reference for provisioning a Motorola DCT5000 set-top box. Refer to the Motorola documentation as the canonical reference.
In this document, the DHCP server system used is Cisco Network Registrar (CNR) version 5.06. It is possible to use earlier CNR releases, but the process is different. You are required to enter the information in ASCII format, which can be a time consuming and complex procedure.
Note: It is recommended to use the process described in this document instead of manually defining the value for Option 43, as seen in earlier versions of CNR.
There are no specific requirements for this document.
The information in this document is based on the CNR version 5.06.
The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, make sure that you understand the potential impact of any command.
Refer to Cisco Technical Tips Conventions for more information on document conventions.
Vendor Class Identifier (Option 60) can be used by DHCP clients to identify the vendor and functionality of a DHCP client. The information is a variable length string of characters or octets which has a meaning specified by the vendor of the DHCP client.
One method that a DHCP client can communicate that it is using a certain type of hardware or firmware, is to set a value in its DHCP requests called the Vendor Class Identifier (VCI) (Option 60). For example, DOCSIS 1.0 based CMs must set the value of this DHCP option to the string docsis1.0, whereas DOCSIS 1.1 based CMs set this value to docsis1.1. This method has a DHCP server differentiate between the two kinds of CMs and process the requests from the two types of modems appropriately.
Some types of set-top boxes also set the VCI (Option 60) to inform the DHCP server about the hardware type and functionality of the device. The value that this option is set to gives the DHCP server a hint about any required extra information that this client needs in a DHCP response.
Code | Len | Vendor Class Identifier | ||
---|---|---|---|---|
60 | n | i1 | i2 | ............. |
Note: Option 60 is defined in RFC 2132 .
The most common option that set-top boxes expect additional vendor specific information, based on the sent VCI to be returned, is via a DHCP option called the Vendor Specific Information Option (Option 43). The format for this option is defined in RFC 2132 . However, the definition of the values returned by this option are specified by the vendor involved.
According to Section 8.4 of RFC 2132 , this option is typically formatted in a type, length, value (TLV) style where different pieces of information can be represented by different suboption types. The meaning of the value field is defined by the manufacturer of the end device.
Code | Len | Data Item | Code | Len | Data Item | ||||
---|---|---|---|---|---|---|---|---|---|
T1 | n | d1 | d2 | ......... | T2 | n | D1 | D2 | ........ |
When a Motorola DCT5000 set-top box sends a DHCP request, it sets the VCI (Option 60) to a value dct5000.008X. The X can be a hexadecimal digit from 0 to F depending on the capabilities of the set-top box. CNR uses this information to determine that a DHCP client is indeed a DCT5000 set-top box.
When CNR recognizes that a DHCP request is from a DCT5000, CNR needs to return a start URL in the DHCP response in order for a Motorola DCT5000 to correctly initialize. Motorola has decided that this start URL needs to be sent as a suboption type 2 in the Vendor Specific Information Option (Option 43).
Code | Len | Data Item |
---|---|---|
2 | 61 | http://172.16.1.10/dtv/app/servicemanager/servicemanager.html |
The first step that needs to take place within CNR is to tell CNR about the VCIs used by the set-top box. This is accomplished by issuing the nrcmd command in the CNR command line interface utility: vendor-option <vendor-option-name> create <Vendor-class-identifier> .
Note: This configuration can only be performed using the nrcmd command. It is not possible to use the GUI interface for these commands.
Where:
vendor-option-name — The identifier representing the type of client that sends the VCI.
Vendor-class-identifier — The value that Vendor Information Option (Option 60) is set to by a particular type of device.
Note: The vendor-option-name field in the command should be specified in all lower case. If upper case letters are used, they are converted to lower case. The Vendor-class-identifier field can have upper and lower case letters.
In the case for DCT5000 set-top boxes, these are the defined vendor options that reflect the different types of DCT5000s:
Vendor-option dct5000_80 create dct5000.0080 vendor-option dct5000_81 create dct5000.0081 vendor-option dct5000_82 create dct5000.0082 vendor-option dct5000_83 create dct5000.0083 vendor-option dct5000_84 create dct5000.0084 vendor-option dct5000_85 create dct5000.0085 vendor-option dct5000_86 create dct5000.0086 vendor-option dct5000_87 create dct5000.0087 vendor-option dct5000_88 create dct5000.0088 vendor-option dct5000_89 create dct5000.0089 vendor-option dct5000_8a create dct5000.008A vendor-option dct5000_8b create dct5000.008B vendor-option dct5000_8c create dct5000.008C vendor-option dct5000_8d create dct5000.008D vendor-option dct5000_8e create dct5000.008E vendor-option dct5000_8f create dct5000.008F
If other types of set-top boxes are deployed in your network in the future, and if these set-top boxes use different VCIs, then these can be defined later.
At present, there is no solution in CNR to amalgamate these different VCIs into one entry. CNR treats them as completely separate entities.
The next step is to define suboption type 2 as being a valid type for each of these VCIs.
Suboption types are created by using the nrcmd command, vendor-option <vendor-option-name> definesuboption <suboption-name> <suboption-type-number> <option-data-type> .
Where:
vendor-option-name — The identifier chosen to represent the client type.
suboption-name —The name of the suboption being created. This should be representative of the function of the suboption.
suboption-type-number —The suboption type number for this suboption.
option-data-type —The data type that this suboption uses. For example, IPADDR, STRING, BYTE_ARRAY. Other types can be seen using the nrcmd command, option-datatype list.
Note: The vendor-option-name and suboption-name field in this command should be specified in all lower case. If upper case letters are used, then they are converted to lower case. The option-data-type field can have upper and lower case letters.
For this example, you need to define suboption type number 2 for the start URL. Since the URL is a text string, issue the type STRING command as the option-data-type.
Vendor-option dct5000_80 definesuboption start_url 2 STRING vendor-option dct5000_81 definesuboption start_url 2 STRING vendor-option dct5000_82 definesuboption start_url 2 STRING vendor-option dct5000_83 definesuboption start_url 2 STRING vendor-option dct5000_84 definesuboption start_url 2 STRING vendor-option dct5000_85 definesuboption start_url 2 STRING vendor-option dct5000_86 definesuboption start_url 2 STRING vendor-option dct5000_87 definesuboption start_url 2 STRING vendor-option dct5000_88 definesuboption start_url 2 STRING vendor-option dct5000_89 definesuboption start_url 2 STRING vendor-option dct5000_8a definesuboption start_url 2 STRING vendor-option dct5000_8b definesuboption start_url 2 STRING vendor-option dct5000_8c definesuboption start_url 2 STRING vendor-option dct5000_8d definesuboption start_url 2 STRING vendor-option dct5000_8e definesuboption start_url 2 STRING vendor-option dct5000_8f definesuboption start_url 2 STRING
If extra functionality is defined on the set-top box in the future, and other suboptions need to be defined, then these can be specified in a similar manner at a later stage.
The final step in the process is to associate the defined vendor option with a policy, and to specify the values that individual suboptions should take. This is performed with the nrcmd command, policy <policy-name> setvendoroption <vendor-option-name> <suboption-name> <suboption-value> .
Where:
policy-name — The name of the DHCP policy from which set-top boxes receive options. This has been configured previously.
vendor-option-name — The identifier chosen to represent the client type.
suboption-name — The name of the suboption.
suboption-value — The value given to the suboption in DHCP responses. This should be entered as per the option-data-type specified when defining the suboption.
Note: The vendor-option-name and suboption-name fields are case sensitive. It is important to make sure that these fields are specified in all lower case. The suboption-value field can be specified in upper or lower case. The suboption-value field is only case sensitive if the client receiving the suboption needs it to be case sensitive.
For this example, assume that a policy for set-top Boxes has been created and is called STB_policy. Also, specify a start URL for each of these types of Set Top Boxes as http://172.16.1.10/dtv/app/servicemanager/servicemanager.htmlhttp://www.lookuptables.com/.
This is performed with these nrcmd commands:
policy STB_policy setvendoroption dct5000_80 start_url http://172.16.1.10/dtv/app/ servicemanager/servicemanager.html policy STB_policy setvendoroption dct5000_81 start_url http://172.16.1.10/dtv/app/ servicemanager/servicemanager.html policy STB_policy setvendoroption dct5000_82 start_url http://172.16.1.10/dtv/app/ servicemanager/servicemanager.html policy STB_policy setvendoroption dct5000_83 start_url http://172.16.1.10/dtv/app/ servicemanager/servicemanager.html policy STB_policy setvendoroption dct5000_84 start_url http://172.16.1.10/dtv/app/ servicemanager/servicemanager.html policy STB_policy setvendoroption dct5000_85 start_url http://172.16.1.10/dtv/app/ servicemanager/servicemanager.html policy STB_policy setvendoroption dct5000_86 start_url http://172.16.1.10/dtv/app/ servicemanager/servicemanager.html policy STB_policy setvendoroption dct5000_87 start_url http://172.16.1.10/dtv/app/ servicemanager/servicemanager.html policy STB_policy setvendoroption dct5000_88 start_url http://172.16.1.10/dtv/app/ servicemanager/servicemanager.html policy STB_policy setvendoroption dct5000_89 start_url http://172.16.1.10/dtv/app/ servicemanager/servicemanager.html policy STB_policy setvendoroption dct5000_8a start_url http://172.16.1.10/dtv/app/ servicemanager/servicemanager.html policy STB_policy setvendoroption dct5000_8b start_url http://172.16.1.10/dtv/app/ servicemanager/servicemanager.html policy STB_policy setvendoroption dct5000_8c start_url http://172.16.1.10/dtv/app/ servicemanager/servicemanager.html policy STB_policy setvendoroption dct5000_8d start_url http://172.16.1.10/dtv/app/ servicemanager/servicemanager.html policy STB_policy setvendoroption dct5000_8e start_url http://172.16.1.10/dtv/app/ servicemanager/servicemanager.html policy STB_policy setvendoroption dct5000_8f start_url http://172.16.1.10/dtv/app/ servicemanager/servicemanager.html
If other suboption types of VCIs are specified, they can be associated with policies and assigned values in a similar manner.
At this stage, the configuration changes are saved and the DHCP server can be reloaded in order to apply the changes. This can be accomplished issuing nrcmd with these commands: dhcp save and reload.
In earlier versions of CNR, the advance vendor specific information option functionality was not available. Instead, the Vendor Specific Option (Option 43) had to be manually configured in a policy. This can not be done in CNR 5.0. If a value in Option 43 needs to be received, you must issue the vendor-option and policy setvendoroption suite of commands.
In CNR versions prior to 5.0, in order to configure a policy to supply a value for the Vendor Specific Information Option (Option 43), you issue the command policy <policy-name> setoption vendor-encapsulated-option <value-byte-array> .
Where:
policy-name — The name of the DHCP policy from which Set Top Boxes receive options. This has been configured previously.
value-byte-array — The value taken by the whole of the returned Vendor Specific Information Option (Option 43) specified as an array of hexadecimal bytes.
Since the value contained in the Vendor Specific Information Option (Option 43) is listed as an array of hexadecimal bytes, and since no subtype definitions are put in place, the whole of the required field must be decoded into appropriate ASCII codes.
Using a text to ASCII hex conversion table, such as the one at http://www.lookuptables.com/ , you can convert the URL, http://172.16.1.10/dtv/app/servicemanager/servicemanager.html, to equivalent hexadecimal values.
This URL becomes this value:
68:74:74:70:3a:2f:2f:31:37:32:2e:31:36:2e:31:2e:31:30:2f:64: 74:76:2f:61:70:70:2f:73:65:72:76:69:63:65:6d:61:6e:61:67:65: 72:2f:73:65:72:76:69:63:65:6d:61:6e:61:67:65:72:2e:68:74:6d:6c
In order to properly format the Vendor Specific Information Option (Option 43), you need to add the type and length fields at the beginning of this array.
Code | Len | Data Item |
---|---|---|
2 | 61 | http://172.16.1.10/dtv/app/servicemanager/servicemanager.html |
Code | Len | Data Item |
---|---|---|
02 | 3d | 68:74:74:70:3a:2f:2f:31:37:32:2e:31:36:2e:31:2e:31:30:2f:64:74: 76:2f:61:70:70:2f:73:65:72:76:69:63:65:6d:61:6e:61:67:65:72:2f: 73:65:72:76:69:63:65:6d:61:6e:61:67:65:72:2e:68:74:6d:6c |
As seen in this table, the hexadecimal bytes 61:3d need to be prepended to the hexadecimal string representing the start URL. You can specify the entire value for the Vendor Specific Information Option (Option 43) by issuing this nrcmd command:
policy STB_policy setoption vendor-encapsulated-option
02:3d:68:74:74:70:3a:2f:2f:31:37:32:2e:31:36:2e:31:2e:31:30:2f:64:74:76:2f:61:70:70:2f:73:65:72:76:69:63:65:6d:61:
6e:61:67:65:72:2f:73:65:72: 76:69:63:65:6d:61:6e:61:67:65:72:2e:68:74:6d:6c
Note: This entire command is performed on one line.
To verify that the configuration commands were entered properly, you can issue nrcmd commands.
The first command is vendor-option list. As seen in this output, the output of this command provides a list of the vendor options, giving the vendor-option-name, the vendor-class-id, and the vendor-option feature read_only.
nrcmd> vendor-option list 100 Ok dct5000_80: name = dct5000_80 read-only = disabled vendor-class-id = dct5000.0080 dct5000_81: name = dct5000_81 read-only = disabled vendor-class-id = dct5000.0081 dct5000_82: name = dct5000_82 read-only = disabled vendor-class-id = dct5000.0082 dct5000_83: name = dct5000_83 read-only = disabled vendor-class-id = dct5000.0083 dct5000_84: name = dct5000_84 read-only = disabled vendor-class-id = dct5000.0084 dct5000_85: name = dct5000_85 read-only = disabled vendor-class-id = dct5000.0085 dct5000_86: name = dct5000_86 read-only = disabled vendor-class-id = dct5000.0086 dct5000_87: name = dct5000_87 read-only = disabled vendor-class-id = dct5000.0087 dct5000_88: name = dct5000_88 read-only = disabled vendor-class-id = dct5000.0088 dct5000_89: name = dct5000_89 read-only = disabled vendor-class-id = dct5000.0089 dct5000_8a: name = dct5000_8a read-only = disabled vendor-class-id = dct5000.008A dct5000_8b: name = dct5000_8b read-only = disabled vendor-class-id = dct5000.008B dct5000_8c: name = dct5000_8c read-only = disabled vendor-class-id = dct5000.008C dct5000_8d: name = dct5000_8d read-only = disabled vendor-class-id = dct5000.008D dct5000_8e: name = dct5000_8e read-only = disabled vendor-class-id = dct5000.008E dct5000_8f: name = dct5000_8f read-only = disabled vendor-class-id = dct5000.008F
Note: The vendor-option read-only feature is disabled by default. If you want to enable this, issue the vendor-option name enable read-only command. The read-only feature of the vendor-specific DHCP option should be enabled before you use the option in a policy name setVendoroption command to set the data for the option.
To verify the list of suboptions given to each vendor option, issue the command vendor-option vendor-option-name listsuboptiovns. With this command, you can see the suboption type and value. In this output, it is string type and the value is start_url.
nrcmd> vendor-option dct5000_80 listsuboptiovns 100 OK start_url(2) : string nrcmd> vendor-option dct5000_81 listsuboptions 100 OK start_url(2) : string
In order to verify that the correct values for the Vendor Specific Information Option (Option 43) are being returned to end clients, it is possible to activate extended debugging in CNR to view the contents of DHCP options in DHCP responses to clients. Refer to Troubleshooting DHCP Problems in Cable Networks using Cisco Network Registrar Debugs for more information on turning on extended debugging in CNR.