CMTS info

Helpful linux and DOCSIS/CMTS howtos and tips

Creating DOCSIS Cable modem configuration files

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
NameDescriptionValues
NetworkAccessControlls whether modem forwards data between USB/Ethernet and RF interfaces 0 - forwarding disabled
1 - forwarding enabled
GlobalPrivacyEnableEnables BPI(encryption on RF interface)0 - disables BPI
1 - enables BPI
DownstreamFrequencySpecifies downstream channel frequency in HzFrequency in HZ
UpstreamChannelIdSpecifies the upstream channel number for that downstreamDesired upstream channel number
MaxCPENumber of MAC addresses(computers, network devices), that modem will learn and forward packets from. This includes managed switches, APs etc.Number of such devices
CpeMacAddressSpecifies 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 addressMAC address of one device
MaxClassifiersMaximum number of admitted and active upstream classifiers, that modem is allowed to have
DocsisTwoEnableEnables DOCSIS 2.00 - disabled, 1 - enabled
GenericTLVAllows to enter TLVs unsupported by programSytnax: TlvCode XXX TlvLength X TlvValue 0xXX
SwUpgradeFilenameSpecifies firmware filename on TFTP server."filename"
SwUpgradeServerSpecifies TFTP server IP addressIP address
SnmpMibObjectSpecifies OID to setSyntax: OID type value
SnmpWriteControl
MfgCVCDataProducers 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:

NameDescriptionValues
QosParamSetTypeQuality 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
TrafficPrioritySets priority for packets matching that service flow. CMTS should serve first SFs with higher priority. 0 - lowest (default)
7 - highest
MaxRateSustainedMaximal transfer speed in b/s. Speed in b/s
MaxTrafficBurstSpecifies how much data can be sent in one burst. Value in bytes
MinReservedRateMinimal bandwidth reserverd for that service flow Speed in b/s
MinResPacketSizeUsed 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.
ActQosParamsTimeoutSpecifies how long CMTS reserves resources for that(active) service flow.Value in seconds.
AdmQosParamsTimeoutSpecifies how long CMTS reserves resources for that(admitted) service flow.Value in seconds.
ServiceClassNameSpecifies service class which that servce flow is part of "service_class_name"

Downstream specific parameters:

NameDescriptionValues
DsServiceFlowCreates downstream service flow none
DsServiceFlowRefNumber 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)
MaxDsLatencySprecifies maximal time between reception of packet and forwarding it to RF interface on t-he CMTS Value in micro seconds.

Upstream specific parameters:

NameDescriptionValues
UsServiceFlowCreates upstream service flow none
UsServiceFlowRefNumber 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)
MaxConcatenatedBurstMaximum data in bytes to be transmited in one concatenation burst Size in bytes, default 1522
SchedulingTypeScheduling 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
RequestOrTxPolicyRequest/Transmission Policy - specifies behaviour of a serice flowThere 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
IpTosOverwriteEnables 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:

NameDescriptionValues
DsPacketClassCreates downstream classifier none
UsPacketClassCreates upstream classifier none
ClassifierRefNumber of classifier, must be unique in config file any number (1-255)
ServiceFlowRefServiceFlowRef - number of service flow, which is used if packets matches that classifier. Number of existing SF
RulePrioritySpecifies the priority for the classifier. Higher number - higher priority. Classifiers with higher priority are checked first. any number (0-255)
ActivationStateEnables classfier 1 - enabled,0 - disabled?
DscActionWhat to do with classifier when Dynamic Service Change Request is recived 0 - Add clasifier,1 - replace classifier, 2 - delete classifier

IP classifier parameters:

NameDescriptionValues
IpPacketClassifierCreates IP classifier match none
IpTosMatches ToS values 0xLLHHMM, where LL - low tos, HH -high tos, MM - tos mask. Matches packets, where LL >= (tos AND MM) <= HH.
IpSrcAddrMatches source IP IP address
IpSrcMaskSpecifies source mask. Match = SrcIP AND SrcMaskIP address
IpDstAddrMatches destination IP IP address
IpDstMaskSpecifies destination mask. Match = DstIP AND DstMask IP address
SrcPortStartMatches source ports staring from that value 0(default)-65535
SrcPortEndMatches source ports ending on that value 0-65535(default)
DstPortStartMatches destination ports staring from that value 0(default) - 65535
DstPortEndMatches destination ports ending on that value 0-65535(default)
IpProtoMatches IP protocol 1 - ICMP, 6 - TCP, 17- UDP
256 - any, 257 - TCP+UDP, 0 - ignore this field

LLC classifier parameters:

NameDescriptionValues
LLCPacketClassifierCreates LLC(MAC) classifier match none
DstMacAddressMatches destination MAC MAC address
SrcMacAddressMatches source MAC MAC address
EtherTypeMatches ethertype Ethertype in hex

802.1q classifier parameters:

NameDescriptionValues
IEEE802ClassifierCreates 802.1P/Q classifier match none
UserPriorityMatches priority field 0-7
VlanIDMatches 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:

NameDescriptionValues
docsDevNmAccessStatusConfigures row creation and it's activation1 - active, 2 - inactive, 4 - create and activate, 5 - create and deactivate, 6 - delete. Stick wtih 4.
docsDevNmAccessIpSpecifies source IP of a SNMP query matching this rule.IP address
docsDevNmAccessIpMaskSpecifies source IP mask of a SNMP query matching this rule.mask address
docsDevNmAccessControlSpecifies access privileges2 - RO, 3 - RW, 4 - RO with traps, 5 - RW with traps, 6 - traps
docsDevNmAccessInterfacesSpecifies matching interface0x40 - cable, 0x80 - ethernet, 0xC0,0x00 - both
docsDevNmAccessCommunitySpecifies 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

NameDescriptionValues
docsDevFilterIpControlDiscards or accepts the traffic1 - discard, 2 - accept
docsDevFilterIpDirectionSpecifies the direction of packet to match.1 - incoming, 2 - outgoing, 3 - both directions
docsDevFilterIpBroadcastMatches 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.

NameDescriptionValues
SAMapWaitTimeout
SAMapMaxRetries
BaselinePrivacySpecifies BPI options none - tree
AuthTimeout
ReAuthTimeout
AuthGraceTime
ReKeyTimeout
TEKGraceTime
AuthRejectTimeout

SNMPv3 specific:

NameDescriptionValues
SnmpV3KickstartSpecifies SNMPv3 engine options none - tree
SnmpV3SecurityName
SnmpV3MgrPublicNumber

NameDescriptionValues
SnmpV3TrapReceiverSpecifies SNMPv3 traps settings none - tree
SnmpV3TrapRxIP
SnmpV3TrapRxPort
SnmpV3TrapRxType
SnmpV3TrapRxTimeout
SnmpV3TrapRxRetries
SnmpV3TrapRxFilterOID
SnmpV3TrapRxSecurityName "security_name"

PHS - Payload header supression:

NameDescriptionValues
PHSSpecifies PHS options none - tree
PHSClassifierRef
PHSClassifierId
PHSServiceFlowRef
PHSServiceFlowId
PHSField
PHSIndex
PHSMask
PHSSize
PHSVerify

Vendor specific:

NameDescriptionValues
VendorSpecificSpecifies vendor specific options none - tree
VendorIdentifierSpecifies vendor identifier vendor id - 0xIIIIII

Modem Capabilities:

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

NameDescriptionValues
ModemCapabilitiesStarts the tree none
ConcatenationSupport
ModemDocsisVersion
FragmentationSupport
PHSSupport
IGMPSupport
BaselinePrivacySupport
DownstreamSAIDSupport
UpstreamSIDSupport
DCCSupport
SubMgmtControl
SubMgmtFilters

Template: designsbydarren.com on license
All trademarks belong to their respective owners. All materials presented here for informational purposes only.