General Information

This software is copyright (c) 1999,2000,2001,2002 Cornel Ciocirlan and copyright (c) 2002,2003 Evvolve Media SRL

To contact the current maintainers and developers, send an E-mail to: docsis@evvolve.com.
To contact the original author, send an E-mail to: ctrl@users.sourceforge.net.

General questions about this software can be  sent to docsis-users@sourceforge.net.

Visit http://docsis.sourceforge.net or  http://sourceforge.net/projects/docsis for the latest news on this program.

PLEASE READ THE FILE License.txt. You cannot use this software unless you agree to the conditions of the GNU General Public License, which are outlined in this file.

Description

This program encodes text configuration files which contain Configuration File Settings into binary configuration files, as specified by the DOCSIS RFI 1.1
Specification, Appendix C.

It supports most DOCSIS 1.1 Configuration Settings. Not supported (currently):
See DOCSIS 2.0 Radio Frequency Interface Specification, Appendix C for a description of these settings.

DOCSIS 1.0 considerations

More than one (up to 16) ClassOfService statements can appear in the configuration file. Only one BaselinePrivacy (BPI) statement can appear.
The program does not check for the number of ClassOfService statements that appear, you have to make sure not to include more than 16 or unexpected results will occur  (modems /CMTSes may reset).

DOCSIS BPI Specification clearly states that the BPI settings MUST NOT be present if Privacy is not enabled in [at least one of] the ClassOfService
parameters (for example if PrivacyEnable is 0 for all classes of service, BPI statement should not appear).

The program is not yet as "intelligent" as to detect these problems automatically.

Usage

There are three modes of operation:

  1. Encoding CM configuration files

    To encode a CM configuration file, make sure "docsis" is in your PATH and do:

     unix $ docsis -e cm_config_file.cfg my_key_file cm_config_file.bin

    The format of the text configuration file is described here. As sometimes an example is more  useful than a truckload of documentation, we've included a few configuration files (see examples/*.cfg).

    In this mode of operation (triggered by the "-e" switch), the program will need a keyfile; this is the so-called "shared secret" or "authentication string". The program uses the string in the keyfile to calculate the CMTS MIC. This string has to be configured on the CMTS as well, otherwise the cable modem will not be able to register.

    An example key is provided in file testkey.key. The key is only a string of characters. Any trailing newline (\n) or carriage return (\r) characters are chopped to avoid confusion.

  2. Encoding PacketCable MTA configuration files

    MTA Configuration file support has been added in version 0.8.1.

    To encode a CM configuration file, make sure "docsis" is in your PATH and do:

    unix $ docsis -p mta_config_file.cfg mta_config_file.bin

    PacketCable MTA config files MUST start with the "MtaConfigDelimiter 1" configuration setting and MUST end with "MtaConfigDelimiter 255". All
    other configuration settings must be either SnmpMibObject or VendorSpecific. The program does not enforce this policy so you must make  sure you abide by it or the MTA will reject the file.

  3. Decoding CM or MTA binary configuration files

    To decode a binary file, do:

    unix $ docsis -d my_binary_file.bin

    As of version 0.8, you can directly encode the decoded output. E.g.

    unix $ docsis -d cm_test.bin > cm_test.cfg
    unix $ docsis -e cm_test.cfg testkey.key cm_test.bin
    unix $ docsis -d mta_test.bin > mta_test.cfg
    unix $ docsis -p mta_test.cfg mta_test.bin

    should work, save for still remaining bugs.

Adding new configuration settings

To add new configuration settings, in most cases the only thing you need to do is add them to the docsis_symtable.h (make sure you select the correct
type-functions for encoding and decoding).

Because of the way the encoder works, the symbol_name must determine all other values in the table with the exception of id and parent.
Thus if two symbols share the same name they must also share the same docsis_code, type-functions, limits etc. Only the id and parent can be different.