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 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 and Markus Engelbrecht , for giving me the most complex configuration files available for testing * Dieter Hagel for supporting me to compile the programs under DOS * Peter Bakker for helping me to write a better English * Benjamin Appee 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