How to provision a cable modem using the ISC DHCP server

Since the early days of DOCSIS, cable modems are provisioned using DHCP, the Dynamic Host Configuration Protocol, to obtain the basic connectivity settings.

When the cable modem is powered on, it begins the ranging process with the CMTS. When the ranging process completes, the cable modem starts with the IP provisioning process, which initiates with the Dynamic Host Configuration Protocol (DHCP). DHCP is used to retrieve an IP address, to announce capabilities and retrieve parameters for the next stage of provisioning: acquire the current time and the configuration file. Using all the configuration parameters gathered in the DHCP process and the configuration file download, the cable modem can register with the CMTS.

This blog post shows how to configure the ISC DHCP server to provision cable modems.

DHCP and DOCSIS

Because cable modems need non-standard DHCP options, CableLabs has written a specification to define new options. The options required for a cable modem to boot, are defined in the MAC and Upper Layer Protocols Interface (MULPI) Specification.

For IPv4, the following DHCP parameters and options must be provided by the DHCP server:

• yiaddr: IP address to be used by the cable modem
• next-server: IP address of the TFTP server to be used to download the configuration file from (Required for DOCSIS2.0 cable modems)
• boot-file-name: Name of the configuration file to be downloaded from the TFTP server. By the way, we have a separate blog post on how to create a cable modem config file.
• option 1: subnet mask (optional)
• option 2: time offset of the CM from UTC (optional)
• option 3: router option: list of routers to be used to forward traffic from the cable modem. (optional, but recommended)
• option 4: time server option, Time of Day server(s) to be used by the cable modem to synchronize its clock with. (optional, but recommended)
• option 125.2: CL_V4OPTION_TFTP_SERVERS  – Override for the TFTP server specified in next-server

In DHCPv6, the options are defined as vendor specific options.  Only the IPv6 address information (IA_NA) is configured using the standard DHCPv6 options. The vendor specific options are as following:

• option 17.37: CL_OPTION_TIME_SERVERS – Time Protocol Servers option (optional)
• option 17.38: CL_OPTION_TIME_OFFSET –  Time Offset option (optional)
• option 17.32: CL_OPTION_TFTP_SERVERS – TFTP Servers Address option
• option 17.33: CL_OPTION_CONFIG_FILE_NAME – Configuration File Name option
• option 17.34: CL_OPTION_SYSLOG_SERVERS – Syslog Server Address option (optional)

Configuring ISC DHCP

We will be using the ISC DHCP server in this blog post. In the section above, we learned which options are required to provision a cable modem, but some are not known by ISC by default. Fortunately, the ISC DHCP server can be extended with other, non-standard options.

Also the ISC DHCP server (or daemon) cannot run in multiple IP modes (IPv4, IPv6) at the same time, therefore the daemon must be started once for every IP mode.

In this section we will show how to configure each of these instances of the ISC DHCP server.

DHCPv4

The DHCPv4 configuration file:

# dhcpd-v4.conf

# DHCPv4 server configuration statements

# Where does DHCPd needs to save its leases database
# /var/db/dhcpdv4.leases is probably a good location?
lease-file-name "/path/to/dhcpdv4.leases";

# Is this DHCP server the authorative DHCP server in this network?
# In this case, it is not.
#authorative;

# Where to send its logmessages?
log-facility local7;

# Common options for all hosts

# Assume our syslog server is at 10.16.0.2
option log-servers 10.16.0.2;

# Assume our time servers are at 10.16.0.3 and 10.17.0.3
# This configuration will provide a fallback for the time servers
option time-servers 10.16.0.3, 10.17.0.3;

# Assume our configuration file server (TFTP server) is at 10.16.0.4 and 10.17.0.4
# Old (pre DOCSIS 3.0) modems use the next-server field of the DHCP message
next-server 10.16.0.4

# DOCSIS 3.0+ modems only use next-server if the vivso.2 option is not available
# The newer vivso.2 option allows multiple addresses and thus fallback mechanisms
# Due to some limitations in the ISC dhcpd configuration, we need to encode this in
# hexadecimal, so let's do this:
option vivso 00:00:11:8b:0a:02:08:0a:10:00:04:0a:11:00:04;


# Subnet configuration
# The DHCP server needs a subnet declaration for at least one of the provisioning interfaces,
# so we assume the provisioning interface (the interface used by the relay-agent of the CMTS
# is 10.16.0.5.  We also don't want this DHCP server to provision our backend, so we declare 
# the network, but don't allow the server to hand out any leases
subnet 10.16.0.0 netmask 255.255.255.0 {
    ignore booting;
}

# subnets for the cable modems:
subnet 10.128.0.0 netmask 255.255.0.0 {
    # CMTS-1
    range 10.128.0.2 10.128.255.254;
    option broadcast-address 10.128.255.255;

    default-lease-time 23200;
    max-lease-time 86400;
    # only allow known cable modems
    deny unknown-clients;
}

# subnets for the customer equipment 
subnet 123.128.0.0 netmask 255.255.0.0 {
    # CMTS-1
    # we keep 123.128.0.2-123.128.0.255 for fixed addresses
    range 123.128.1.1 123.128.255.254;
    option routers 123.128.0.1;
    option broadcast-address 123.128.255.255;
    
    default-lease-time 3600;    max-lease-time 7200;
    # allow unknown clients, we don't want to keep track 
    # of all end user equipment
    allow unknown-clients;
}

# Cable modem declarations
host cm-00ff1f000001 {
    hardware ethernet 00:ff:1f:00:00:01;
    # configure the boot-file name DHCP parameter
    # this customer has an unlimited subscription
    filename "cm/unlimited.cfg";
    option bootfile-name "cm/unlimited.cfg";
}

host cm-00ff1f000002 {
    hardware ethernet 00:ff:1f:00:00:02;
    # configure the boot-file name DHCP parameter
    # this customer has a limited 20/2 subscription
    filename "cm/limited-20-2.cfg";
    option bootfile-name "cm/unlimited.cfg";
}

# Enterprise customers get a fixed IP for their gateways.
# The MAC address is given by them
host customer-1-excentis {
    hardware ethernet 00:ff:1f:00:00:03;
    fixed-address 123.128.0.8;
}

In the example above, a lot of information is stored. Let’s walk through it.

First we provide the DHCP server’s configuration for internal bookkeeping. This way, the DHCP server knows where to store its lease database and whether or not it is authorative for this network.

Next common options for all hosts are configured. It seems all pretty straight-forward but a vivso option is configured with a strange hexadecimal value and the CL_V4OPTION_TFTP_SERVERS is not.
This is because, due to a limitation of ISC DHCPd, sub options cannot be declared within the vivso option. So what is that vivso option?
Well the vivso ‘syntax’ is this:

option vivso <entreprise number> <length of the vivso TLV contents> <option type> <option length> <option value>...

So, for one TFTP address it can be substituted as follows:

• Entreprise Number = 4491 (entreprise number of CableLabs, in dotted hex: 00:00:11:8b)
• option type = 2 (CL_V4OPTION_TFTPSERVERS)
• option length = 4 (bytes in an IP address)
• option value = IP address in hex (in our example 10.16.0.4 would be 0a:10:00:04)
• length of the vivso TLV contents = 6 (1 byte of type, 1 byte of length and 4 bytes of data)

This becomes

option vivso 00:00:11:8b:06:02:04:0a:10:00:04;

For two TFTP server addresses, it changes a little:

• Entreprise Number = 4491 (entreprise number of CableLabs, in dotted hex: 00:00:11:8b)
• option type = 2 (CL_V4OPTION_TFTPSERVERS)
• option length = 4 (bytes in an IP address)
• option value = IP addresses in hex (in our example 10.16.0.4 and 10.17.0.4 would be 0a:10:00:04:0a:11:00:04)
• length of the vivso TLV contents = 10 (0x0a) (1 byte of type, 1 byte of length and 8 bytes of data)

option vivso 00:00:11:8b:0a:02:08:0a:10:00:04:0a:11:00:04;

After these common options, the subnets to be provisioned are configured. These subnet declarations allow all options which can be different between subnets. It is for example possible to configure different name servers or TFTP servers per subnet.

The subnet declarations are followed by the host declarations. When a host is declared in the DHCP servers configuration file, it will get the options specified here.

The complete set of options is created as follows:

1. Take all global options.
2. Take all options defined for the network where the DHCP message is received from.
3. Take all options for the host.

This means that a usually best case option can be set globally and be overridden by the subnet or host configuration!

DHCPv6

The DHCPv6 configuration file resembles the DHCPv4 configuration file a lot, but it is still a little different. First we need to declare the CableLabs Vendor Specific Information Options.

# declare the option space where the CableLabs options live
option space docsis code width 2 length width 2 hash size 100;
# CL_OPTION_TFTP_SERVERS
option docsis.tftp-servers code 32 = array of ip6-address;
# CL_OPTION_CONFIG_FILE_NAME
option docsis.configuration-file code 33 = text;
# CL_OPTION_SYSLOG_SERVERS
option docsis.syslog-servers code 34 = array of ip6-address;
# CL_OPTION_TIME_SERVERS
option docsis.time-servers code 37 = array of ip6-address;
# CL_OPTION_TIME_OFFSET
option docsis.time-offset code 38 = signed integer 32;

# declare the option space docsis from above are suboptions of 
# the vsio option (17)
option vsio.docsis code 4491 = encapsulate docsis;

Now the DHCP server knows the CableLabs specific options, we can configure a subnet:

subnet6 fd52:1234:134:abcd::/64 {
    range6 fd52:1234:134:abcd::2 fd52:1234:134:abcd::ffff;
    deny unknown-clients;
    docsis.tftp-servers fd52:1000::3, fd52:1001::3;
    docsis.time-servers fd52:1000::4;
}

And hosts:

host cm-00ff1f000001 {
    clientid 00:03:00:01:00:ff:1f:00:00:01;
    docsis.configuration-file "cm/unlimited.cfg";
}

Starting the DHCP server

# starting the DHCP server in IPv4 mode
# /path/to/dhcpd -4 -cf /path/to/dhcpdv4.conf

# starting the DHCP server in IPv6 mode
# /path/to/dhcpd -6 -cf /path/to/dhcpdv6.conf

Conclusion

The ISC DHCP daemon is a powerful beast. It can provision about every possible device. If the DHCP options you need are not known by default, they can be declared. The ISC DHCP daemon knows more than the options shown in the examples above, but this is out of the scope of this article. A comprehensive list can be found on the website of IPAM Worldwide.

References

• Internet Software Consortium DHCP website
• DHCP mailing-lists
• IPAM Worldwide about DHCP

• Category: Cable Modem, DHCP, DOCSIS, Provisioning