Cisco IOS® Software configuration files are text files which contain the configuration to be sent to routers. In the case of Cisco cable modems, the configuration that is sent typically contains access lists, hostnames, SNMP community strings, passwords, or routing configuration that differs from the default bridging configuration. To send a Cisco IOS configuration file it is necessary to embed the file in the Data-over-Cable Service Interface Specifications (DOCSIS) configuration file that the cable modems use in the TFTP portion of their initialization process.
There are two ways to download a Cisco IOS configuration file to Cisco cable modems.
The first one, which is the most common way, is to use a DOCSIS CPE Configurator tool. Please see the Cisco DOCSIS CPE Configurator (registered customers only) . The document Building DOCSIS 1.0 Configuration Files Using Cisco DOCSIS Configurator (registered customers only) contains a detailed explanation on how to do this.
The second way in which the same task can be accomplished is by using the Command Line Interface (CLI) in Cisco IOS of the Cable Modem Termination System (CMTS).
This document explains in detail the second way to download an IOS configuration file to Cisco Cable Modems without the need of using a DOCSIS Configurator tool. For this we use an enhanced version of the all-in-one configuration which allows the Cisco CMTS to be configured as DHCP, ToD, and TFTP servers, as well as to configure a DOCSIS configuration file on the CMTS itself.
When we want to send a configuration file to cable modems using the CLI to configure the DOCSIS configuration file, we need to add a DHCP option called DHCP Vendor Specific Information Option, also known as option 43.
The main advantage of configuring cable modems this way is that everything can be done from the Cisco's CMTS, and no other servers (like DHCP, TFTP, or ToD) and software (like DOCSIS CPE Configurator Tool) are required to successfully send a Cisco IOS configurations to Cisco cable modems and get them operational with a customized configuration.
For more information on document conventions, see the Cisco Technical Tips Conventions.
The reader should have a basic understanding of:
The DOCSIS protocol
Cisco IOS command-line interface (CLI) on the uBR series routers
UNIX
Dynamic Host Configuration Protocol (DHCP)
Please see the section Configuring all in one config including DHCP Option 43 below.
Option 43 is a DHCP option used by clients and servers to exchange Vendor Specific Information.
This option is typically formatted in a "Type-Length-Value" style where different pieces of information may be represented by different sub-option types. The meaning of the "Value" field is defined by the end device's manufacturer. Figure 1 gives a graphical representation of Option 43.
Type | Length | Value | Type | Length | Value | ||||
T1 | n | d1 | d2 | ......... | T2 | n | D1 | D2 | ........ |
Figure 1 - The Type-Length-Value structure of the data sent within Option 43.
To download Cisco IOS configuration files to Cisco Cable Modems, we use two sub-options, namely Vendor ID and Vendor Specific Information Option (VSIF).
The Vendor ID sub-option has type 8. The three-byte Organization Unique Identifier (OUI) for the vendor is usually the first three bytes of the cable modem's MAC address. This value is usually expressed as a hexadecimal number. This field should be 00:00:0C (in Hex) for Cisco Systems equipment. Figure 2 below gives the hexadecimal numbers for Vendor ID sub-option.
Type | Length | Value |
08 | 03 | 00:00:0C |
Figure 2 - Sub-Option Vendor ID (In Hexadecimal value)
The second Sub-Option used is the Vendor Specific Information Field (VSIF). This sub-option has type 128 and it contains any arbitrary values that are defined by the manufacturer of the cable modem. The Cisco cable modem uses this field to identify the Cisco IOS configuration file name that should be downloaded (if any) to a router.
Arbitrary Cisco IOS commands can also be specified in this field. This field is usually represented in dotted-decimal. Dotted-decimal notation is the decimal representation of the letters according to ASCII in which each letter has a decimal value. "Dots" are used between the decimal representation to make it easier to understand.
In this document we will show how to download a Cisco IOS configuration file called ios.cf. The name of this file gets converted from ASCII to dotted-decimal.
To know what is the translation between ASCII and dotted-decimal, the UNIX command man ascii can be used as shown below. This command gives several conversion tables. We need to look for the Decimal - Character table.
sj-cse-494% man ascii Reformatting page. Wait... done ASCII(5) Headers, Tables, and Macros ASCII(5) NAME ASCII - map of ASCII character set .... (skip the beginning) Decimal - Character | 0 NUL| 1 SOH| 2 STX| 3 ETX| 4 EOT| 5 ENQ| 6 ACK| 7 BEL| | 8 BS | 9 HT | 10 NL | 11 VT | 12 NP | 13 CR | 14 SO | 15 SI | | 16 DLE| 17 DC1| 18 DC2| 19 DC3| 20 DC4| 21 NAK| 22 SYN| 23 ETB| | 24 CAN| 25 EM | 26 SUB| 27 ESC| 28 FS | 29 GS | 30 RS | 31 US | | 32 SP | 33 ! | 34 " | 35 # | 36 $ | 37 % | 38 & | 39 ' | | 40 ( | 41 ) | 42 * | 43 + | 44 , | 45 - | 46 . | 47 / | | 48 0 | 49 1 | 50 2 | 51 3 | 52 4 | 53 5 | 54 6 | 55 7 | | 56 8 | 57 9 | 58 : | 59 ; | 60 < | 61 = | 62 > | 63 ? | | 64 @ | 65 A | 66 B | 67 C | 68 D | 69 E | 70 F | 71 G | | 72 H | 73 I | 74 J | 75 K | 76 L | 77 M | 78 N | 79 O | | 80 P | 81 Q | 82 R | 83 S | 84 T | 85 U | 86 V | 87 W | | 88 X | 89 Y | 90 Z | 91 [ | 92 \ | 93 ] | 94 ^ | 95 _ | | 96 ` | 97 a | 98 b | 99 c |100 d |101 e |102 f |103 g | |104 h |105 i |106 j |107 k |108 l |109 m |110 n |111 o | |112 p |113 q |114 r |115 s |116 t |117 u |118 v |119 w | |120 x |121 y |122 z |123 { |124 | |125 } |126 ~ |127 DEL|
Therefore, the dotted-decimal representation of ios.cf is 105.111.115.46.99.102 as shown below in Figure 3.
i | o | s | . | c | f |
105 | 111 | 115 | 46 | 99 | 192 |
Figure 3 - Dotted-decimal representation of the filename ios.cf.
Since the VSIF is a Type- Length-Value format, the complete dotted-decimal representation of the Cisco IOS configuration file named ios.cf is 128.6.105.111.115.46.99.192. As you can see, 128.6 has been added to the dotted-decimal representation of ios.cf shown in Figure 3. Remember that "128" is the type and "6" is the length.
128.6.105.111.115.46.99.192 is the value entered in the VSIF field of the Vendor Info Tab of the DOCSIS CPE Configurator Tool V3.2 as shown in the Figure 4 below.
Figure 4 - Vendor Info field from DOCSIS CPE Configurator Tool.
However, when doing this function in Cisco IOS using the DHCP Option 43, the Type-Length-Value (TLV) information should be expressed in Hexadecimal values. This document focuses on this hexadecimal expression.
To find out the hexadecimal representation of the ASCII characters, we can use the Unix command:
echo -n "ios.cf" | od -t x1 | cut -s -d' ' -f2- | tr ' ' ':' sj-cse-494% echo -n "ios.cf" | OD -t x1 | cut -s -d' ' -f2- | tr ' ' ':' 69:6f:73:2e:63:66
Or, you can also used the previous UNIX command man ASCII and find the "Hexadecimal - Character" table.
sj-cse-494% man ASCII Reformatting page. Wait... done ASCII(5) Headers, Tables, and Macros ASCII(5) NAME ASCII - map of ASCII character set .... (skip the beginning) Hexadecimal - Character | 00 NUL| 01 SOH| 02 STX| 03 ETX| 04 EOT| 05 ENQ| 06 ACK| 07 BEL| | 08 BS | 09 HT | 0A NL | 0B VT | 0C NP | 0D CR | 0E SO | 0F SI | | 10 DLE| 11 DC1| 12 DC2| 13 DC3| 14 DC4| 15 NAK| 16 SYN| 17 ETB| | 18 CAN| 19 EM | 1A SUB| 1B ESC| 1C FS | 1D GS | 1E RS | 1F US | | 20 SP | 21 ! | 22 " | 23 # | 24 $ | 25 % | 26 & | 27 ' | | 28 ( | 29 ) | 2A * | 2B + | 2C , | 2D - | 2E . | 2F / | | 30 0 | 31 1 | 32 2 | 33 3 | 34 4 | 35 5 | 36 6 | 37 7 | | 38 8 | 39 9 | 3A : | 3B ; | 3C < | 3D = | 3E > | 3F ? | | 40 @ | 41 A | 42 B | 43 C | 44 D | 45 E | 46 F | 47 G | | 48 H | 49 I | 4A J | 4B K | 4C L | 4D M | 4E N | 4F O | | 50 P | 51 Q | 52 R | 53 S | 54 T | 55 U | 56 V | 57 W | | 58 X | 59 Y | 5A Z | 5B [ | 5C \ | 5D ] | 5E ^ | 5F _ | | 60 ` | 61 a | 62 b | 63 c | 64 d | 65 e | 66 f | 67 g | | 68 h | 69 i | 6A j | 6B k | 6C l | 6D m | 6E n | 6F o | | 70 p | 71 q | 72 r | 73 s | 74 t | 75 u | 76 v | 77 w | | 78 x | 79 y | 7A z | 7B { | 7C | | 7D } | 7E ~ | 7F DEL|
Figure 5 below summarizes the dotted-decimal as well as hexadecimal representation of the Vendor Specific Information Field (VSIF).
Type | Length | Value | |
Dotted-decimal | 128 | 6 | 105.111.115.46.99.102 |
Hexadecimal | 80 | 06 | 69:6F:73:2E:63:66 |
Figure 5 - Sub-Option VSIF in dotted-decimal and hexadecimal.
This configuration was developed and tested using the software and hardware versions below.
Cisco uBR10012 running 12.2(2)XF
Cisco CVA120 running 12.2(2)XA
The information presented in this document was created from devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If you are working in a live network, ensure that you understand the potential impact of any Cisco IOS command before using it.
The first step in configuring Option 43 is to know the necessary hexadecimal value of the Vendor ID and the necessary hexadecimal value of the VSIF sub-options of DHCP Option 43.
The table below summarizes these values that were discussed in detail in the Vendor Specific Information section.
Vendor ID sub-option | VSIF sub-option | |||||
TLV | Type | Length | Value | Type | Length | Value |
Hexadecimal | 08 | 03 | 00:00:0C | 80 | 06 | 69:6F:73:2E:63:66 |
Meaning | Vendor ID Type | Vendor ID Length | Cisco's ID | VSIF Type | VSIF Length | (filename) ios.cf |
Figure 6
Once we know which value we will enter, we need to use the CLI of the Cisco's CMTS to generate all the properties needed for the DOCSIS Configuration file, including the DHCP option 43.
To create the DOCSIS Configuration file we need to enter the global command cable config-file DOCSIS-file-name . The following output shows the creation of the DOCSIS Configuration file named platinum.cm. All the settings of platinum.cm are explained below.
Note: !--- Comments are in blue. cable config-file platinum.cm !--- Name of the DOCSIS config file is platinum.cm service-class 1 priority 2 !--- The Upstream Channel priority is 2 service-class 1 max-upstream 128 !--- The Maximum upstream value is 128Kbps service-class 1 guaranteed-upstream 10 !--- The Guaranteed Upstream is 10 Kbps service-class 1 max-downstream 10000 !--- The Maximum Downstream is 10Mbps service-class 1 max-burst 1600 !--- The Maximum Upstream Transmit burst is 1600 bytes cpe max 10 !--- The Maximum number of CPE's is 10 timestamp !--- Enable timestamp generation option 43 hex 08:03:00:00:0C:80:06:69:6F:73:2E:63:66 !--- Using option 43 to send the IOS Configuration file named "ios.cf" !--- to cable modems.
Caution: The cable config-file command was introduced in Cisco IOS version 12.1(2)EC1 for uBR7200 and uBR7100, and on Cisco IOS version 12.2(1)XF1 for the uBR10K.
Note: Be certain that you have correctly entered the TLV data when using the hex option. Incorrectly entered data could cause CMs to reset, go offline, or hang, requiring a power cycle before being able to continue.
Once we have created the DOCSIS configuration file platinum.cm, we need to configure the CMTS to be the DHCP server, and configure the options needed for the DHCP functionality. Please see The Cisco IOS Dynamic Host Configuration Protocol (DHCP) service on a CMTS, which explains the meaning of each of the command that we are using for the creation of the dhcp pool. Here we will just summarize the configuration and give a brief description.
The configuration of the DHCP pool is:
ip dhcp pool surf !--- name of the dhcp pool. This scope is for the cable modems attached !--- to interface cable 5/0/0 network 10.1.4.0 255.255.255.0 !--- pool of addresses for scope from interface c5/0/0 bootfile platinum.cm !--- DOCSIS config file name associated with this pool next-server 10.1.4.1 !--- IP address of TFTP server which sends bootfile default-router 10.1.4.1 !--- default gateway for cable modems, necessary to get DOCSIS files option 7 ip 10.1.4.1 !--- Log Server DHCP option option 4 ip 10.1.4.1 !--- ToD server IP address option 2 hex ffff.8f80 !--- Time offset for ToD, in seconds, HEX, from GMT, -28,000 = PST = ffff.8f80 lease 7 0 10 !--- lease 7 days 0 hours 10 minutes !
The third step is to configure the CMTS to be a TFTP server. To do this you will need to:
Use the command tftp-server
Tell the TFTP server where the file ios.cf is located
You can achieve this with the command tftp-server disk0:ios.cf alias ios.cf . Notice that this command puts the file ios.cf in disk0.
tftp-server server !--- enable the cmts to act as a tftp server tftp-server disk0:ios.cf alias ios.cf !--- get the IOS config file called ios.cf that is pre-downloaded to disk0 !--- this IOS config file was built with a text editor and tftp to disk0
To put the ios.cf file in your flash or disk0 (for uBR10012) you have to tftp the file that has been created using a text file editor. To do this first make sure you can ping the tftp server where the Cisco IOS configuration is located.
Next, the global command copy tftp <device> should be entered to place the file inside the CMTS. Usually the flash is used for uBR7200 or uBR7100 or uBR10K, however, this example shows how to use disk0 for uBR10012.
schooner#copy tftp disk0 Address or name of remote host []? 172.16.30.2 Source filename []? ios.cf Destination filename [ios.cf]? Accessing tftp://172.16.30.2/ios.cf... Loading ios.cf from 172.16.30.2 (via FastEthernet0/0/0): ! [OK - 173/4096 bytes] 173 bytes copied in 0.152 secs
To make sure that the IOS configuration file is stored on the CMTS run the command dir.
schooner#dir Directory of disk0:/ 3 -rw- 11606084 Sep 17 2001 13:31:38 ubr10k-k8p6-mz.122-2.XF.bin 2839 -rw- 173 Oct 01 2001 23:29:44 ios.cf 47890432 bytes total (36274176 bytes free)
To view what commands are configured in the ios.cf file the command more <filename> can be used in the CMTS as follows:
schooner#more ios.cf hostname SUCCEED service linenumber enable password cisco interface ethernet 0 load 30 no shut interface cable 0 load 30 no shut line vty 0 4 password cisco end
To configure ToD on a Cisco's CMTS only two global commands are needed service udp-small-servers max-servers no-limit and cable time-server. The configuration looks like:
service udp-small-servers max-servers no-limit !--- supports a large number of modems / hosts attaching quickly cable timeserver !--- permits cable modems to obtain Time of Day (ToD) from uBR10012
The complete configuration of the uBR10012 is found below. All the commands in bold are the relevant commands to the purpose of this document.
Schooner#show run Building configuration... Current configuration : 3522 bytes ! version 12.2 no parser cache no service single-slot-reload-enable no service pad service timestamps debug uptime service timestamps log uptime no service password-encryption service udp-small-servers max-servers no-limit ! hostname schooner ! logging rate-limit console all 10 except critical enable secret 5 $1$cM7F$ryXH7z/Ly6QCnD2LQ.gZs/ ! no cable qos permission create no cable qos permission update cable qos permission modems cable timeserver ! cable config-file platinum.cm service-class 1 priority 2 service-class 1 max-upstream 128 service-class 1 guaranteed-upstream 10 service-class 1 max-downstream 10000 service-class 1 max-burst 1600 cpe max 10 timestamp option 43 hex 08:03:00:00:0C:80:06:69:6F:73:2E:63:66 ! redundancy main-cpu auto-sync standard facility-alarm intake-temperature major 49 facility-alarm intake-temperature minor 40 facility-alarm core-temperature major 53 facility-alarm core-temperature minor 45 card 1/0 1oc12pos-1 card 1/1 2cable-tccplus card 2/0 1gigethernet-1 card 5/0 2cable-mc28 card 7/0 2cable-mc28 ip subnet-zero no ip domain-lookup ! ip dhcp pool surf network 10.1.4.0 255.255.255.0 bootfile platinum.cm next-server 10.1.4.1 default-router 10.1.4.1 option 7 ip 10.1.4.1 option 4 ip 10.1.4.1 option 2 hex ffff.8f80 lease 7 0 10 ! interface FastEthernet0/0/0 ip address 172.16.30.50 255.255.255.192 ! interface POS1/0/0 no ip address crc 32 pos report all POs flag j0 1 ! interface GigabitEthernet2/0/0 no ip address negotiation auto ! interface Cable5/0/0 ip address 10.1.4.1 255.255.255.0 cable downstream annex B cable downstream modulation 64qam cable downstream interleave-depth 32 cable upstream 0 frequency 40000000 cable upstream 0 power-level 0 no cable upstream 0 shutdown cable upstream 1 shutdown cable upstream 2 shutdown cable upstream 3 shutdown ! ip classless ip route 0.0.0.0 0.0.0.0 172.16.30.1 no ip http server ! no cdp run snmp-server community public RO snmp-server community private RW snmp-server trap-source Cable5/0/0 snmp-server packetsize 2048 snmp-server enable traps cable snmp-server host 172.16.30.8 public cable snmp snmp-server manager tftp-server server tftp-server ios.cf alias ios.cf ! alias exec scm show cable modem ! line con 0 line aux 0 line vty 0 4 ! end schooner#
Other CMTS vendors may not have the ability to set up all these pieces using only their CMTS commands whereas it can be accomplished completely in Cisco IOS.
To make the cable modems take the commands specified in the Cisco IOS configuration file called ios.cf, it is necessary to reboot the cable modems in question. This can be done from the from the CMTS's CLI by using the command clear cable modem <ip address/MAC address> reset.
Schooner#clear cable modem 10.1.4.4 reset
Caution: If you have a large network and want to send a different configuration file to all the cable modems in your plant, it is recommended to do so in phases. This will minimize the impact of thousands of cable modems attempting to step on each other while trying to get online at the same time.
To verify the configuration, clear the cable modem with the clear cable modem command. When the cable modem comes back online, telnet to it look at the configuration.
Schooner#show cable modem MAC Address IP Address I/F MAC Prim RxPwr Timing Num BPI State Sid (db) Offset CPEs Enbld 0004.27ca.0e9b 10.1.4.6 C5/0/0/U0 online 1 *0.00 2820 0 no 0090.9600.703d 10.1.4.2 C5/0/0/U0 online 2 -0.75 2816 0 no 0003.e38f.f9b5 10.1.4.3 C5/0/0/U0 online 3 *0.00 2822 0 no 0001.64ff.e4b5 10.1.4.4 C5/0/0/U0 online 4 *0.00 2812 0 no !--- CVA120 0020.4086.2704 10.1.4.5 C5/0/0/U0 online 5 -0.50 2808 0 no 0020.4086.3324 10.1.4.7 C5/0/0/U0 online 6 -0.50 2808 0 no 0020.4079.feb4 10.1.4.8 C5/0/0/U0 online 7 0.00 2805 0 no 0020.4085.d06a 10.1.4.9 C5/0/0/U0 online 8 -0.50 2807 0 no
Notice in this example that the ios.cf file commands the cable modems to have a hostname of SUCCEED, and indeed this is the filename that is seen when we telnet into the cable modem.
Schooner#telnet 10.1.4.4 Trying 10.1.4.4 ... Open SUCCEED line 1 User Access Verification Password: SUCCEED>en Password: SUCCEED#
To verify that the Cisco IOS configuration file was downloaded successfully to the cable modem use the command show version. The output below shows the information regarding the ios.cf file in bold.
SUCCEED#show version Cisco Internetwork Operating System Software IOS (tm) 120 Software (CVA120-K8V4Y5-M), Version 12.2(2)XA, EARLY DEPLOYMENT RELEASE SOFTWARE (fc1) TAC:Home:SW:IOS:Specials for info Copyright (c) 1986-2001 by cisco Systems, Inc. Compiled Wed 27-Jun-01 02:02 by hwcheng Image text-base: 0x800100A0, data-base: 0x80782844 ROM: System Bootstrap, Version 12.0(20001010:025045) [spaulsen-blue-3105 3108], DEVELOPMENT SOFTWARE ROM: 120 Software (CVA120-K8V4Y5-M), Version 12.2(2)XA, EARLY DEPLOYMENT RELEASE SOFTWARE (fc1) SUCCEED uptime is 3 days, 3 hours, 21 minutes System returned to ROM by reload at 05:52:09 - Sat Jan 1 2000 System restarted at 05:58:30 - Sat Oct 6 2001 System image file is "flash:cva120-k8v4y5-mz.122-2.XA.bin" Host configuration file is "tftp://10.1.4.1/ios.cf" cisco CVA122 CM (MPC850) processor (revision 3.r) with 32256K/1024K bytes of memory. Processor board ID SAD043708GK Bridging software. 1 Ethernet/IEEE 802.3 interface(s) 1 Cable Modem network interface(s) 1 Universal Serial Bus (USB) interface(s) 8192K bytes of processor board System flash (Read/Write) 7296K bytes of processor board Boot flash (Read/Write) Configuration register is 0x2
The configuration of the CVA120 is shown below. Notice that the commands in bold correspond to the lines in the ios.cf file.
SUCCEED#show run Building configuration... Current configuration : 1429 bytes ! ! Last configuration change at 11:22:22 - Tue Oct 9 2001 ! version 12.1 no service single-slot-reload-enable no service pad service timestamps debug uptime service timestamps log uptime no service password-encryption service linenumber service internal ! hostname SUCCEED ! no logging buffered no logging buffered logging rate-limit console 10 except errors enable password cisco ! clock timezone - -8 ip subnet-zero no ip routing no ip finger ! interface Ethernet0 ip address 10.1.4.11 255.255.255.0 no ip route-cache no ip mroute-cache load-interval 30 bridge-group 59 bridge-group 59 spanning-disabled ! interface cable-modem0 ip address docsis no ip route-cache no ip mroute-cache load-interval 30 cable-modem boot admin 2 cable-modem boot oper 5 cable-modem downstream mode annex-b cable-modem Mac-timer t2 40000 bridge-group 59 bridge-group 59 spanning-disabled ! interface USB0 ip address 10.1.4.11 255.255.255.0 no ip route-cache no ip mroute-cache arp timeout 0 bridge-group 59 bridge-group 59 spanning-disabled ! ip classless no ip http server no ip http cable-monitor ! snmp-server packetsize 4096 snmp-server chassis-id snmp-server manager ! voice-port 0 input gain -2 ! voice-port 1 input gain -2 ! mgcp modem passthrough voaal2 mode no mgcp timer receive-rtcp ! mgcp profile default ! line con 0 transport input none line vty 0 4 password cisco login ! end
It appears that the option command for cable config-file is broken because one may expect the commands below to give valid configuration.
option 43 instance 8 hex 00:00:0c option 43 instance 128 ASCII ios.cf
While these commands are accepted, it does not generate correct Cisco IOS config file. This is NOT a bug! The problem here is how the term "instance" was interpreted as a "sub-option," which it was never supposed to be.
The implementation of "instance" only permits the repetition of the same option multiple times, as when you have multiple instances of option 43 for various vendors! Here is an example:
option 43 instance 1 hex 08:03:00:00:0C:80:07:69:6F:73:2E:63:66:67 !--- Config file cisco CM option 43 instance 2 hex 08:03:11:22:33:80:07:69:6F:73:2E:63:66:67 !--- Some option for other CM
Notice that 11:22:33 is a random Vendor ID from a fictitious company. Any match with a real vendor ID is a pure coincidence.
Since the term "instance" is expected to reflect TLV sub-option fields, and you indeed have TLV sub-option fields, you will have to enter the entire string in Hexadecimal.