DocsDiag - DOCSIS cable modem diagnostics


DocsDiag is a program for reading diagnostic data from DOCSIS cable modems. It should work with any DOCSIS-compliant cable modem that has SNMP access available to the end-user. It will be of primary benefit to end-users with cable modems that do not offer diagnostics via web pages.

DocsDiag is a text-mode console program without any graphical user interface. It will run on any platform that supports Java console applications.

Many models of cable modem do not work with the default settings of DocsDiag. Before using DocsDiag for the first time, please read the recipes for:

If you have a firewall, you might need to disable it.

Contents of this page:


Download instructions

DocsDiag is supplied as a .zip archive.

Download the latest version 030720 here: docsdiag.zip (check: length 77,553 bytes).

After download, the .zip file must be expanded. If you have Windows ME or XP, this can be done by right-clicking docsdiag.zip, and selecting Extract all.... Otherwise, you will need an un-zip utility such as the free Stuffit Expander for Windows. (Although Windows ME and XP allow you to look inside a compressed folder, do not try to use the files from inside the compressed folder: extract them first).

The extracted files comprise docsdiag.jar (which contains the DoscDiag program, used on all platforms) plus some helper files (for Windows only). Do not attempt to expand the docsdiag.jar file into its component parts.


Requirements

A DOCSIS-compliant cable modem. Not all cable modems are DOCSIS ones.

Java runtime support for Java 1.1.x or higher. This appears to be available on all versions of Windows that have IE4 or higher installed, except that Windows XP users might need to install Java runtime support: see below. Other platforms might need to install Java Runtime Support from Sun.

Firewalls and NAT routers must allow traffic to/from UDP port 161 (SNMP) of the IP address being diagnosed, or in the case of -ubrip, to/from UDP port 161 of all addresses searched. You might need to disable or uninstall your firewall if you cannot configure it to allow this.

The cable operator must permit SNMP read access to cable modems with community string "public". If the cable operator has changed the community string, then DocsDiag will not work unless you can tell it what the new community string is.

No other significant upload or download traffic during use, such as might cause UDP traffic to be lost or delayed.


To run under Windows:

Open the folder containing the unzipped files.

To run DocsDiag without any parameters, just double-click 2kXP-run (on Windows 2000/XP) or 9xME-run (on Windows 9x/ME). Thats it!

To run DocsDiag with parameters, double-click 2kXP-win (on Windows 2000/XP) or 9xME-win (on Windows 9x/ME). This will open a command window with the current directory automatically set to the directory containing docsdiag.jar.

To run DocsDiag under the Microsoft Virtual Machine, type the command:

jview /cp docsdiag.jar docsdiag  parameters

If you wish to save the output to file, add a redirection at the very end of the line, such as:

jview /cp docsdiag.jar docsdiag  parameters  >results.txt

where the parameters to use are documented below.

Note for Windows XP users: XP as installed does not include the jview command. It was available for a short period as part of Windows XP Service Pack 1, but was later removed from SP1. It currently cannot be easily obtained from Microsoft. If your XP system does not include the jview command, you should download and use the Sun Java 2 Runtime Environment - see below.


To run on platforms supporting the Sun Java Runtime Environment:

Under the Sun Java Runtime Environment v1.1.x, type the command:

jre -cp docsdiag.jar docsdiag  parameters

Under the Sun Java 2 Runtime Environment, type the command:

java -jar docsdiag.jar  parameters

Parameters

-v verbose output: IP/MAC addresses and error counters also displayed. This is a worthwhile improvement on the default output, but is longer.
-vv very verbose output: for all data relevant to cable modems.
-vvv very very verbose output: for a full MIB walk.
-log also print the cable modem event log.
-cmip <ipaddr> cable modem IP address <ipaddr>. Defaults to trying some well-known customer-side cable modem IP addresses, in particular 192.168.100.1. If <ipaddr> looks like a private ISP-side address, then one of -cmmac or -cmser is also required.
-cmmac <MACaddr>  cable modem HFC MAC address, from the label on the cable modem, as a string of 12 hexadecimal digits, with optional separators hyphen, colon, or period to break the digits into groups as you wish. Only required if <ipaddr> is a private ISP-side address, or if -ubrip is used. This is used as evidence that the user has authority to access the cable modem. -cmmac and -cmser are alternatives, either will do.
-cmser <serial> cable modem serial number, as a string of letters and numbers. Only required if <ipaddr> is a private ISP-side address, or if -ubrip is used. This is used as evidence that the user has authority to access the cable modem. -cmmac and -cmser are alternatives, either will do.
-ubrip <ubraddr> requests a search of all cable modems attached to the local UBR (head-end) interface with private IP address <ubraddr>, searching for a match with the data given either in -cmmac or in -cmser. This can take a long time. Be very careful to quote the UBR's private address precisely correctly: see instructions below for discovering it, and examples in the ISP-side recipe below. Must be used with one of -cmmac, -cmser, -srchup.
-netw <int> the -ubrip search will be of length 2 to the power <int> IP addresses, where <int> is in the range 4 to 16. Defaults to 11.
-traffic Analyses the traffic usage on each downstream and upstream of the UBR. See further instructions below.
-srpt <int> the number of times an SNMP request will be sent to each address in the -ubrip search before giving up. Default 1. Increasing this parameter might solve failures to find the cable modem when line conditions are difficult.
-sto <int> the timout in milliseonds that DocsDiag will wait for a reply to each request in the -ubrip search. Default 500.
-rrpt <int> the number of times an SNMP request will be sent when reading data before giving up. Default 3.
-rto <int> the timeout in milliseconds that DocsDiag will wait for a reply to each read request. Default 1000.
-community <string>  sets the community string used for SNMP read requests. The default is public.
-walk <OID> suppress normal cable modem output, and perform a MIB walk based on <OID> in dotted decimal.
-nodecode suppress normal interpretation of OIDs and object values.

Example of use with parameters:

jview /cp docsdiag.jar docsdiag -vv >results.txt
 
jview /cp docsdiag.jar docsdiag -cmip 172.25.123.98 -cmmac 002040789ABC

jview /cp docsdiag.jar docsdiag -ubrip 172.25.123.254 -cmmac 002040789ABC

DOCSIS cable modems have two possible IP addresses that can be used with -cmip, one for the customer-side interface, and one for the ISP-side interface. For more information on this, see http://homepage.ntlworld.com/robin.d.h.walker/cmtips/ipaddr.html#cmip. The ISP-side address cannot be used in ex-C&W regions of NTL.

Before using the -ubrip option, you might need to uninstall any firewall you have on your PC. The -ubrip option will only work if the cable modem is online to the cable operator's network. The -ubrip option cannot be used in ex-C&W regions of NTL. The UBR private IP address to use as value to the -ubrip parameter can be discovered from the results of the first hop of a traceroute to anywhere: see http://homepage.ntlworld.com/robin.d.h.walker/cmtips/ipaddr.html#ubrip. See the ISP-side recipe below for an example. The -ubrip parameter usually requires a private IP address in the range 10.xxx.xxx.xxx or 172.yy.xxx.xxx (where yy is in the range 16-31), and -ubrip is unlikely to work with other values. The -ubrip option will output one character per cable modem checked while it is searching, which can take several minutes, depending on the values of -netw, -srpt, and -sto. The character will be:

If all you see are rows of unbroken dots with not a single X, then it possible that your cable operator has filtered out SNMP access to its network, and DocsDiag will be no help to you: see How to tell if your cable ISP has disabled SNMP below.

You should need to use the -ubrip search only once: it will finish by telling you the ISP-side address of your cable modem, so that you can use the faster -cmip option in the future.

To analyse traffic usage on the cable network of your UBR, use the syntax:

jview /cp docsdiag.jar docsdiag -traffic

This will try to read the search range data from your cable modem. It will be able to do this if DocsDiag can normally read data from your cable modem without special options. If it fails to read the search range, it will say so, and you should then try the syntax:

jview /cp docsdiag.jar docsdiag -ubrip 172.25.123.254 -traffic

where the -ubrip address is discovered as described above. The -traffic option cannot be used in ex-C&W regions of NTL.

Warning: some cable operators might consider the use of -ubrip to be a breach of their AUP. Proceed at your own risk.

The -netw parameter enables you to specify the length of the search, as a power of 2. -netw defaults to 11 (to search 2048 addresses): you can over-ride this default if you need to. The "right" value of -netw is the size of the sub-net in which the UBR and ISP-side cable modem addresses lie, but this is not knowable in advance of first use [and Java cannot test the sub-net size in a platform-independent way].


Typical output

DocsDiag v020414 Copyright 2001-2 Robin Walker rdhw@cam.ac.uk

General Instrument SB3100 Cable Modem: Hardware version: 1; OS: VxWorks 5.3.1; Software version: 3.2.9p

Downstream channel ID                = 3
Downstream channel frequency         = 403000000 Hz
Downstream received signal power     = 0.0 dBmV (or not supported)
Upstream channel ID                  = 2
Upstream channel frequency           = 35984000 Hz
QoS max upstream bandwidth           = 128000 bps
QoS max downstream bandwidth         = 600000 bps
SigQu: Signal to Noise Ratio         = 33.8 dB
Cable modem status                   = Registration complete
Upstream transmit signal power       = 54.0 dBmV
Date and Time                        = 2002-04-14,21:18:12.00+00:00
Configuration filename               = mota4100-silver.cm

This is an example of typical output for a particular brand of cable modem, and is not indicative of acceptable values. There will be differences between brands, and between ISPs. For an explanation of the acceptability of the noise and signal levels, please see http://homepage.ntlworld.com/robin.d.h.walker/cmtips/signal.html. Please do not post just these results and ask "Are these OK?" on support forums: this utility is provided as an aid to diagnosing pre-existing problems, not as a source of problems in itself. With the error counters shown in the verbose modes, the important thing is not so much their absolute value (which might be due to problems fixed long ago), but the rate at which they are now increasing: so you might need to take two sets of readings and compare the counters.

A typical -traffic report looks like:

UBR 172.30.111.254 at 2002 Jul 14, 17:48

Channel   Freq     Max  Usage  Users  Min  Ave  Max
           MHz    kbps   kbps          ms   ms   ms
Dnstr 3  402.75? 30342   6897    529   23   55  260
Upstr 1   32.8    2560    713    157   39   67  220
Upstr 2   36.0    2560    132     82   23   44  201
Upstr 3   39.2    2560    408    128   34   50  260
Upstr 4   32.8    2560    109     84   36   43  110
Upstr 5   40.8    2560    142     33   32   42  100
Upstr 6   34.4    2560    230     45   33   47   90

Note: timings include one hop on your up/downstream
and at least one on target up/downstream.

This is a typical example and is not indicative of acceptable values. Normal recommendations are that there should be no more than 200 users per upstream channel.


Future plans


Known Problems


Change History

030720: Fixed ASN.1 library for various integer overflow problems, some of which caused an exception if an OID component appeared negative in 32-bit integers. Fixed a class exception in the decoding of docsDevFilterPolicyPtr.

030216: Improved -traffic report option so that, if it can, it reads its configuration information directly from the user's cable modem (this means that it is no longer normally necessary to quote -ubrip or -netw options with -traffic). Changed -netw to default to 11 independent of the value of -ubrip. Added decoding for Scientific Atlanta objects (root only). Added decoding for IP Pause objects. Syntax of -cmmac option now permits separators hyphen, colon, or period to break the hexadecimal characters into groups.

020927: Fixed(?) an OutOfBoundsException in the -traffic option.

2002 Aug 29/30: Documentation only updated.

020714: Experimental version: added option -traffic and withdrew -srchup. The traffic report includes, for each downstream and upstream channel: the maximum capacity, the current traffic load, and the number of cable modems connected. Current traffic load figures are lower-bound estimates, and might not be a true picture: if they are systematically wrong, they are likely to be wrong in the same way for all channels. Round-trip times of the enquiries include one hop on your local upstream/downstream and one hop (plus perhaps an ARP) on the target upstream/downstream. Cable modems which do not respond will not be included in the totals.

020705: Experimental version: added option -srchup. When used with -ubrip, counts the number of cable modems on each upstream frequency of the UBR. Cable modems which do not respond will not be included in the totals.

020604: Fixed problem introduced in 020505 causing refusal to read SNMP from public IP addresses.

020505: Added parameters -rrpt (read repeat count) and -rto (read time-out) to control SNMP read requests. Extensive internal changes to ensure that, while reading from one cable modem, only one local UDP port is used.

020428: Added parameters -srpt (search repeat count) and -sto (search time-out) to control the -ubrip search. Increased the default for -netw to 11. Added system uptime to the default report. Corrected the format of SNMP date/time strings (deciseconds, not centiseconds). Started optimising the code for string handling to reduce memory churn and garbage collection. Added warning message if the -ubrip parameter is not within a private IP range. Added decoding for Host and Lanman objects.

020421: Fixed unintended display of ethernet errors at beginning of -vvv report introduced in 020414. Added microreflections to -v report. Added decoding for some DOCSIS 2.0 objects. BPI object names prefixed with BPI. Surfboard private object names prefixed with SB. The old experimental docsdev object names prefixed with Exptl to distinguish them from the final versions. Some internal changes in preparation for Counter64 decoding.

2002 Apr 19: this documentation page revised, giving the recipes titles more descriptive of their function.

020414: In the default, -v, and -vv reports, if ethernet error counts are non-zero, they are included in the output, so that user-side network problems (such as duplex negotiation) can be diagnosed. In the -v and -vv reports, absent MAC addresses are no longer listed. Some helper batch files added to simplify use under the Windows GUI, and the delivery package changed to be a ZIP file.

020324: Added decoding for AT objects and some further IP, TCP, and UDP objects. Suppressed printing of newlines as the last significant character of octet-strings when rendered as display strings in the output for undecoded objects. Attempted automatic recognition of character strings used as indices inside OIDs.

2002 Feb 10: added documentation to this page on How to tell if your cable ISP has disabled SNMP.

011209: Added decoding for IP routes, ICMP, TCP, UDP, SNMP, dot1dBridge objects.

011208: Fixed problem with combination of -ubrip and -cmser on certain recent models of cable modem. Added the downstream and upstream IDs to the standard and -v verbose reports. Added to the -vv very-verbose report the private MIB walk for ELSA cable modems. Added option -tech to restore the OID index suffices normally suppressed for simplicity.

011014: Fixed bug causing SNMP response error status to be ignored if SNMP error index was zero (believed to finally fix bug previously thought fixed in 011007). Added upstream timing offset to the -v verbose report. Added to the -vv very-verbose report private MIB walks for Com21, Thomson Consumer Electronics (RCA), and Conexant chipset cable modems. Added decoding for the root (only) of the private MIBs for Cisco and Conexant. Added remark that 0.0dBmV receive power might mean that power measurement is not supported.

011007: Fixed bug causing DocsDiag to loop or give a Java Class Cast Exception upon receiving an SNMP error during a MIB walk. Added mini-slot transmission usage to the -v verbose report. Added options -nodecode and -walk for specialist use. Added decoding for further IfMIB objects.

010802: Suppressed error message SnmpConnection: response: wrong request id. Fixed a possible instability arising from SNMP reply runt packets. Added decoding for the LED on the Com21 DOXport DP1110.

010715: Added decoding of Ethernet and USB objects, finished decoding of BPI+ objects. Added the USB objects to the -vv report.

010714: Added option -netw to specify the length of the -ubrip search. Added decoding of ASN1 data types from their raw values to the normal SNMP usage.

010701: Added system up time to -v and -vv reports. Added decoding for some BPI+ objects.

010630: fixed a significant bug which (when run on the Windows platform) resulted in any of the bytes hex 81, 8D, 8E, 8F, 90, 9D, 9E being displayed as 3F in octet strings. This also affected use of -cmmac when verifying or searching for MAC addresses, as -cmmac was matching against an octet string. Added decoding for most Interface and IP properties, and a few Tailfin proprietary properties. Date & time added to reports for automatic time-stamping of pasted copies. Simple display of MAC and IP addresses added to the verbose reports.

010622: fixed the omission of testing six IP addresses with -ubrip. Added -community option.

010611: current version re-posted with internal version number in sync with this history.

010610: fixed bug with zero-length strings introduced in 010609. Extended the CMX recipe to suggest a method for those with Linksys routers between their PC and the CMX.

010609: added option -log to print the cable modem event log. Added decoding of docsDevFilter objects. Checked syntax of -cmmac parameter values. Extended this documentation page in respect of the CMX recipe.

010606: Fixed incomplete decoding of some CMX properties. Other minor changes. Otherwise most changes have been to this documentation page.

2001 June 4: version 010603 was re-posted with a modified JAR manifest to support usage under J2RE.

010603: added option -ubrip to search all local cable modems for a match with data provided. Added -cmser as an alternative to -cmmac for search and verification.

010602: deal with modems (such as the CMX) that support the old experimental docsDev MIB instead of the standard one. Add -vvv option for a full MIB walk. Increase timeouts from 500ms to 1000ms and repeat up to three attempts per SNMP request. Added transmit retry counters to the verbose -v report.

2001 May 31: version 010530 was remounted as a ZIP file instead of a JAR file, to work around this web server not having a correct MIME-type mapping for JAR files.

010530: added ability to use ISP-side private IP addresses, on condition that the user can show evidence of authority to access this private address by being able to quote the HFC MAC address of the cable modem, with the -cmmac parameter.

010529: first posted version, as a beta release for comment.


Acknowledgements

I acknowledge with thanks the JMGMT library by Sven Dörr.

Information sources

DOCSIS specifications from http://www.cablemodem.com/specifications.html.
RFC 2669 (DOCSIS Cable Device MIB) from http://www.ietf.org/rfc/rfc2669.txt.
RFC 2670 (DOCSIS RF Interface MIB) from http://www.ietf.org/rfc/rfc2670.txt.
RFC 3083 (DOCSIS Baseline Privacy Interface MIB) from http://www.ietf.org/rfc/rfc3083.txt.
IP over Cable Data Network Working Group Internet Drafts from http://www.ietf.org/html.charters/ipcdn-charter.html.


Feedback and Support

Please e-mail all feedback or support queries to: rdhw@cam.ac.uk

Before you e-mail me, check that your problem is not that your cable ISP has disabled use of SNMP: see How to tell if your cable ISP has disabled SNMP below.

If you e-mail me concerning failure of DocsDiag to find your cable modem, please include:

Back to my index.

How you can help



Recipe for use of DocsDiag with 3Com CMX

The 3Com CMX has no customer-side IP address, so we are forced to use the ISP-side private IP address, which can be specifically determined from the CMX log.

Refer to http://homepage.ntlworld.com/robin.d.h.walker/cmtips/macaddr.html#machfc for instructions on finding the HFC MAC address from the label on the modem.

Refer to http://homepage.ntlworld.com/robin.d.h.walker/cmtips/signal.html#cmxdiag for instructions on viewing the CMX log. (If you are unable to view the CMX log, then try the ISP-side recipe below instead, with the direct on-LAN route fix below). One of the entries in the CMX log is its own ISP-side private IP address:

DHCP -- DHCP process complete(DHCPACK received) 0xff
		
        Cable Modem IP Address          = 172.18.149.159
        Cable Modem Subnet Mask         = 255.255.252.0

Use the above information with DocsDiag as follows:

jview /cp docsdiag.jar docsdiag -cmip 172.18.149.159 -cmmac 00104B012345

where -cmip introduces the private IP address from the log (replace 172.18.149.159 with the address you discovered in the log) and -cmmac introduces the HFC MAC address from the label, without the group separators (replace 00104B012345 with the address from your label). If this command gives the error message "Host ... not responding" then try adding a direct on-LAN route to the network containing the cable modem IP address, as follows.

The direct on-LAN route fix for 3Com CMX cable modems

This will work only if the PC is directly connected to the cable modem, with no intervening router or firewall. Convert the CM IP address to its network base address as follows:

Then give the command (shown here in the syntax for Windows):

route add nnn.nnn.nnn.0 mask kkk.kkk.kkk.0 xxx.xxx.xxx.xxx

where xxx.xxx.xxx.xxx is the IP address of your own PC (see http://homepage.ntlworld.com/robin.d.h.walker/cmtips/ipaddr.html#ipaddr for how to find it), nnn.nnn.nnn.0 is the base address of the network containing your CM ISP-side IP address, as calculated above, and kkk.kkk.kkk.0 is the sub-net mask copied from the CMX log above (it might be 255.255.248.0 or 255.255.252.0). Other platforms will have their own syntax to achieve the same effect. You might now find that the docsdiag command line works. This fix is cable modem specific: it works with CMXs but not necessarily with any others.

For those with routers connected to their CMX cable modem, it might be possible to configure the router to create the direct route in an analogous way. Unfortunately, no way has yet been discovered of configuring the Linksys series routers to create a direct route on the WAN interface (please e-mail me with the recipe if you make it work with the CMX).


Recipe for use of DocsDiag with the ISP-side address of the cable modem

This recipe can be used with any brand of DOCSIS cable modem (unless the cable operator has prevented use of SNMP).

This ISP-side recipe will not work with cable modems in the ex-C&W regions of NTL.

This ISP-side recipe only works if the cable modem is online to the cable operator's network. If the cable modem has failed to connect to the network, try the customer-side recipe instead.

The advantage of the ISP-side recipe over the customer-side recipe is that the ISP-side recipe can be executed while your PC is in normal on-line service (even via a local NAT router), whereas the customer-side recipe requires the PC to be given a special static IP address, and to be connected directly to the cable modem, not via a router.

Before proceeding, you might need to disable or uninstall any firewall that you might have, if the firewall would interfere with SNMP traffic to/from private IP ranges.

Refer to http://homepage.ntlworld.com/robin.d.h.walker/cmtips.html#macreg for instructions on finding the HFC MAC address from the label on the modem.

Refer to http://homepage.ntlworld.com/robin.d.h.walker/cmtips/ipaddr.html#ubrip for instructions on how to do a traceroute to find the UBR's private IP address. For example, do a traceroute to anywhere, and note the IP address returned from the first hop:

C:\>tracert www.uu.net

Tracing route to www.uu.net [208.243.117.123]
over a maximum of 30 hops:

1    14 ms   <10 ms    14 ms  172.19.83.254
2    14 ms   <10 ms   <10 ms  ren-cam2-a-fa41.inet.ntl.com [62.252.131.69]
3   426 ms   494 ms    55 ms  ren-core-a-pos1000.inet.ntl.com [62.252.128.149]
4     *       27 ms    28 ms  win-bb-a-atm100-808.inet.ntl.com [62.253.187.130]
5   110 ms   110 ms   124 ms  mae-east-gw1-atm410-1.inet.ntl.com [194.168.118.238]
6   151 ms   138 ms   137 ms  902.Serial3-1-1.GW1.TCO1.ALTER.NET [157.130.33.57]
7   124 ms   124 ms   123 ms  717.GW1.TCO3.customer.ALTER.NET [157.130.32.206]
8   123 ms   138 ms   151 ms  uu123.web.uu.net [208.243.117.123]

If the IP address from the first hop is in the private range 10.xxx.xxx.xxx or 172.yy.xxx.xxx (where yy is in the range 16-31), then it will be the private IP address of the customer-facing interface of the UBR, which is the one we want: it will also be the gateway address for the ISP-side private IP addresses of all the cable modems connected to this UBR interface. If, instead, this line contains a normal public IP address (such as the default gateway address for your PC), then you will not be able to proceed directly with this recipe: but you might be able to use the packet-sniffer method below to discover the private IP address of the UBR.

To repeat: the -ubrip parameter normally requires a value which is a private IP address in the range 10.xxx.xxx.xxx or 172.yy.xxx.xxx, and it is unlikely to work with anything else.

Use the above information with DocsDiag as follows:

jview /cp docsdiag.jar docsdiag -ubrip 172.19.83.254 -cmmac 00E06F012345

where -ubrip introduces the IP address copied from the first hop of the traceroute (replace 172.19.83.254 with your value) and -cmmac introduces the HFC MAC address from the label, without the group separators (replace 00E06F012345 with your value). You may modify the length of the search with the -netw parameter. You may expect the search to take several minutes. Once this search has discovered your ISP-side IP address, it will tell you what the ISP-side address is, so that you can use it in future directly with -cmip, and you need not run this search again.

If the search fails after lines of unbroken dots, then maybe:

If the search fails after a mix of dots and Xs, then SNMP is working, but maybe:

Note for 3Com CMX owners: if you try this recipe with a 3Com CMX, it might need the same direct on-LAN route fix from the CMX recipe above, in order to get a response from your own cable modem. You can use the UBR address as the starting point from which to compute the base network address. For instance, in the above case, UBR address 172.19.83.254 leads to a network base address of 172.19.80.0 with mask 255.255.248.0. However, setting up the direct route will block communication with every other cable modem on the network, apart from your own CMX. So during the search, you will see rows of unbroken dots until it finds your own CMX. Be patient!

Using a packet-sniffer to ascertain DocsDiag parameters

If a traceroute does not reveal the private IP address of the UBR, then you might be able to discover the correct information from packet-sniffing. This is not the place for a packet-sniffing tutorial: this discussion will assume familiarity with the basics of packet-sniffing. Connect a packet sniffer to your cable modem, re-boot the cable modem, and watch the traffic seen coming from the cable network. You might see many ARP requests, which will not help you. You might see, at low frequency, a few BootP/DHCP replies (UDP from source port 67 broadcast to destination port 68). These will be of two types: those destined for customer PCs (no use to us) and those destined for cable modems themselves, which we want. The ones destined for cable modems themselves are distinguished by having data in the Boot File Name field of the BootP reply. In such a packet, you can then discover data as follows:

If you do not see any BootP/DHCP replies, look instead for any ARP replies (your network and cable modem might or might not permit these to pass through the modem). Search for an ARP reply that contains your own cable modem's HFC MAC address: in the packet you will discover the ISP-side IP address of your cable modem (as needed for -cmip) and the IP address of the UBR (as needed for -ubrip).


Recipe for use of DocsDiag with the customer-side address of the cable modem

This recipe works with any brand of DOCSIS cable modem that has SNMP active on the customer-side IP address of 192.168.100.1, unless the cable ISP has disabled SNMP. This recipe will not work for a 3Com CMX, as that does not have a customer side IP address.

Most cable modems should have SNMP active on the customer-side IP address of 192.168.100.1, and therefore ought to work with DocsDiag without the need for -cmip or -ubrip. But many brands of cable modem do not receive the requests from DocsDiag, because 192.168.100.1 is not on the same sub-net as the WAN IP address allocated to you by DHCP from your cable operator, so your PC routes the packets for 192.168.100.1 to the IP default gateway address (head-end UBR), where they get lost.

Some specific brands of cable modem (e.g. Motorola SURFboard, 3Com Tailfin) take special action to sniff passing traffic from the user's PC, and intercept packets addressed to 192.168.100.1, so they appear to do the right thing even when the rules of IP routing are broken, but even this magic fails unless those cable modems have successfully connected to the cable operator's network.

There are a number of ways of fixing this sub-net mismatch to make DocsDiag work, but as I don't have an example of this class of cable modem to play with, I shall have to make a few suggestions and hope that some cable-modem owners will let me know by e-mail which ones worked for them.

The advantage of the following methods over the ISP-side recipe is that the following methods should work even when the cable modem is not online to the cable operator's network. The disadvantage (of Method 1 at least) is that the PC has to be taken out of normal DHCP service to be given a special static IP address.

All the methods below require reconfiguration of the device connected directly to the cable modem. That device might be your PC (if you have no NAT router), or it might be a NAT router. I will refer below to the device, meaning whatever device is the one connected directly to the cable modem.

Method 1: For a temporary period, reconfigure the device so that it no longer uses DHCP to pick up a WAN address, and configure the device to have a static IP address in the same sub-net as the cable modem, for instance 192.168.100.xxx where xxx is in the range 2 to 254, with a sub-net mask of 255.255.255.0, and default gateway 192.168.100.1. Restart the device if necessary.

On your PC, open a command window, and try

ping 192.168.100.1

If the ping does not get a reply, then something is wrong, so double-check everything: re-boot cable modem, re-boot PC. If the ping worked, try DocsDiag without any parameters. This should now work. If ping works but DocsDiag doesn't, the most likely reason is that your cable ISP has disabled SNMP; see How to tell if your cable ISP has disabled SNMP.

After use of this method, you will need to reconfigure the device back into using DHCP (automatic) for IP and DNS settings in order to go back online to your cable operator's network.

If Method 1 did not get DocsDiag working, then Methods 2 and 3 won't work either.

Method 2: This has been reported to work with a Toshiba PCX 1100, and reported not to work with a PCX 1000. Please make your own trial. Reconfigure the IP routing tables of the device so as to create an additional direct on-LAN route to the cable modem address of 192.168.100.1.

If the device connected directly to the cable modem is your PC, then you can do this by opening a command window and giving the following command (shown in the syntax for Windows):

route add 192.168.100.1 mask 255.255.255.255 xxx.xxx.xxx.xxx

where xxx.xxx.xxx.xxx is the WAN IP address of the network interface connecting to the cable modem (not the gateway address) as allocated by DHCP from your cable ISP.

If the device connected directly to the cable modem is a NAT router, consult your router's user handbook for setting up routing tables on the WAN interface.

If DocsDiag now works, you will be able to run DocsDiag at any time during normal service.

Method 3: [for expert users only] If Method 1 works but Method 2 does not, you might be able to use the 192.168.100.1 address in normal service by assigning a secondary IP address to the WAN network interface of the device, the secondary address being in the same sub-net as the cable modem on 192.168.100.1, with the primary address being the one allocated by DHCP by your cable operator. Adding a secondary IP address to a single network interface is an example of multihoming. If the device is a Windows PC, the only way to add secondary IP addresses to a single adapter is by editing the registry, and it is non-trivial to find which registry entry is the one that corresponds to the adapter connected to the cable modem. With Linux and Macs, multihoming on a single adapter is somewhat easier.

Discovering and using the ISP-side addresses

Once you have DocsDiag working with the customer-side address, use DocsDiag with the verbose option -v. The output will include a list of addresses of the cable modem, like this:

MAC address.1                        = 002040701235
MAC address.2                        = 002040701234
IP address.172.16.229.150            = 172.16.229.105
IP address.192.168.100.1             = 192.168.100.1

The IP address that is neither 192.168.100.1 nor 127.0.0.1 will be the ISP-side private IP address, as shown above. The ISP-side private address should be of the form 10.xxx.xxx.xxx or 172.yy.xxx.xxx, where yy is in the range 16-31. The second MAC address shown will normally be the ISP-side HFC MAC address of the cable modem. So to use DocsDiag with the ISP-side, you could type:

jview /cp docsdiag.jar docsdiag -cmip 172.16.229.105 -cmmac 002040701234

where -cmip introduces the ISP-side IP address (replace 172.16.229.105 with your value), and -cmmac introduces the HFC MAC address of the cable modem (replace 002040701234 with your value). This technique will enable you to use DocsDiag when your PC is in a normal in-service configuration, and even if it is behind a NAT router.

Tip: If you are trying to use -cmser (in conjunction with -cmip or -ubrip) with a Toshiba cable modem, then note that the serial number required by -cmser for a Toshiba PCX is a ten-digit decimal number, without a hyphen or any trailing digits after the hyphen.


Recipe for use of DocsDiag with a generic cable modem

First, just try DocsDiag without any parameters:

jview /cp docsdiag.jar docsdiag

If the above works, then you have no need for the more complicated methods below. It should work this way with (please e-mail me with any updates to this list of models):

If you have so far not got DocsDiag working, then review the customer-side recipe above for some techniques for making the customer-side IP address work.

If you cannot discover the customer-side IP address, but you can discover the ISP-side IP address (see for instance the CMX recipe above), then use:

jview /cp docsdiag.jar docsdiag -cmip 172.18.148.159 -cmmac 00104B012345

where -cmip introduces the ISP-side IP address (replace 172.18.148.159 with your value) and -cmmac introduces the HFC MAC address of your cable modem, as a string of 12 hexadecimal characters (replace 00104B012345 with the value from the label of your cable modem: you may use hyphens, colons, or periods to separate the hexadecimal digits into groups as you wish). This should work unless your cable operator denies SNMP traffic.

If you have no means of discovering the ISP-side IP address, then disable any firewall and use:

jview /cp docsdiag.jar docsdiag -ubrip 172.19.83.254 -cmmac 00E06F012345

where -ubrip introduces the private IP address of your local UBR (replace 172.19.83.254 with your value), and -cmmac introduces the HFC MAC address of your cable modem (replace 00E06F012345 with your value). This method is described more fully in the ISP-side recipe above. This method should work unless your cable operator denies SNMP traffic, but it will only work when the cable modem is online to the cable operator's network. Once this search has discovered your ISP-side IP address, it will tell you what the ISP-side address is, so that you can use it in future with the -cmip method above, and you need not run the search again.



How to tell if your cable ISP has disabled SNMP

Before contacting me to query why you can't get any results from DocsDiag, or why the only messages you get from it are:

then please check first whether your ISP is blocking the use of SNMP, as follows (but do not try this with the 3Com CMX):

If it is your ISP that is disabling your use of SNMP, then there is nothing that I can do to help you. This issue is between you and your ISP.