1. General Information
======================

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

Portions of this program are derived from the RSA Data Security, Inc. MD5 Message-Digest Algorithm.

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 and http://sourceforge.net/projects/docsis 
for the latest news on this program.

PLEASE READ THE FILE License.txt.

Caution: This is Unsupported software that may crash your computer, damage all your data
or otherwise drive you nuts. You'd better know what you're doing. 

2. Description
==============

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

It supports most DOCSIS 2.0 Configuration Settings. Not supported (currently):

	* Telephony Settings
	* Modem Capabilities
	* Vendor ID (Partial support provided)
	* TFTP server timestamp
	* TFTP server provisioned modem address
	* SNMPv3 settings (partial support provided)

Refer to Appendix C of the Radio Frequency Interface Specification  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 (quite trivial).

3. Usage
========

There are three modes of operation:

a). 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, although simple, is not 
    described anywhere but the source code (see the grammar in docsis_yy.y 
    and lexical analyzer in docsis_lex.l). As sometimes an example is more 
    useful than a truckload of documentation, we've included a few 
    configuration files (see examples/cm/*.cfg).

    In this mode of operation (triggered by the "-e" switch), the program will 
    need a keyfile; it will calculate the CM MIC and use the string in the 
    keyfile to calculate a CMTS MIC; and it will add the DOCSIS End of Data 
    marker as well as pad at the end. 

    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. 

b). 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.
   
c). Decoding CM or MTA binary configuration files 

    To decode a binary file, do:

    unix $ ./docsis -d my_binary_file.bin

    The decoded output is not always "compatible" with itself, eg cannot be 
    directly encoded back into a binary file. 

    This is mostly due to the usage of ucd-snmp library functions to print the 
    SnmpMibObjects, which print out a different syntax than what we need.

    As of version 8.0, 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.

4. 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 share the same docsis_code, 
type-functions, limits etc. Only the id and parent can be different.
