docsis

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

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

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

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 COPYING.GPL.

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 RFI 1.1
Specification, Appendix C.

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

* Telephony Settings
* Modem Capabilities
* Vendor-specific information
* Vendor ID
* TFTP server timestamp
* TFTP server provisioned modem address
* SNMPv3 settings

See DOCSIS 1.1 Radio Frequency Interface Specification, Appendix C for a
description of these settings.

A limited range of ASN types are supported for SNMP MibObjects (the most used
types - Integer, String, HexString, IP Address). Adding a new ASN type is as
easy as cut&paste from UCD-SNMP source code into docsis_snmp.c, function
encode_vbind (well, maybe a few changes are needed, but I trust the reader can
figure it out).

A. 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).

B. DOCSIS 1.1 considerations
============================

The DOCSIS 1.1 implementation is being tested. A major rewrite was needed to
add support for DOCSIS 1.1 and clean up the parsing, encoding and decoding, so
expect the docsis-0.7.x versions to be be less stable/bug-free than the
docsis-0.6.x series. However because of the cleanup (mostly done by the Evvolve
guys) the bugs will be much easier to fix and the new features (configuration
settings) A LOT easier to add.

3. Usage
========

To encode a configuration file, do:

unix $ ./docsis -e my_config_file.cfg my_key_file my_config_file.md5

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, I've included a few configuration files (see
examples/*.cfg).

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 decode a binary file, do:

unix $ ./docsis -d my_binary_file.md5

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.

If you want to encode back a decoded file, you have to fix the syntax of
SnmpMibObject settings and delete CM MIC and CMTS MIC lines.
Then you should be able to encode the file back.

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, docsis_code} pair
must be unique, e.g. 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.