MIB Viewer

Modem Bootfiles

A DOCSIS bootfile is a small binary configuration file a cable modem downloads over TFTP during provisioning, telling it things like which services it's allowed to use, QoS parameters, and baseline privacy settings. It's written by hand as plain text, then compiled into the binary TLV (type-length-value) format the modem actually expects. This guide covers doing that with rlaager/docsis, a widely-used open-source encoder for exactly this purpose.

Installing it

Dependencies first, then build from source - there's no pre-built package for most distributions, so this is a compile-it-yourself tool:

# Debian / Ubuntu
sudo apt-get install automake libtool libsnmp-dev bison make gcc flex git libglib2.0-dev libfl-dev

# RHEL / CentOS / Fedora
sudo yum install autoconf automake libtool glib2-devel bison flex net-snmp-devel
git clone https://github.com/rlaager/docsis.git
cd docsis
./autogen.sh
./configure
make
sudo make install   # optional - installs to /usr/local, otherwise run ./docsis from the build directory

MIBs

The repository includes a mibs/ directory with the MIBs the tool needs to translate named OIDs (like docsDevSwServer) into their numeric form when you reference them by name in a config file, rather than requiring you to type out full dotted OIDs by hand.

Writing a config file

Config files are plain text, TLV settings one per line. A minimal example:

# basic.cfg
NetworkAccess 1
MaxCPE 2
GlobalPrivacyEnable 1

SnmpMibObject docsDevSwServer IPADDRESS 10.0.0.5
SnmpMibObject docsDevSwFilename STRING "cm-firmware-v2.bin"

NetworkAccess 1 allows the modem online at all; MaxCPE caps how many customer devices can share the connection; the SnmpMibObject lines let you set arbitrary SNMP objects directly from the config file - useful for the firmware-upgrade objects covered on the Modem Firmware Upgrades page, among other things.

Compiling the bootfile

Encoding a modem config file needs a key file (a shared secret used to compute the CMTS MIC, a cryptographic integrity check) in addition to the config itself:

echo "mysharedsecret" > key.txt
./docsis -e basic.cfg key.txt basic.bin

basic.bin is the actual binary bootfile - this is what gets placed on the TFTP server and referenced (usually by DHCP option 67, or a corresponding line in the DHCP server config) for the modem to download during provisioning.

To check what's actually inside a compiled bootfile - useful for confirming a file matches what you intended, or inspecting one you didn't write yourself - decode it back to text:

./docsis -d basic.bin

A known gotcha

Quoting hex string values (things like 0x0011ee) causes the encoder to crash - the documented workaround is simply not quoting hex definitions, even though quoting plain string values (as in the docsDevSwFilename line above) is fine and often necessary.