Creating DOCSIS Cable modem configuration files

Creating DOCSIS Cable modem configuration files

http://www.cmtsinfo.net/index.php?howto=cm_config

1)Basics

First one must obtain a program to convert text config files to binary DOCSIS format.

A free, console program is found here. Install as usual, problems with compilation are to be expected.. (docsis program last update was in 2006).

Another program can be downloaded from here(Windows only). It supports GUI and tree like view.

2) Basic settings

Our first file will just allow network acces and limit download/upload speeds:

Main
{
  NetworkAccess 1;            /* enables packet forwarding */
  GlobalPrivacyEnable 0;      /* disables BPI(encryption) */
  UsServiceFlow               /* creates an upstream service flow */
  {
    UsServiceFlowRef 1;       /* SF number */
    QosParamSetType 7;        /* activates SF */
    TrafficPriority 3;        /* sets medium priority */
    MaxRateSustained 128000;  /* max upstream transfer rate - 128kb/s */
  }
  
  DsServiceFlow               /* creates an downstream service flow */
  {
    DsServiceFlowRef 2;       /* SF number */
    QosParamSetType 7;        /* activates SF */
    TrafficPriority 3;        /* sets medium priority */
    MaxRateSustained 1000000; /* max downstream transfer rate - 1Mb/s */
  }

}  

Reader's comment: Please note that Ds/UsServiceRef numbers must be unique in cable modem config. 
On Cisco CM with same Ds and UsServiceFlowRef will end up with reject(c) status.

3) Adding advanced parameters

This file includes DS frequency, US channel number, 1 classifier, 3 service flows and limits user devices connected to modem.

Main
{
    NetworkAccess 1;                   /* enables packet forwarding */
    GlobalPrivacyEnable 0;             /* disables BPI(encryption) */
    DownstreamFrequency 410000000;     /* sets DS frequency to 410MHz */
    UpstreamChannelId 3;               /* sets 3rd US channel */
    MaxCPE 3;                          /* allows max 3 user devices */
    CpeMacAddress 00:00:00:00:00:00;   /* device #1 MAC is 00:00... */
    CpeMacAddress 11:11:11:11:11:11;   /* device #2 MAC is 11:11... */
    
    DsPacketClass
    {
      ClassifierRef 2;                 /* Classifier number */
      ServiceFlowRef 4;                /* forwards packets using SF #4 */
      RulePriority 3;                  /* Low priority classifier */
      ActivationState 1;               /* enables classifier */
      IpPacketClassifier
      {
        IpTos 0x0808ff;                /* matches ToS 0x08 */
      }
    }
    
    UsServiceFlow
    {
      UsServiceFlowRef 1;              /* SF number */
      QosParamSetType 7;               /* activates SF */
      TrafficPriority 3;               /* sets medium priority */
      MaxRateSustained 128000;         /* max transfer rate - 128kb/s */
    }
    
    DsServiceFlow
    {
      DsServiceFlowRef 2;              /* SF number */
      QosParamSetType 7;               /* activates SF */
      TrafficPriority 3;               /* sets medium priority */
      MaxRateSustained 1000000;        /* max transfer rate - 1Mb/s */
    }
    
    DsServiceFlow
    {
      DsServiceFlowRef 4;              /* SF number */
      QosParamSetType 7;               /* activates SF */
      TrafficPriority 3;               /* sets medium priority */
      MaxRateSustained 2000000;        /* max transfer rate - 2Mb/s */
    }
}

4) Global Parameters explained

Name	Description	Values
NetworkAccess	Controlls whether modem forwards data between USB/Ethernet and RF interfaces	0 - forwarding disabled 1 - forwarding enabled
GlobalPrivacyEnable	Enables BPI(encryption on RF interface)	0 - disables BPI 1 - enables BPI
DownstreamFrequency	Specifies downstream channel frequency in Hz	Frequency in HZ
UpstreamChannelId	Specifies the upstream channel number for that downstream	Desired upstream channel number
MaxCPE	Number of MAC addresses(computers, network devices), that modem will learn and forward packets from. This includes managed switches, APs etc.	Number of such devices
CpeMacAddress	Specifies MAC address of a computer/device. Number of CpeMacAddress commands must be less or equal MaxCPE. Usefull when you don't want the modem to learn Access point's IP address	MAC address of one device
MaxClassifiers	Maximum number of admitted and active upstream classifiers, that modem is allowed to have
DocsisTwoEnable	Enables DOCSIS 2.0	0 - disabled, 1 - enabled
GenericTLV	Allows to enter TLVs unsupported by program	Sytnax: TlvCode XXX TlvLength X TlvValue 0xXX
SwUpgradeFilename	Specifies firmware filename on TFTP server.	"filename"
SwUpgradeServer	Specifies TFTP server IP address	IP address
SnmpMibObject	Specifies OID to set	Syntax: OID type value
SnmpWriteControl
MfgCVCData	Producers certificate used for firmware upgrade.	Must be used several times to represent whole certificate. Can specify 254 hex chars max at a time.
MtaConfigDelimiter

Note: to create Mfg CVC Data, take mfg cert and then:

  hexdump -v -e ' 2/1 "%02X" ' -n 254 cert.cer

The complete MfgCVCData option would be MfgCVCData 0xOUTPUT_FROM_ABOVE; 
To create next portion just skip first 254 chars with -s:

   hexdump -v -e ' 2/1 "%02X" ' -n 254 -s 254 cert.cer

Increase -s by 254 for next portions.

5)Service flow parameters explained

General SF parameters:

Name	Description	Values
QosParamSetType	Quality of Service Parameter Set Type. Describes whether service flow is: Provisioned, Admitted and Active. Bit0 - Provisioned flag, Bit1 - Admitted flag, Bit2 - Active flag. For a servce flow to be working all 3 bits must be set to 1. Binary 111 equals 7 deciminal.	7 - Active other - disabled
TrafficPriority	Sets priority for packets matching that service flow. CMTS should serve first SFs with higher priority.	0 - lowest (default) 7 - highest
MaxRateSustained	Maximal transfer speed in b/s.	Speed in b/s
MaxTrafficBurst	Specifies how much data can be sent in one burst.	Value in bytes
MinReservedRate	Minimal bandwidth reserverd for that service flow	Speed in b/s
MinResPacketSize	Used for calculating minreserved rate, when smaller packets are sent, size from this field is taken for calculations instead of actual packet size.	Size in bytes.
ActQosParamsTimeout	Specifies how long CMTS reserves resources for that(active) service flow.	Value in seconds.
AdmQosParamsTimeout	Specifies how long CMTS reserves resources for that(admitted) service flow.	Value in seconds.
ServiceClassName	Specifies service class which that servce flow is part of	"service_class_name"

Downstream specific parameters:

Name	Description	Values
DsServiceFlow	Creates downstream service flow	none
DsServiceFlowRef	Number of downstream service flow - must match ServiceFlowRef in packet clasifiers(if exists). Service flows with lowest numbers are taken as default - no classifiers needed there.	any number (1-65535)
MaxDsLatency	Sprecifies maximal time between reception of packet and forwarding it to RF interface on t-he CMTS	Value in micro seconds.

Upstream specific parameters:

Name	Description	Values
UsServiceFlow	Creates upstream service flow	none
UsServiceFlowRef	Number of upstream service flow - must match ServiceFlowRef in packet clasifiers(if exists). Service flows with lowest numbers are taken as default - no classifiers needed there.	any number (1-65535)
MaxConcatenatedBurst	Maximum data in bytes to be transmited in one concatenation burst	Size in bytes, default 1522
SchedulingType	Scheduling type to be used in service flow	2- Best effort, 3 - Non-Real-Time Polling, 4 - Real-Time Polling, 5 - Unsolicited Grant Service with Activity Detection, 6 - Unsolicited Grant Service
RequestOrTxPolicy	Request/Transmission Policy - specifies behaviour of a serice flow	There are 16 bits numbered from 15 to 0. Bit0 disables all cm opportunities, bit1 disables Priority Request multicast opportunities, bit2 disables Request/Data opportunities for Requests bit3 same for data, bit4 disables piggyback requests with data, bit5 disables concatenation, bit6 disables fragmentation, bit7 disables payload header suppression, bit8 enables droping of packets that do not fit in the Unsolicited Grant. Example: 0x000001ff; Size
IpTosOverwrite	Enables overwriting ToS values for matchin packets	New ToS=(Old Tos AND AA) OR OO,example: 0xAAOO

I've purposely omited information about other sheduling types: UGS, UGS with AD, non real-time polling, real-time polling.
Test revealed that they are only useful with VOIP and/or streaming video. One may use source ip or destination port based classifier to capture voip traffic and limit UP- and down-stream service flows to no more than 128k. Since its uselles for browsing the internet no one should exploit that SF. With streaming video destiantion IP of video server must be known because high speed, low latency connection is VERY likely to be exploited if unprotected properly. It might be good idea for voip to create separate IP address class for voip gateways and create best effort service flows with highest traffic priority. Adding MinReservedRate may give even better results.

6)Classifies

IP and port based classifier

UsPacketClass {
  ServiceFlowRef 3;
  ClassifierRef 11;
  RulePriority 68;
  ActivationState 1;
  IpPacketClassifier {          /* Matches: */
    IpSrcAddr 192.168.0.0;      /* source IPs from 192.168.0.0 */
    IpSrcMask 255.255.255.0;    /* to 192.168.0.255 */
    SrcPortStart 1024;          /* source ports from 1024 */
    SrcPortEnd 2000;            /* to 2000 */
    IpDstAddr 113.206.95.144;   /* destination IPs from 113.206.95.144 */
    IpDstMask 255.255.255.248;  /* to 113.206.95.151 */
    DstPortStart 80;            /* destination port 80 */
    DstPortEnd 80;
    IpProto 6;                  /* TCP protocol */
  }
}

MAC address based classifier

UsPacketClass {
  ServiceFlowRef 3;
  ClassifierRef 11;
  RulePriority 68;
  ActivationState 1;
  LLCPacketClassifier {         
    SrcMacAddress 00:11:22:33:44:55 /* Matches that MAC address  */
  }
}

General classifier parameters:

Name	Description	Values
DsPacketClass	Creates downstream classifier	none
UsPacketClass	Creates upstream classifier	none
ClassifierRef	Number of classifier, must be unique in config file	any number (1-255)
ServiceFlowRef	ServiceFlowRef - number of service flow, which is used if packets matches that classifier.	Number of existing SF
RulePriority	Specifies the priority for the classifier. Higher number - higher priority. Classifiers with higher priority are checked first.	any number (0-255)
ActivationState	Enables classfier	1 - enabled,0 - disabled?
DscAction	What to do with classifier when Dynamic Service Change Request is recived	0 - Add clasifier,1 - replace classifier, 2 - delete classifier

IP classifier parameters:

Name	Description	Values
IpPacketClassifier	Creates IP classifier match	none
IpTos	Matches ToS values	0xLLHHMM, where LL - low tos, HH -high tos, MM - tos mask. Matches packets, where LL >= (tos AND MM) <= HH.
IpSrcAddr	Matches source IP	IP address
IpSrcMask	Specifies source mask. Match = SrcIP AND SrcMask	IP address
IpDstAddr	Matches destination IP	IP address
IpDstMask	Specifies destination mask. Match = DstIP AND DstMask	IP address
SrcPortStart	Matches source ports staring from that value	0(default)-65535
SrcPortEnd	Matches source ports ending on that value	0-65535(default)
DstPortStart	Matches destination ports staring from that value	0(default) - 65535
DstPortEnd	Matches destination ports ending on that value	0-65535(default)
IpProto	Matches IP protocol	1 - ICMP, 6 - TCP, 17- UDP  256 - any, 257 - TCP+UDP, 0 - ignore this field

LLC classifier parameters:

Name	Description	Values
LLCPacketClassifier	Creates LLC(MAC) classifier match	none
DstMacAddress	Matches destination MAC	MAC address
SrcMacAddress	Matches source MAC	MAC address
EtherType	Matches ethertype	Ethertype in hex

802.1q classifier parameters:

Name	Description	Values
IEEE802Classifier	Creates 802.1P/Q classifier match	none
UserPriority	Matches priority field	0-7
VlanID	Matches vlan ID field	0-4095

IP, LLC and IEEE802 matches may be used together in one classifier.

7) SNMP parameters for use in docsis configuration files

SNMP v1 access table:

Allows read-only access for community string some_password from 192.168.0.1/24 coming only from RF interface of a CM.
.1 means that it's first entry - remember to change when adding more.

SnmpMibObject docsDevNmAccessStatus.1 Integer 4; /* createAndGo */
SnmpMibObject docsDevNmAccessIp.1 IPAddress 192.168.0.1 ;
SnmpMibObject docsDevNmAccessIpMask.1 IPAddress 255.255.255.0 ;
SnmpMibObject docsDevNmAccessControl.1 Integer 2; /* read */
SnmpMibObject docsDevNmAccessInterfaces.1 HexString 0x40;
SnmpMibObject docsDevNmAccessCommunity.1 String "some_password" ;

Nmaccess entries explained:

Name	Description	Values
docsDevNmAccessStatus	Configures row creation and it's activation	1 - active, 2 - inactive, 4 - create and activate, 5 - create and deactivate, 6 - delete. Stick wtih 4.
docsDevNmAccessIp	Specifies source IP of a SNMP query matching this rule.	IP address
docsDevNmAccessIpMask	Specifies source IP mask of a SNMP query matching this rule.	mask address
docsDevNmAccessControl	Specifies access privileges	2 - RO, 3 - RW, 4 - RO with traps, 5 - RW with traps, 6 - traps
docsDevNmAccessInterfaces	Specifies matching interface	0x40 - cable, 0x80 - ethernet, 0xC0,0x00 - both
docsDevNmAccessCommunity	Specifies the community string	"desired_community_string"

Firewall rule:

This firewall rule prevents users from sending mail using port 25(SMTP). 
Note that by setting docsDevFilterIpDefault to 2(drop) one can allow only selected traffic insted of droping it.

SnmpMibObject docsDevFilterIpControl.7 Integer 1; /* discard */
SnmpMibObject docsDevFilterIpIfIndex.7 Integer 0 ;
SnmpMibObject docsDevFilterIpDirection.7 Integer 3; /* both */
SnmpMibObject docsDevFilterIpBroadcast.7 Integer 2; /* false */
SnmpMibObject docsDevFilterIpSaddr.7 IPAddress 0.0.0.0 ;
SnmpMibObject docsDevFilterIpSmask.7 IPAddress 0.0.0.0 ;
SnmpMibObject docsDevFilterIpDaddr.7 IPAddress 0.0.0.0 ;
SnmpMibObject docsDevFilterIpDmask.7 IPAddress 0.0.0.0 ;
SnmpMibObject docsDevFilterIpProtocol.7 Integer 6 ;
SnmpMibObject docsDevFilterIpSourcePortLow.7 Integer 0 ;
SnmpMibObject docsDevFilterIpSourcePortHigh.7 Integer 65535 ;
SnmpMibObject docsDevFilterIpDestPortLow.7 Integer 25 ;
SnmpMibObject docsDevFilterIpDestPortHigh.7 Integer 25 ;
SnmpMibObject docsDevFilterIpStatus.7 Integer 4; /* createAndGo */

Notable parameters

Name	Description	Values
docsDevFilterIpControl	Discards or accepts the traffic	1 - discard, 2 - accept
docsDevFilterIpDirection	Specifies the direction of packet to match.	1 - incoming, 2 - outgoing, 3 - both directions
docsDevFilterIpBroadcast	Matches ONLY broadcast traffic.	1 - yes, 0 - no

Other:

Specifies maximal number of source IPs that modem is forwarding from Ethernet and USB interfaces. 
WARNING: Undesired operation on some modems - allows only 1 IP per MAC address. This may sound good but PCs get modem assigned(192.168.100.X) and windows private IPs all the time. Result: no network access.

SnmpMibObject docsDevCpeIpMax.0 Integer 3 ;

8) Other configuarion parameters

Currently other parameters are only listed. Will write descriptions when there's time.

Baseline Privacy, must be turned on by GlobalPrivacyEnable.

Name	Description	Values
SAMapWaitTimeout
SAMapMaxRetries
BaselinePrivacy	Specifies BPI options	none - tree
AuthTimeout
ReAuthTimeout
AuthGraceTime
ReKeyTimeout
TEKGraceTime
AuthRejectTimeout

SNMPv3 specific:

Name	Description	Values
SnmpV3Kickstart	Specifies SNMPv3 engine options	none - tree
SnmpV3SecurityName
SnmpV3MgrPublicNumber

Name	Description	Values
SnmpV3TrapReceiver	Specifies SNMPv3 traps settings	none - tree
SnmpV3TrapRxIP
SnmpV3TrapRxPort
SnmpV3TrapRxType
SnmpV3TrapRxTimeout
SnmpV3TrapRxRetries
SnmpV3TrapRxFilterOID
SnmpV3TrapRxSecurityName		"security_name"

PHS - Payload header supression:

Name	Description	Values
PHS	Specifies PHS options	none - tree
PHSClassifierRef
PHSClassifierId
PHSServiceFlowRef
PHSServiceFlowId
PHSField
PHSIndex
PHSMask
PHSSize
PHSVerify

Vendor specific:

Name	Description	Values
VendorSpecific	Specifies vendor specific options	none - tree
VendorIdentifier	Specifies vendor identifier	vendor id - 0xIIIIII

Modem Capabilities:

Everything shuld be enabled by default so use it only to disable things.

Name	Description	Values
ModemCapabilities	Starts the tree	none
ConcatenationSupport
ModemDocsisVersion
FragmentationSupport
PHSSupport
IGMPSupport
BaselinePrivacySupport
DownstreamSAIDSupport
UpstreamSIDSupport
DCCSupport
SubMgmtControl
SubMgmtFilters