Assembler and Disassembler for DOCSIS cable modem configuration files.

The current release is 1.2 (alpha stage).

This distribution is free software under the GNU public license. Please
read the copyright notes in the COPYRIGHT file.


		     FEATURES OF THIS TOOL COLLECTION

This collection of DOCSIS tools consists of an assembler and disassembler
for cable modem configuration files. Both tools are completely ASCII based.
In designing them, I focused on reliability rather than appearance. In the
past, I have come to realise that `nice' graphical windows do not usually
help when it comes to solving complex technical problems.

The disassembler can be used in the following two output modes:

1. The default mode prints the content of the configuration file in a
   syntax that can be directly fed back to the assembler.

2. The pretty output mode (command line option `-p') prints the content in
   much detail and is very useful in finding problems with complex
   configuration files.

Typically, you generate configuration files using either of the following
methods:

1. To modify an existing file
 * first, disassemble your master file 
 * now edit the output according to your requirements 
 * finally, feed this outback back to the assembler

2. To create a new file from scratch
 * the assemble option `-e' (example) helps you to identify the correct
   input syntax of the assembler

The current version, 1.2, supports the DOCSIS 1.0 configuration setting
only.  All configuration settings for DOCSIS 1.0 are supported excluding
that for SNMP Write-Access Control Configuration.

Unfortunately, I have not been able to get the HMAC-MD5 running. So I have
decided to implement it in a future release. In the meantime, there should
be no problem using the old MD5. I have already tested it using a couple of
CMTSs, without any trouble.


			      PRODUCT HISTORY

Why did I decide to write these tools? And why am I now giving it away for
free?  It's a long story.

Things started when I installed my first DOCSIS cable modem (the modem came
from ELSA, the company that I was working for at the time). ELSA develops
CMs only - no CMTSs. This meant that the DOCSIS environment in that I had
to install the modem had already been installed by one of the `big' CMTS
vendors. And I had to use one of those cryptic configuration files that
came from the same CMTS vendor. Needless to say, it did not work!

Of course, the main problem turned out to be my modem. The CMTS vendor's
modems always work - but for some reason, mine didn't. There was one minor
twist, however. The problem was not actually with my modem, it was with the
modem's configuration file which, surprise, surprise, contained some
incredibly useless entries!!! Not surprisingly, the same `big' CMTS vendor
also generated this configuration file.  However, because this vendor
failed to deliver a configuration file editor to the network operator, the
operator was not able to generate an adequate configuration file.

Unfortunately, this kind of thing continued to happen again and again. I'd
navigate to some network, try to install the modem and then find myself
having to repair the configuration files (and the DHCP servers, but that's
another, even longer story). In the meantime, I started to collect illegal
configuration files. Here's a short list of typical problems that I
encountered with them:

* "max_burst_size = 255" (that's the obsolete default value - before it was
  changed to 1518 some years ago)
* double definition of Class of Services, both of which used the same
  Class-Id
* each Class of Service setting was not incorporated in its own QOS{}
  setting - unfortunately, both were incorporated in the same setting
* Vendor Specific Informtion which did not include Vendor-ID inside

Ok, I know my situation could have been improved a little by using that
`nice' JAVA-based tool from CableLabs (or was it Cisco?). But it really
only helps with simple problems. I mean, did you ever try to edit SNMP
command settings with this tool? I think you'll agree, the results can be a
little strange! And how often have you clicked the CLONE button when all
you wanted to do was CLOSE a fold? Another very obvious problem definitely
not addressed by this tool is how to generate configuration files - should
you generate them automatically or from a script? However, its single
greatest downfall is the fact that you cannot correct, improve or extend
it, since its sources are not free!

Needless to say, after 6 month of such trouble, I was no longer willing to
accept this very unsatisfactory situation. Over that time, I had complained
about it to practically everyone - but nobody was able to help.  There was
only one solution. I decided to write my own tools. And I decided to give
them away free to anyone who wants to use them.

Under the terms of the GNU General Public License, I'm now giving the
source of these tools free to everyone. This, of course, means that I'm
inviting all interested parties - and that means everyone - to help me
improve them.

			       AVAILABILITY

I'm currently constructing a web site in which to locate the sources for
these tools.  In the meantime it would be helpful if you'd drop me a short
e-mail telling me whether or not you are interested in being informed about
new versions.

My e-mail address is dpetras@elsa.de


			   COSTS

I have written all of these tools in my spare time. And I am offering the
software free to anyone who wants to use it. So, luckily enough, there are
no costs. You are welcome to use it for any purpose under the terms of the
GNU General Public License.  Of course, if you are happy with the results
of my programming labours, you are welcome to send me a `small' donation
(see e-mail address). You never know ... it could well motivate me to start
with the implementation of some new advanced features (see the TO DO list,
below).


		   CAN YOU HELP ME TO IMPROVE THE TOOLS?

Of course you can. Here's how ...

You can
* send me bug reports
* send me ideas for new features
* implement extensions and send me the patches
* write relevant user-friendly documentation 
* send me a donation


			       INSTALLATION

The tools have been compiled on GNU systems (I used Linux and Solaris) with
the following GNU packages:
* gcc version 2.95.2
* GNU Make version 3.77
* GNU Bison version 1.25
* flex version 2.5.4

The code should run on other C compilers without too much trouble.

For configuration, simply edit the first lines in the Makefile in
accordance with your local requirements. If you don't happen to have
lex/flex or yacc/bison and you do not want to install them, you can use the
precompiled files from the `no_bison' subdirectory. To do this, simply
enter `make no_bison' at the prompt.

For compilation and installation, follow these steps:

> make depend
> make all
> make install


			INVOCATION, COMMAND OPTIONS

DOCSIS configuration file assembler version 1.2:
Usage:  docas [options] input-file output-file
Output formats: DOCSIS-1.0 configuration files
Options:
  -m          encode CMTS MIC with old MD5 algorithm (default)
  -n          encode CMTS MIC with new HMAC-MD5 algorithm
  -s secret   authentication string (shared secret between server and CMTS)
  -h          Print this message
  -i num      Generate illegal configuration file for ATP testing.
              Valid numbers are:
                1: No End-Of-Data marker
                2: Invalid CM MIC
  -e          Print syntax example
  -l          debug lexical analyser
  -p          debug parser

DOCSIS configuration file disassembler version 1.2:
Usage:  docdisas [options] config-file
Input formats: DOCSIS-1.0 configuration files
Options:
  -p      print more readable (pretty) output
  -a      output syntax of GNU DOCSIS configuration file assembler (default) 
  -d      on UNIX platform print end-of-line in DOS mode
  -h      Print this message.
  -v      Verbose output, also implies -p (enables pretty output).


			  STABILITY OF THE TOOLS

The stability of the tools is guaranteed by the fact that the configuration
files generated by them are already used in plenty of DOCSIS networks. In
addition, they have been tested with several types of CMTSs and CMs. A
collection of test files can be viewed in the "files"-subdirectory.

However, as everyone knows, no software can be completely free of bugs. If
you come across any, you can report them to

<dpetras@elsa.de>


				   TO DO

Here's a list of improvements that still need to be implemented:

* make sure that HMAC-MD5 is up and running
* implement SNMP Write-Access Control Configuration setting
* print Vendor-Id as pretty string
* correct bug associated with SNMP objects consisting of four sub-object ID
  - because of bug these are interpreted as IP addresses
* implement DOCSIS 1.1
* write manuals & documentation
* improve portability

Any other suggestions?


				  AUTHOR

Dietmar Petras, Eupener Strasse 107, 52156 Monschau, Germany
E-Mail: dpetras@elsa.de

The MD5 algorithm is based on the public domain implemantation written by
Colin Plumb in 1993.

The getopt modules is copied from version 2.1.2 release of the GNU C
Library.


			     ACKNOWLEDGEMENTS

I would like to thank the following people and corporations for their
support in developing this software:

* Stefan Köhler <skoehler@elsa.de> and Markus Engelbrecht
  <mengelbr@elsa.de>, for giving me the most complex configuration files
  available for testing
* Dieter Hagel <dhagel@elsa.de> for supporting me to compile the programs
  under DOS
* Peter Bakker <pbakker@iel.ie> for helping me to write a better English
* Benjamin Appee <appee@sign-tech.de> for his extensive testings and bug
  reports
* That very large CMTS vendor I constantly refer to. Thanks again for
  producing such a huge number of bugs and illegal configuration files,
  both of which I used to test the software's error messages