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

Reader interactions

18 Replies to “How to provision a cable modem using the ISC DHCP server”

  1. 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

    Reply

  2. Vincent De Maertelaere September 7, 2015 at 6:38 am

    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.

    Reply

  3. Great, you did make a excellent work!!!!

    Reply

  4. 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.

    Reply

  5. Vincent De Maertelaere May 19, 2016 at 6:40 am

    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

    Reply

  6. Roberto Schmitz June 13, 2016 at 6:40 am

    Hello!
    How would the setting to put fixed IP in CPE?

    ThankĀ“s

    Reply

  7. Vincent De Maertelaere June 30, 2016 at 6:41 am

    Hi Roberto,

    In the host declaration in the configuration, adding

    fixed-address 192.168.0.20;

    will do the trick.

    Reply

  8. 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?

    Reply

  9. Vincent De Maertelaere September 26, 2016 at 6:43 am

    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

    Reply

  10. 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

    Reply

  11. Vincent De Maertelaere April 26, 2018 at 6:44 am

    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)

    Reply

  12. 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?

    Reply

  13. Vincent De Maertelaere June 6, 2018 at 6:59 am

    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

    Reply

  14. loren zaleski July 21, 2018 at 7:00 am

    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.

    Reply

  15. Vincent De Maertelaere August 7, 2018 at 7:00 am

    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

    Reply

  16. 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 ?

    Reply

  17. Vincent De Maertelaere June 13, 2019 at 7:01 am

    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

    Reply

  18. Alakuntla KranthiKumar June 3, 2020 at 7:02 am

    I am using Dhcp server and Arris Cmts and My Modem is showing ranged but IP is not getting assigned.
    I had checked Dhcp is providing ip to Modem and when i checked by Connecting Laptop i am getting IP to Laptop but for MOdem it’s not coming IP.
    Kindly help me for Config.
    Please find my below Config
    [root@linux ~]# vi /etc/dhcp/dhcpd.conf
    option space PacketCable;
    option PacketCable.pri-dhcp code 1 = ip-address;
    option PacketCable.sec-dhcp code 2 = ip-address;
    option PacketCable.kerberos-realm-name code 6 = text;
    option packet-cable code 122 = encapsulate PacketCable;
    option PacketCable.pri-dhcp 172.29.0.2;
    # interface eth1
    shared-network office-network {

    subnet 172.29.0.0 netmask 255.255.255.0 {
    }
    # cm on cmts 2 (arris)

    subnet 10.1.0.0 netmask 255.255.0.0 {
    option time-servers 172.29.0.2;
    option netbios-name-servers 172.29.0.2;
    range 10.1.0.2 10.1.10.240;
    option domain-name-servers 8.8.8.8, 8.8.4.4;
    option routers 10.1.0.1;
    default-lease-time 345600;
    max-lease-time 691200;
    allow unknown-clients;
    authoritative;
    }
    # cpe
    subnet 10.101.0.0 netmask 255.255.0.0 {
    option time-servers 172.29.0.2;
    range 10.101.0.2 10.101.20.254;
    option netbios-name-servers 172.29.0.2;
    option domain-name-servers 8.8.8.8,8.8.4.4;
    option routers 10.101.0.1;
    default-lease-time 345600;
    max-lease-time 691200;
    allow unknown-clients;
    authoritative;

    }
    }
    host laptop {
    hardware ethernet 18:60:24:c1:fa:ab;
    fixed-address 10.101.0.200;
    }
    ~

    Logs of dhcp server
    : Jun 3 11:33:35 linux dhcpd: DHCPDISCOVER from bc:c8:10:5d:f8:b6 via 10.1.0.1
    Jun 3 11:33:35 linux dhcpd: DHCPOFFER on 10.1.1.116 to bc:c8:10:5d:f8:b6 via 10.1.0.1

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *


The reCAPTCHA verification period has expired. Please reload the page.