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

Comments

Hello, I have a question (hope isn't stupid one), where is the "dhcpd-v4.conf" file? I have already installed isp-dhcp-server but I don't know whether this file comes with the installation or I have to create it.
sorry about my english
Hello Hanz,

Where the isc-dhcp configuration file resides is Linux distribution dependent, but for e.g. Ubuntu, the default location is /etc/dhcp/dhcpd.conf. This configuration file should be created by the user as it describes the local network configuration. Most distributions do provide an example configuration file which is usually stored at /etc/dhcp/dhcpd.example or somewhere under /usr/share/dhcp.

At Excentis, we duplicated the dhcpd.conf file to the two files described above for the reason that ISC dhcpd cannot run in IPv4 and IPv6 at the same time (in the same process).

I hope this will help you out.
Great, you did make a excellent work!!!!
Hi Vincent, we have recently received DOCSIS 3.0 CM to test (those that we used currently are 2.0) and I trying for days to configure our ISC to deal with the 125 option without success.
When I put the option vivso generates an error, we are using the version 3.1.1... it means that this version can not use this option ?
Thanks, Bernardo.
Hi Bernardo,

In our setup, we are using ISC dhcpd 4.2.3.
The configuration of this option is quite tricky. Please make sure all the lengths of the TLV's are correct.

Best regards,
Vincent
Hello!
How would the setting to put fixed IP in CPE?

Thank´s
Hi Roberto,

In the host declaration in the configuration, adding

fixed-address 192.168.0.20;

will do the trick.
Hi,

I am having an issue having Cable modems connect on Freqs from 235 to 265 Mhz. They do connect at 429 Mhz. This is all in test lab prior to deployment. What Am I doing wrong?
Hi Mr. Ochoa,

Locking on a downstream is beyond the scope of the blog post.
My first guesses are:
- Is there really a downstream there? Is the downstream of the CMTS connected to that fiber node?
- Is the SNR good? Isn't there too much noise on that frequency (those frequencies)?
- Is the received power at the modem ok?

Best regards,
Vincent De Maertelaere
Hi Vincent,
Great jobs !
We also use isc dhcp for ipv4 that allow execute script for specifc modem during regstration.
what's about prefix delegation for erouter in ipv6 mode ?
We tried to use isc for this without success no issu using CNR from cisco.
issue is no prefixe available for this interface.
Thanks in advance
Best regards,
Gwen
Hi Gwen,

I remember we needed to patch the ISC dhcpd code for this. We also suggested the fix to the ISC developers and is incorporated in release 4.2.4b1 of ISC dhcpd.

We also use the prefix pool syntax for our CPE subnets:
e.g. prefix6 subnet-start subnet-stop /48.

I hope this helps.
Best Regards
Vincent
(This is also sent by email)
About DHCP offer that DHCP server send to cable modem after CM did DHCP request: which protocol (interface) use CM and DHCP server on CMTS side for this communications? Ethernet interface or via RF (cable) interface?
Hi Mike,

A cable modem uses standard DHCPv4 and DHCPv6 for provisioning. This is done over the RF to the DHCP server in the operators network.

Vincent
wowway contends they can not send the latest update to my netgear modem/router. how do I provision my unit to accept the FW? What do I give up by provisioning my unit? At one point the net genie did the download and kept my unit current. I have a router mode # C3700-100NAS firmware V01.01.05. my ISP and netgear refuse to upgrade - each says to go to the other and neither will send FW upgrade.
Hi Loren Zaleski,

For security reasons described in the DOCSIS specifications, the ISP is the only one which can upgrade a cable modem.

When new firmware updates are available for a cable modem, the firmware will usually undergo extensive testing in the lab of the ISP. Those tests validate whether the firmware works nicely with all equipment used by the ISP.

Hope this clarifies the matter a little.
Best Regards
Vincent
Hi, Can you please let me know the DHCP options which contain the model # and vendor Information for a modem in this DHCP message exchange ?
Hi Aditya,

Those are described in the CableLabs DHCP Options Registry (https://specification-search.cablelabs.com/CL-SP-CANN-DHCP-Reg section 4.1)

The options are DHCP Option 43.9 (Model number) and DHCP Option 43.10 (Vendor Name).

Vincent

Add new comment