INTERNET-DRAFT MCNS Cable Device MIB May 1998 Cable Device Management Information Base for MCNS compliant Cable Modems and Cable Modem Termination Systems draft-ietf-ipcdn-cable-device-mib-04.txt Fri May 22 17:39:15 PDT 1998 Guenter Roeck (editor) cisco Systems groeck@cisco.com Status of this Memo This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its Areas, and its Working Groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as a "work in progress". To view the entire list of current Internet-Drafts, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). Abstract This memo defines an experimental portion of the Management Information Base (MIB) for use with network management protocols in the Internet community. In particular, it defines a basic set of managed objects for SNMP-based management of MCNS compliant Cable Modems and Cable Modem Termination Systems. This memo specifies a MIB module in a manner that is compliant to the SNMPv2 SMI. The set of objects is consistent with the SNMP framework and existing SNMP standards. This memo does not specify a standard for the Internet community. This memo is a product of the IPCDN working group within the Internet Engineering Task Force. Comments are solicited and should be addressed to the working group's mailing list at ipcdn@terayon.com and/or the author. Expires November 1998 [Page 1] INTERNET-DRAFT MCNS Cable Device MIB May 1998 Table of Contents 1 The SNMPv2 Network Management Framework ......................... 3 2 Object Definitions .............................................. 3 3 Overview ........................................................ 4 3.1 Structure of the MIB .......................................... 4 3.2 Management requirements ....................................... 4 3.2.1 Handling of Software upgrades ............................... 4 3.2.2 Events and Traps ............................................ 5 3.2.3 Trap Throttling ............................................. 6 3.2.3.1 Trap rate throttling ...................................... 6 3.2.3.2 Limiting the trap rate .................................... 6 3.3 Protocol Filters .............................................. 6 4 Definitions ..................................................... 7 5 Acknowledgments ................................................. 31 6 References ...................................................... 31 7 Security Considerations ......................................... 31 8 Author's Address ................................................ 32 Expires November 1998 [Page 2] INTERNET-DRAFT MCNS Cable Device MIB May 1998 1. The SNMPv2 Network Management Framework The SNMPv2 Network Management Framework presently consists of three major components. They are: o the SMI, described in RFC 1902 [1] - the mechanisms used for describing and naming objects for the purpose of management. o the MIB-II, STD 17, RFC 1213 [2] - the core set of managed objects for the Internet suite of protocols. o the protocol, RFC 1157 [3] and/or RFC 1905 [4], - the protocol for accessing managed objects. The Framework permits new objects to be defined for the purpose of experimentation and evaluation. 2. Object Definitions Managed objects are accessed via a virtual information store, termed the Management Information Base or MIB. Objects in the MIB are defined using the subset of Abstract Syntax Notation One (ASN.1) defined in the SMI. In particular, each object type is named by an OBJECT IDENTIFIER, an administratively assigned name. The object type together with an object instance serves to uniquely identify a specific instantiation of the object. For human convenience, we often use a textual string, termed the descriptor, to refer to the object type. Expires November 1998 [Page 3] INTERNET-DRAFT MCNS Cable Device MIB May 1998 3. Overview This MIB provides a set of objects required for the management of MCNS compliant Cable Modems (CM) and Cable Modem Termination Systems (CMTS). The specification is derived from the MCNS Radio Frequency Interface specification [6]. 3.1. Structure of the MIB This MIB is structured in six groups: o The docsDevBase group extends the MIB-II 'system' group with objects needed for cable device system management. o The docsDevNmAccessGroup provides a minimum level of SNMP access security (see Section 3 of [8]). o The docsDevSoftware group provides information for network- downloadable software upgrades. o The docsDevServer group provides information about the progress of the interaction with various provisioning servers. o The docsDevEvent group provides control and logging for event reporting o The docsDevFilter group configures filters at link layer and IP layer for bridged data traffic. 3.2. Management requirements 3.2.1. Handling of Software upgrades The Cable Modem software upgrade process is documented in [6]. From a network management station, the operator: o sets docsDevSwServer to the address of the TFTP server for software upgrades o sets docsDevSwFilename to the file pathname of the software upgrade image o sets docsDevSwAdminStatus to upgrade-from-mgt One reason for the SNMP-initiated upgrade is to allow loading of a temporary software image (e.g., special diagnostic software) that differs from the software normally used on that device without changing the provisioning database. Expires November 1998 [Page 4] INTERNET-DRAFT MCNS Cable Device MIB May 1998 Note that software upgrades should not be accepted blindly by the cable device. The cable device may refuse an upgrade if: o The download is incomplete. o The file contents are incomplete or damaged. o The software is not intended for that hardware device (may include the case of a feature set that has not been purchased for this device). 3.2.2. Events and Traps This MIB provides control facilities for reporting events through syslog, traps, and nonvolatile logging. If events are reported through traps, the specified conventions must be followed. Other means of event reporting are outside the scope of this document. The definition and coding of events is vendor-specific. In deference to the network operator who must troubleshoot multi-vendor networks, the circumstances and meaning of each event should be reported as human- readable text. Vendors SHOULD provide time-of-day clocks in CMs to provide useful timestamping of events. For each vendor-specific event that is reportable via TRAP, the vendor must create an enterprise-specific trap definition. Trap definitions MUST include the event reason encoded as DisplayString and should be defined as: trapName NOTIFICATION-TYPE OBJECTS { ifIndex, eventReason, other useful objects } STATUS current DESCRIPTION "trap description" ::= Object Id Note that ifIndex is only included if the event or trap is interface related. The last digit of the trap OID for enterprise-specific traps must match docsDevEvId. For SNMPv1-capable Network Management systems, this is necessary to correlate the event type to the trap type. Many Network Management systems are only capable of trap filtering on an enterprise and single-last-digit basis. Expires November 1998 [Page 5] INTERNET-DRAFT MCNS Cable Device MIB May 1998 3.2.3. Trap Throttling The CM and CMTS MUST provide support for trap message throttling as described below. The network operator can employ message rate throttling or trap limiting by manipulating the appropriate MIB variables. 3.2.3.1. Trap rate throttling Network operators may employ either of two rate control methods. In the first method, the device ceases to send traps when the rate exceeds the specified maximum message rate. It resumes sending traps only if reactivated by a network management station request. In the second method, the device resumes sending traps when the rate falls below the specified maximum message rate. The network operator configures the specified maximum message rate by setting the measurement interval (in seconds), and the maximum number of traps to be transmitted within the measurement interval. The operator can query the operational throttling state (to determine whether traps are enabled or blocked by throttling) of the device, as well as query and set the administrative throttling state (to manage the rate control method) of the device. 3.2.3.2. Limiting the trap rate Network operators may wish to limit the number of traps sent by a device over a specified time period. The device ceases to send traps when the number of traps exceeds the specified threshold. It resumes sending traps only when the measurement interval has passed. The network operator defines the maximum number of traps he is willing to handle and sets the measurement interval to a large number (in hundredths of a second). For this case, the administrative throttling state is set to stop at threshold which is the maximum number of traps. See "Techniques for Managing Asynchronously Generated Alerts" [7] for further information. 3.3. Protocol Filters The Cable Device MIB provides objects for both LLC and IP protocol filters. The LLC protocol filter entries can be used to limit CM forwarding to a restricted set of network-layer protocols (such as IP, IPX, NetBIOS, and Appletalk). The IP protocol filter entries can be used to restrict upstream or downstream traffic based on source and destination IP addresses, transport-layer protocols (such as TCP, UDP, and ICMP), and source and destination TCP/UDP port numbers. Expires November 1998 [Page 6] INTERNET-DRAFT MCNS Cable Device MIB May 1998 4. Definitions DOCS-CABLE-DEVICE-MIB DEFINITIONS ::= BEGIN IMPORTS MODULE-IDENTITY, OBJECT-TYPE, BITS, IpAddress, Unsigned32, Integer32, Counter32, experimental FROM SNMPv2-SMI DisplayString, RowStatus, DateAndTime, TruthValue, TEXTUAL-CONVENTION FROM SNMPv2-TC OBJECT-GROUP, MODULE-COMPLIANCE FROM SNMPv2-CONF; -- InterfaceIndexOrZero -- FROM IF-MIB; docsDev MODULE-IDENTITY LAST-UPDATED "9805221716Z" -- May 22, 1998 ORGANIZATION "IETF IPCDN Working Group" CONTACT-INFO " Guenter Roeck Postal: cisco Systems 170 West Tasman Drive San Jose, CA 95134 U.S.A. Phone: +1 408 527 3143 E-mail: groeck@cisco.com" DESCRIPTION "This is the MIB Module for MCNS-compliant cable modems and cable-modem termination systems." ::= { experimental 83 } -- The following textual convention is from the -- Interfaces MIB draft. It should go away once this -- draft has been published as RFC. InterfaceIndexOrZero ::= TEXTUAL-CONVENTION DISPLAY-HINT "d" STATUS current DESCRIPTION "This textual convention is an extension of the Expires November 1998 [Page 7] INTERNET-DRAFT MCNS Cable Device MIB May 1998 InterfaceIndex convention. The latter defines a greater than zero value used to identify an interface or interface sub-layer in the managed system. This extension permits the additional value of zero. the value zero is object-specific and must therefore be defined as part of the description of any object which uses this syntax. Examples of the usage of zero might include situations where interface was unknown, or when none or all interfaces need to be referenced." SYNTAX Integer32 (0..2147483647) docsDevMIBObjects OBJECT IDENTIFIER ::= { docsDev 1 } docsDevBase OBJECT IDENTIFIER ::= { docsDevMIBObjects 1 } -- -- For the following object, there is no concept in the -- RFI specification corresponding to a backup CMTS. The -- enumeration is provided here in case someone is able -- to define such a role or device. -- docsDevRole OBJECT-TYPE SYNTAX INTEGER { cm(1), cmtsActive(2), cmtsBackup(3) } MAX-ACCESS read-only STATUS current DESCRIPTION "Defines the current role of this device." ::= { docsDevBase 1 } docsDevDateTime OBJECT-TYPE SYNTAX DateAndTime MAX-ACCESS read-write STATUS current DESCRIPTION "The date and time, with optional timezone information." ::= { docsDevBase 2 } docsDevResetNow OBJECT-TYPE SYNTAX TruthValue MAX-ACCESS read-write STATUS current DESCRIPTION "Setting this object to true(1) causes the device to reset. Reading this object always returns false(2)." ::= { docsDevBase 3 } docsDevSerialNumber OBJECT-TYPE SYNTAX DisplayString Expires November 1998 [Page 8] INTERNET-DRAFT MCNS Cable Device MIB May 1998 MAX-ACCESS read-only STATUS current DESCRIPTION "The manufacturer's serial number for this device." ::= { docsDevBase 4 } docsDevSTPControl OBJECT-TYPE SYNTAX INTEGER { stEnabled(1), noStFilterBpdu(2), noStPassBpdu(3) } MAX-ACCESS read-write STATUS current DESCRIPTION "This object controls operation of the spanning tree protocol (as distinguished from transparent bridging). If set to stEnabled(1) then the spanning tree protocol is enabled, subject to bridging constraints. If noStFilterBpdu(2), then spanning tree is not active, and Bridge PDUs received are discarded. If noStPassBpdu(3) then spanning tree is not active and Bridge PDUs are transparently forwarded. Note that a device need not implement all of these options, but that noStFilterBpdu(2) is required." ::= { docsDevBase 5 } -- -- The following table provides one level of security for access -- to the device by network management stations. -- Note that access is also constrained by the -- community strings and any vendor-specific security. -- docsDevNmAccessTable OBJECT-TYPE SYNTAX SEQUENCE OF DocsDevNmAccessEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "This table controls access to SNMP objects by network management stations. If the table is empty, access to SNMP objects is unrestricted." ::= { docsDevMIBObjects 2 } docsDevNmAccessEntry OBJECT-TYPE SYNTAX DocsDevNmAccessEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "Controls access to SNMP objects by a particular network management station. For each entry in this table, the contents are not readable unless the management station Expires November 1998 [Page 9] INTERNET-DRAFT MCNS Cable Device MIB May 1998 has read-write permission." INDEX { docsDevNmAccessIndex } ::= { docsDevNmAccessTable 1 } DocsDevNmAccessEntry ::= SEQUENCE { docsDevNmAccessIndex INTEGER, docsDevNmAccessIp IpAddress, docsDevNmAccessIpMask IpAddress, docsDevNmAccessCommunity DisplayString, docsDevNmAccessControl INTEGER, docsDevNmAccessInterfaces OCTET STRING, docsDevNmAccessStatus RowStatus } docsDevNmAccessIndex OBJECT-TYPE SYNTAX INTEGER (1..2147483647) MAX-ACCESS not-accessible STATUS current DESCRIPTION "Index used to order the application of access entries." ::= { docsDevNmAccessEntry 1 } docsDevNmAccessIp OBJECT-TYPE SYNTAX IpAddress MAX-ACCESS read-create STATUS current DESCRIPTION "The IP address (or subnet) of the network management station. The address 255.255.255.255 is defined to mean any NMS. If traps are enabled for this entry, then the value must be the address of a specific device." DEFVAL { 'ffffffff'h } ::= { docsDevNmAccessEntry 2 } docsDevNmAccessIpMask OBJECT-TYPE SYNTAX IpAddress MAX-ACCESS read-create STATUS current DESCRIPTION "The IP subnet mask of the network management stations. If traps are enabled for this entry, then the value must be 255.255.255.255." DEFVAL { 'ffffffff'h } ::= { docsDevNmAccessEntry 3 } docsDevNmAccessCommunity OBJECT-TYPE SYNTAX DisplayString MAX-ACCESS read-create STATUS current DESCRIPTION "The community string to be matched for access by this entry. If set to the null string then any community string Expires November 1998 [Page 10] INTERNET-DRAFT MCNS Cable Device MIB May 1998 will match." DEFVAL { "public" } ::= { docsDevNmAccessEntry 4 } docsDevNmAccessControl OBJECT-TYPE SYNTAX INTEGER { none(1), read(2), readWrite(3), roWithTraps(4), rwWithTraps(5), trapsOnly(6) } MAX-ACCESS read-create STATUS current DESCRIPTION "Specifies the type of access allowed to this NMS. Setting this object to none(1) causes the table entry to be destroyed. Read(2) allows access by 'get' and 'get-next' PDUs. ReadWrite(3) allows access by 'set' as well. RoWithtraps(4), rwWithTraps(5), and trapsOnly(6) control distribution of Trap PDUs transmitted by this device." DEFVAL { read } ::= { docsDevNmAccessEntry 5 } -- The syntax of the following object was copied from RFC1493, -- dot1dStaticAllowedToGoTo. docsDevNmAccessInterfaces OBJECT-TYPE SYNTAX OCTET STRING MAX-ACCESS read-create STATUS current DESCRIPTION "Specifies the set of interfaces from which requests from this NMS will be accepted. Each octet within the value of this object specifies a set of eight interfaces, with the first octet specifying ports 1 through 8, the second octet specifying interfaces 9 through 16, etc. Within each octet, the most significant bit represents the lowest numbered interface, and the least significant bit represents the highest numbered interface. Thus, each interface is represented by a single bit within the value of this object. If that bit has a value of '1' then that interface is included in the set. Note that entries in this table apply only to link-layer interfaces (e.g., Ethernet and CATV MAC). Upstream and downstream channel interfaces must not be specified." -- DEFVAL is the bitmask corresponding to all interfaces ::= { docsDevNmAccessEntry 6 } Expires November 1998 [Page 11] INTERNET-DRAFT MCNS Cable Device MIB May 1998 docsDevNmAccessStatus OBJECT-TYPE SYNTAX RowStatus MAX-ACCESS read-create STATUS current DESCRIPTION "Controls and reflects the status of rows in this table." ::= { docsDevNmAccessEntry 7 } -- -- Procedures for using the following group are described in section -- 3.2.1 -- docsDevSoftware OBJECT IDENTIFIER ::= { docsDevMIBObjects 3 } docsDevSwServer OBJECT-TYPE SYNTAX IpAddress MAX-ACCESS read-write STATUS current DESCRIPTION "The address of the TFTP server used for software upgrades." ::= { docsDevSoftware 1 } docsDevSwFilename OBJECT-TYPE SYNTAX DisplayString (SIZE (0..64)) MAX-ACCESS read-write STATUS current DESCRIPTION "The file name of the software image to be loaded into this device. Unless set via SNMP, this is the file name specified by the provisioning server that corresponds to the software version that is desired for this device. If unknown, the string '(unknown)' is returned." ::= { docsDevSoftware 2 } docsDevSwAdminStatus OBJECT-TYPE SYNTAX INTEGER { upgradeFromMgt(1), allowProvisioningUpgrade(2), ignoreProvisioningUpgrade(3) } MAX-ACCESS read-write STATUS current DESCRIPTION "If set to upgradeFromMgt(1), the device will initiate a TFTP software image download using docsDevSwFilename. After successfully receiving an image, the device will set its state to ignoreProvisioningUpgrade(3) and reboot. If the download process is interrupted by a reset or power failure, the device will load the previous image and, after re-initialization, continue to attempt loading the image specified in docsDevSwFilename. Expires November 1998 [Page 12] INTERNET-DRAFT MCNS Cable Device MIB May 1998 If set to allowProvisioningUpgrade(2), the device will use the software version information supplied by the provisioning server when next rebooting (this does not cause a reboot). When set to ignoreProvisioningUpgrade(3), the device will disregard software image upgrade information from the provisioning server. Note that reading this object can return upgradeFromMgt(1). This indicates that a software download is currently in progress, and that the device will reboot after successfully receiving an image." ::= { docsDevSoftware 3 } docsDevSwOperStatus OBJECT-TYPE SYNTAX INTEGER { inProgress(1), completeFromProvisioning(2), completeFromMgt(3), failed(4), other(5) } MAX-ACCESS read-only STATUS current DESCRIPTION "InProgress(1) indicates that a TFTP download is underway, either as a result of a version mismatch at provisioning or as a result of a upgradeFromMgt request. CompleteFromProvisioning(2) indicates that the last software upgrade was a result of version mismatch at provisioning. CompleteFromMgt(3) indicates that the last software upgrade was a result of setting docsDevSwAdminStatus to upgradeFromMgt. Failed(4) indicates that the last attempted download failed, ordinarily due to TFTP timeout." ::= { docsDevSoftware 4 } -- -- The following group describes server access and parameters used for -- initial provisioning and bootstrapping. -- docsDevServer OBJECT IDENTIFIER ::= { docsDevMIBObjects 4 } docsDevServerBootState OBJECT-TYPE SYNTAX INTEGER { operational(1), disabled(2), waitingForDhcpOffer(3), waitingForDhcpResponse(4), Expires November 1998 [Page 13] INTERNET-DRAFT MCNS Cable Device MIB May 1998 waitingForTimeServer(5), waitingForTftp(6), refusedByCmts(7), forwardingDenied(8), other(9), unknown(10) } MAX-ACCESS read-only STATUS current DESCRIPTION "If operational(1), the device has completed loading and processing of configuration parameters and the CMTS has completed the Registration exchange. If disabled(2) then the device was administratively disabled, possibly by being refused network access in the configuration file. If waitingForDhcpOffer(3) then a DHCP Discover has been transmitted and no offer has yet been received. If waitingForDhcpResponse(4) then a DHCP Request has been transmitted and no response has yet been received. If waitingForTimeServer(5) then a Time Request has been transmitted and no response has yet been received. If waitingForTftp(6) then a request to the TFTP parameter server has been made and no response received. If refusedByCmts(7) then the Registration Request/Response exchange with the CMTS failed. If forwardingDenied(8) then the registration process completed, but the network access option in the received configuration file prohibits forwarding. " ::= { docsDevServer 1 } docsDevServerDhcp OBJECT-TYPE SYNTAX IpAddress MAX-ACCESS read-only STATUS current DESCRIPTION "The IP address of the DHCP server that assigned an IP address to this device. Returns 0.0.0.0 if DHCP was not used for IP address assignment." ::= { docsDevServer 2 } docsDevServerTime OBJECT-TYPE SYNTAX IpAddress MAX-ACCESS read-only STATUS current DESCRIPTION "The IP address of the Time server (RFC-868)." ::= { docsDevServer 3 } docsDevServerTftp OBJECT-TYPE SYNTAX IpAddress MAX-ACCESS read-only Expires November 1998 [Page 14] INTERNET-DRAFT MCNS Cable Device MIB May 1998 STATUS current DESCRIPTION "The IP address of the TFTP server responsible for downloading provisioning and configuration parameters to this device." ::= { docsDevServer 4 } docsDevServerConfigFile OBJECT-TYPE SYNTAX DisplayString MAX-ACCESS read-only STATUS current DESCRIPTION "The name of the device configuration file read from the TFTP server." ::= { docsDevServer 5 } -- -- Event Reporting -- docsDevEvent OBJECT IDENTIFIER ::= { docsDevMIBObjects 5 } docsDevEvControl OBJECT-TYPE SYNTAX INTEGER { resetLog(1), useDefaultReporting(2) } MAX-ACCESS read-write STATUS current DESCRIPTION "Setting this object to resetLog(1) empties the event log. All data is deleted. Setting it to useDefaultReporting(2) returns all event priorities to their factory-default reporting. Reading this object always returns useDefaultReporting(2)." ::= { docsDevEvent 1 } docsDevEvSyslog OBJECT-TYPE SYNTAX IpAddress MAX-ACCESS read-write STATUS current DESCRIPTION "The IP address of the Syslog server. If 0.0.0.0, syslog transmission is inhibited." ::= { docsDevEvent 2 } docsDevEvThrottleAdminStatus OBJECT-TYPE SYNTAX INTEGER { unconstrained(1), maintainBelowThreshold(2), stopAtThreshold(3), inhibited(4) Expires November 1998 [Page 15] INTERNET-DRAFT MCNS Cable Device MIB May 1998 } MAX-ACCESS read-write STATUS current DESCRIPTION "Controls the transmission of traps and syslog messages with respect to the trap pacing threshold. unconstrained(1) causes traps and syslog messages to be transmitted without regard to the threshold settings. maintainBelowThreshold(2) causes trap transmission and syslog messages to be suppressed if the number of traps would otherwise exceed the threshold. stopAtThreshold(3) causes trap transmission to cease at the threshold, and not resume until directed to do so. inhibited(4) causes all trap transmission and syslog messages to be suppressed. A single event is always treated as a single event for threshold counting. That is, an event causing both a trap and a syslog message is still treated as a single event. Writing to this object resets the thresholding state." ::= { docsDevEvent 3 } docsDevEvThrottleInhibited OBJECT-TYPE SYNTAX TruthValue MAX-ACCESS read-only STATUS current DESCRIPTION "If true(1), trap and syslog transmission is currently inhibited due to thresholds and/or the current setting of docsDevEvThrottleAdminStatus." ::= { docsDevEvent 4 } docsDevEvThrottleThreshold OBJECT-TYPE SYNTAX Unsigned32 MAX-ACCESS read-write STATUS current DESCRIPTION "Number of trap/syslog events per docsDevEvThrottleInterval to be transmitted before throttling. A single event is always treated as a single event for threshold counting. That is, an event causing both a trap and a syslog message is still treated as a single event." ::= { docsDevEvent 5 } docsDevEvThrottleInterval OBJECT-TYPE SYNTAX INTEGER(1..2147483647) UNITS "seconds" MAX-ACCESS read-write STATUS current DESCRIPTION Expires November 1998 [Page 16] INTERNET-DRAFT MCNS Cable Device MIB May 1998 "The interval over which the trap threshold applies." ::= { docsDevEvent 6 } -- -- The following table controls the reporting of the various classes of -- events. For each event priority, -- a combination of logging and reporting mechanisms may be chosen. The -- mapping of event types -- to priorities is vendor-dependent. Vendors may also choose to allow -- the user to control that mapping -- through proprietary means. docsDevEvControlTable OBJECT-TYPE SYNTAX SEQUENCE OF DocsDevEvControlEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "Allows control of the reporting of event classes." ::= { docsDevEvent 7 } docsDevEvControlEntry OBJECT-TYPE SYNTAX DocsDevEvControlEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "Allows configuration of the reporting mechanisms for a particular event priority." INDEX { docsDevEvPriority } ::= { docsDevEvControlTable 1 } DocsDevEvControlEntry ::= SEQUENCE { docsDevEvPriority INTEGER, docsDevEvReporting BITS } docsDevEvPriority OBJECT-TYPE SYNTAX INTEGER { emergency(1), alert(2), critical(3), error(4), warning(5), notice(6), information(7), debug(8) } MAX-ACCESS not-accessible STATUS current DESCRIPTION "The priority level that is controlled by this entry." ::= { docsDevEvControlEntry 1 } Expires November 1998 [Page 17] INTERNET-DRAFT MCNS Cable Device MIB May 1998 docsDevEvReporting OBJECT-TYPE SYNTAX BITS { local(0), traps(1), syslog(2) } MAX-ACCESS read-write STATUS current DESCRIPTION "Defines the action to be taken on occurrence of this event class. Implementations may not necessarily support all options for all event classes, but at minimum must allow traps and syslogging to be disabled." ::= { docsDevEvControlEntry 2 } docsDevEventTable OBJECT-TYPE SYNTAX SEQUENCE OF DocsDevEventEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "Contains a log of network and device events that may be of interest in fault isolation and troubleshooting." ::= { docsDevEvent 8 } docsDevEventEntry OBJECT-TYPE SYNTAX DocsDevEventEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "Describes a network or device event that may be of interest in fault isolation and troubleshooting." INDEX { docsDevEvIndex } ::= { docsDevEventTable 1 } DocsDevEventEntry ::= SEQUENCE { docsDevEvIndex INTEGER, docsDevEvFirstTime DateAndTime, docsDevEvLastTime DateAndTime, docsDevEvCount Counter32, docsDevEvLevel INTEGER, docsDevEvId Unsigned32, docsDevEvText DisplayString } docsDevEvIndex OBJECT-TYPE SYNTAX INTEGER (1..2147483647) MAX-ACCESS not-accessible STATUS current DESCRIPTION "Provides relative ordering of the objects in the event log. This object will always increase except when (a) the log is reset via docsDevEvControl, Expires November 1998 [Page 18] INTERNET-DRAFT MCNS Cable Device MIB May 1998 (b) the device reboots and does not implement nonvolatile storage for this log, or (c) it reaches the value 2^31. The next entry for all the above cases is 1." ::= { docsDevEventEntry 1 } docsDevEvFirstTime OBJECT-TYPE SYNTAX DateAndTime MAX-ACCESS read-only STATUS current DESCRIPTION "The time that this entry was created." ::= { docsDevEventEntry 2 } docsDevEvLastTime OBJECT-TYPE SYNTAX DateAndTime MAX-ACCESS read-only STATUS current DESCRIPTION "If multiple events are reported via the same entry, the time that the last event for this entry occurred." ::= { docsDevEventEntry 3 } docsDevEvCount OBJECT-TYPE SYNTAX Counter32 MAX-ACCESS read-only STATUS current DESCRIPTION "The number of consecutive event instances reported by this entry." ::= { docsDevEventEntry 4 } docsDevEvLevel OBJECT-TYPE SYNTAX INTEGER { emergency(1), alert(2), critical(3), error(4), warning(5), notice(6), information(7), debug(8) } MAX-ACCESS read-only STATUS current DESCRIPTION "The priority level of this event." ::= { docsDevEventEntry 5 } -- -- Vendors will provide their own enumerations for the following. -- The interpretation of the enumeration is unambiguous for a -- particular value of the vendor's enterprise number in sysObjectID. Expires November 1998 [Page 19] INTERNET-DRAFT MCNS Cable Device MIB May 1998 -- docsDevEvId OBJECT-TYPE SYNTAX Unsigned32 MAX-ACCESS read-only STATUS current DESCRIPTION "For this product, uniquely identifies the type of event that is reported by this entry." ::= { docsDevEventEntry 6 } docsDevEvText OBJECT-TYPE SYNTAX DisplayString MAX-ACCESS read-only STATUS current DESCRIPTION "Provides a human-readable description of the event, including all relevant context (interface numbers, etc.)." ::= { docsDevEventEntry 7 } docsDevFilter OBJECT IDENTIFIER ::= { docsDevMIBObjects 6 } -- LLC filters can be defined on an inclusive or exclusive basis: CMs -- can be configured to forward only packets matching a set of layer -- three protocols, or to drop packets matching a set of layer three -- protocols. docsDevFilterLLCDefault OBJECT-TYPE SYNTAX INTEGER { discard(1), accept(2) } MAX-ACCESS read-write STATUS current DESCRIPTION "If set to discard(1), all packets not matching an LLC filter will be discarded. If set to accept(2), all packets not matching an LLC filter will be accepted for further processing (e.g., bridging)." ::= { docsDevFilter 1 } docsDevFilterLLCTable OBJECT-TYPE SYNTAX SEQUENCE OF DocsDevFilterLLCEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "A list of filters to apply to (bridged) LLC traffic, which forwards or drops packets on the basis of the layer three protocol type." ::= { docsDevFilter 2 } Expires November 1998 [Page 20] INTERNET-DRAFT MCNS Cable Device MIB May 1998 docsDevFilterLLCEntry OBJECT-TYPE SYNTAX DocsDevFilterLLCEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "Describes a single filter to apply to (bridged) LLC traffic received on a specified interface. " INDEX { docsDevFilterLLCIndex } ::= { docsDevFilterLLCTable 1 } DocsDevFilterLLCEntry ::= SEQUENCE { docsDevFilterLLCIndex INTEGER, docsDevFilterLLCStatus RowStatus, docsDevFilterLLCIfIndex InterfaceIndexOrZero, docsDevFilterLLCProtocolType INTEGER, docsDevFilterLLCProtocol INTEGER, docsDevFilterLLCMatches Counter32 } docsDevFilterLLCIndex OBJECT-TYPE SYNTAX INTEGER (1..2147483647) MAX-ACCESS not-accessible STATUS current DESCRIPTION "Index used for the identification of filters (note that LLC filter order is irrelevant)." ::= { docsDevFilterLLCEntry 1 } docsDevFilterLLCStatus OBJECT-TYPE SYNTAX RowStatus MAX-ACCESS read-create STATUS current DESCRIPTION "Controls and reflects the status of rows in this table." ::= { docsDevFilterLLCEntry 2} docsDevFilterLLCIfIndex OBJECT-TYPE SYNTAX InterfaceIndexOrZero MAX-ACCESS read-create STATUS current DESCRIPTION "The entry interface to which this filter applies. The value corresponds to ifIndex for either a CATV MAC or another network interface. If the value is zero, the filter applies to all interfaces. In Cable Modems, the default value is the customer side interface. In Cable Modem Termination Systems, this object has to be specified to create a row in this table." ::= { docsDevFilterLLCEntry 3 } docsDevFilterLLCProtocolType OBJECT-TYPE SYNTAX INTEGER { Expires November 1998 [Page 21] INTERNET-DRAFT MCNS Cable Device MIB May 1998 ethertype(1), dsap(2) } MAX-ACCESS read-create STATUS current DESCRIPTION "The format of the value in docsDevFilterLLCProtocol: either a two-byte Ethernet Ethertype, or a one-byte 802.2 SAP value. EtherType(1) also applies to SNAP- encapsulated frames." DEFVAL { ethertype } ::= { docsDevFilterLLCEntry 4 } docsDevFilterLLCProtocol OBJECT-TYPE SYNTAX INTEGER (0..65535) MAX-ACCESS read-create STATUS current DESCRIPTION "The layer three protocol for which this filter applies. The protocol value format depends on docsDevFilterLLCProtocolType. Note that for SNAP frames, etherType filtering is performed rather than DSAP=0xAA." DEFVAL { 0 } ::= { docsDevFilterLLCEntry 5 } docsDevFilterLLCMatches OBJECT-TYPE SYNTAX Counter32 MAX-ACCESS read-only STATUS current DESCRIPTION "Counts the number of times this filter was matched." ::= { docsDevFilterLLCEntry 6 } -- The default behavior for (bridged) packets that do not match IP -- filters is defined by -- docsDevFilterIpDefault. docsDevFilterIpDefault OBJECT-TYPE SYNTAX INTEGER { discard(1), accept(2) } MAX-ACCESS read-write STATUS current DESCRIPTION "If set to discard(1), all packets not matching an IP filter will be discarded. If set to accept(2), all packets not matching an IP filter will be accepted for further processing (e.g., bridging)." ::= { docsDevFilter 3 } docsDevFilterIpTable OBJECT-TYPE Expires November 1998 [Page 22] INTERNET-DRAFT MCNS Cable Device MIB May 1998 SYNTAX SEQUENCE OF DocsDevFilterIpEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "An ordered list of filters to apply to IP traffic. Filter application is ordered by the filter index, rather than by a best match algorithm. Packets which match no filters are discarded or forwarded according to the setting of docsDevFilterIpDefault." ::= { docsDevFilter 4 } docsDevFilterIpEntry OBJECT-TYPE SYNTAX DocsDevFilterIpEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "Describes a filter to apply to IP traffic received on a specified interface. Both source and destination addresses must match for the filter to apply." INDEX { docsDevFilterIpIndex } ::= { docsDevFilterIpTable 1 } DocsDevFilterIpEntry ::= SEQUENCE { docsDevFilterIpIndex INTEGER, docsDevFilterIpStatus RowStatus, docsDevFilterIpControl INTEGER, docsDevFilterIpIfIndex InterfaceIndexOrZero, docsDevFilterIpDirection INTEGER, docsDevFilterIpBroadcast TruthValue, docsDevFilterIpSaddr IpAddress, docsDevFilterIpSmask IpAddress, docsDevFilterIpDaddr IpAddress, docsDevFilterIpDmask IpAddress, docsDevFilterIpProtocol INTEGER, docsDevFilterIpSourcePortLow INTEGER, docsDevFilterIpSourcePortHigh INTEGER, docsDevFilterIpDestPortLow INTEGER, docsDevFilterIpDestPortHigh INTEGER, docsDevFilterIpMatches Counter32 } docsDevFilterIpIndex OBJECT-TYPE SYNTAX INTEGER (1..2147483647) MAX-ACCESS not-accessible STATUS current DESCRIPTION "Index used to order the application of filters. The filter with the lowest index is always applied first." ::= { docsDevFilterIpEntry 1 } docsDevFilterIpStatus OBJECT-TYPE Expires November 1998 [Page 23] INTERNET-DRAFT MCNS Cable Device MIB May 1998 SYNTAX RowStatus MAX-ACCESS read-create STATUS current DESCRIPTION "Controls and reflects the status of rows in this table." ::= { docsDevFilterIpEntry 2 } docsDevFilterIpControl OBJECT-TYPE SYNTAX INTEGER { discard(1), accept(2) } MAX-ACCESS read-create STATUS current DESCRIPTION "If set to discard(1), all packets matching this filter will be discarded and scanning of the remainder of the filter list will be aborted. If set to accept(2), all packets matching this filter will be accepted for further processing (e.g., bridging) and scanning of the remainder of the filter list will be aborted. " DEFVAL { discard } ::= { docsDevFilterIpEntry 3 } docsDevFilterIpIfIndex OBJECT-TYPE SYNTAX InterfaceIndexOrZero MAX-ACCESS read-create STATUS current DESCRIPTION "The entry interface to which this filter applies. The value corresponds to ifIndex for either a CATV MAC or another network interface. If the value is zero, the filter applies to all interfaces. Default value in Cable Modems is the customer-side interface. In Cable Modem Termination Systems, this object has to be specified to create a row in this table." ::= { docsDevFilterIpEntry 4 } docsDevFilterIpDirection OBJECT-TYPE SYNTAX INTEGER { inbound(1), outbound(2), both(3) } MAX-ACCESS read-create STATUS current DESCRIPTION "Determines whether the filter is applied to inbound(1) traffic, outbound(2) traffic, or traffic in both(3) directions." DEFVAL { inbound } ::= { docsDevFilterIpEntry 5 } Expires November 1998 [Page 24] INTERNET-DRAFT MCNS Cable Device MIB May 1998 docsDevFilterIpBroadcast OBJECT-TYPE SYNTAX TruthValue MAX-ACCESS read-create STATUS current DESCRIPTION "If set to true(1), the filter only applies to multicast and broadcast traffic. If set to false(2), the filter applies to all traffic." DEFVAL { false } ::= { docsDevFilterIpEntry 6 } docsDevFilterIpSaddr OBJECT-TYPE SYNTAX IpAddress MAX-ACCESS read-create STATUS current DESCRIPTION "The source IP address, or portion thereof, that is to be matched for this filter." DEFVAL { '00000000'h } ::= { docsDevFilterIpEntry 7 } docsDevFilterIpSmask OBJECT-TYPE SYNTAX IpAddress MAX-ACCESS read-create STATUS current DESCRIPTION "A bit mask that is to be applied to the source address prior to matching. This mask is not necessarily the same as a subnet mask, but 1's bits must be leftmost and contiguous." DEFVAL { '00000000'h } ::= { docsDevFilterIpEntry 8 } docsDevFilterIpDaddr OBJECT-TYPE SYNTAX IpAddress MAX-ACCESS read-create STATUS current DESCRIPTION "The destination IP address, or portion thereof, that is to be matched for this filter " DEFVAL { '00000000'h } ::= { docsDevFilterIpEntry 9 } docsDevFilterIpDmask OBJECT-TYPE SYNTAX IpAddress MAX-ACCESS read-create STATUS current DESCRIPTION "A bit mask that is to be applied to the destination address prior to matching. This mask is not necessarily the same as a subnet mask, but 1's bits must be leftmost and contiguous " Expires November 1998 [Page 25] INTERNET-DRAFT MCNS Cable Device MIB May 1998 DEFVAL { '00000000'h } ::= { docsDevFilterIpEntry 10 } docsDevFilterIpProtocol OBJECT-TYPE SYNTAX INTEGER { icmp(1), tcp(6), udp(17), any(256) } MAX-ACCESS read-create STATUS current DESCRIPTION "The IP protocol value that is to be matched." DEFVAL { any } ::= { docsDevFilterIpEntry 11 } docsDevFilterIpSourcePortLow OBJECT-TYPE SYNTAX INTEGER (0..65535) MAX-ACCESS read-create STATUS current DESCRIPTION "If docsDevFilterIpProtocol is udp or tcp, this is the inclusive lower bound of the transport-layer source port range that is to be matched." DEFVAL { 0 } ::= { docsDevFilterIpEntry 12 } docsDevFilterIpSourcePortHigh OBJECT-TYPE SYNTAX INTEGER (0..65535) MAX-ACCESS read-create STATUS current DESCRIPTION "If docsDevFilterIpProtocol is udp or tcp, this is the inclusive upper bound of the transport-layer source port range that is to be matched." DEFVAL { 65535 } ::= { docsDevFilterIpEntry 13 } docsDevFilterIpDestPortLow OBJECT-TYPE SYNTAX INTEGER (0..65535) MAX-ACCESS read-create STATUS current DESCRIPTION "If docsDevFilterIpProtocol is udp or tcp, this is the inclusive lower bound of the transport-layer destination port range that is to be matched." DEFVAL { 0 } ::= { docsDevFilterIpEntry 14 } docsDevFilterIpDestPortHigh OBJECT-TYPE SYNTAX INTEGER (0..65535) Expires November 1998 [Page 26] INTERNET-DRAFT MCNS Cable Device MIB May 1998 MAX-ACCESS read-create STATUS current DESCRIPTION "If docsDevFilterIpProtocol is udp or tcp, this is the inclusive upper bound of the transport-layer destination port range that is to be matched." DEFVAL { 65535 } ::= { docsDevFilterIpEntry 15 } docsDevFilterIpMatches OBJECT-TYPE SYNTAX Counter32 MAX-ACCESS read-only STATUS current DESCRIPTION "Counts the number of times this filter was matched." ::= { docsDevFilterIpEntry 16 } -- -- Placeholder for notifications/traps. -- docsDevNotification OBJECT IDENTIFIER ::= { docsDev 2 } -- -- Conformance definitions -- docsDevConformance OBJECT IDENTIFIER ::= { docsDev 3 } docsDevGroups OBJECT IDENTIFIER ::= { docsDevConformance 1 } docsDevCompliances OBJECT IDENTIFIER ::= { docsDevConformance 2 } docsDevBasicCompliance MODULE-COMPLIANCE STATUS current DESCRIPTION "The compliance statement for MCNS Cable Modems and Cable Modem Termination Systems." MODULE -- docsDev -- conditionally mandatory groups GROUP docsDevBaseGroup DESCRIPTION "Mandatory in Cable Modems, optional in Cable Modem Termination Systems." GROUP docsDevEventGroup DESCRIPTION "Mandatory in Cable Modems, optional in Cable Modem Termination Systems." GROUP docsDevFilterGroup DESCRIPTION Expires November 1998 [Page 27] INTERNET-DRAFT MCNS Cable Device MIB May 1998 "Mandatory in Cable Modems, optional in Cable Modem Termination Systems." GROUP docsDevNmAccessGroup DESCRIPTION "Mandatory in Cable Modems, optional in Cable Modem Termination Systems." GROUP docsDevServerGroup DESCRIPTION "This group is implemented only in Cable Modems, not in Cable Modem Termination Systems." GROUP docsDevSoftwareGroup DESCRIPTION "Mandatory in Cable Modems, optional in Cable Modem Termination Systems." OBJECT docsDevSTPControl MIN-ACCESS read-only DESCRIPTION "It is compliant to implement this object as read-only. Devices need only support noStFilterBpdu(2)." OBJECT docsDevEvReporting MIN-ACCESS read-only DESCRIPTION "It is compliant to implement this object as read-only. Devices need only support local(0)." ::= { docsDevCompliances 1 } docsDevBaseGroup OBJECT-GROUP OBJECTS { docsDevRole, docsDevDateTime, docsDevResetNow, docsDevSerialNumber, docsDevSTPControl } STATUS current DESCRIPTION "A collection of objects providing device status and control." ::= { docsDevGroups 1 } docsDevNmAccessGroup OBJECT-GROUP OBJECTS { docsDevNmAccessIp, docsDevNmAccessIpMask, docsDevNmAccessCommunity, docsDevNmAccessControl, Expires November 1998 [Page 28] INTERNET-DRAFT MCNS Cable Device MIB May 1998 docsDevNmAccessInterfaces, docsDevNmAccessStatus } STATUS current DESCRIPTION "A collection of objects for controlling access to SNMP objects." ::= { docsDevGroups 2 } docsDevSoftwareGroup OBJECT-GROUP OBJECTS { docsDevSwServer, docsDevSwFilename, docsDevSwAdminStatus, docsDevSwOperStatus } STATUS current DESCRIPTION "A collection of objects for controlling software downloads." ::= { docsDevGroups 3 } docsDevServerGroup OBJECT-GROUP OBJECTS { docsDevServerBootState, docsDevServerDhcp, docsDevServerTime, docsDevServerTftp, docsDevServerConfigFile } STATUS current DESCRIPTION "A collection of objects providing status about server provisioning." ::= { docsDevGroups 4 } docsDevEventGroup OBJECT-GROUP OBJECTS { docsDevEvControl, docsDevEvSyslog, docsDevEvThrottleAdminStatus, docsDevEvThrottleInhibited, docsDevEvThrottleThreshold, docsDevEvThrottleInterval, docsDevEvReporting, docsDevEvFirstTime, docsDevEvLastTime, docsDevEvCount, docsDevEvLevel, docsDevEvId, docsDevEvText } Expires November 1998 [Page 29] INTERNET-DRAFT MCNS Cable Device MIB May 1998 STATUS current DESCRIPTION "A collection of objects used to control and monitor events." ::= { docsDevGroups 5 } docsDevFilterGroup OBJECT-GROUP OBJECTS { docsDevFilterLLCDefault, docsDevFilterIpDefault, docsDevFilterLLCStatus, docsDevFilterLLCIfIndex, docsDevFilterLLCProtocolType, docsDevFilterLLCProtocol, docsDevFilterLLCMatches, docsDevFilterIpControl, docsDevFilterIpIfIndex, docsDevFilterIpStatus, docsDevFilterIpDirection, docsDevFilterIpBroadcast, docsDevFilterIpSaddr, docsDevFilterIpSmask, docsDevFilterIpDaddr, docsDevFilterIpDmask, docsDevFilterIpProtocol, docsDevFilterIpSourcePortLow, docsDevFilterIpSourcePortHigh, docsDevFilterIpDestPortLow, docsDevFilterIpDestPortHigh, docsDevFilterIpMatches } STATUS current DESCRIPTION "A collection of objects to specify filters at link layer and IP layer." ::= { docsDevGroups 6 } END Expires November 1998 [Page 30] INTERNET-DRAFT MCNS Cable Device MIB May 1998 5. Acknowledgments This document was produced by the IPCDN Working Group. It is based on a document written by Pam Anderson from CableLabs, Wilson Sawyer from BayNetworks, and Rich Woundy from Continental Cablevision. Special thanks is also due to Azlina Palmer, who helped a lot reviewing the document. 6. References [1] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, "Structure of Management Information for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1902, January 1996. [2] McCloghrie, K., and M. Rose, Editors, "Management Information Base for Network Management of TCP/IP-based internets: MIB-II", STD 17, RFC 1213, Hughes LAN Systems, Performance Systems International, March 1991. [3] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "A Simple Network Management Protocol (SNMP)", STD 15, RFC 1157, SNMP Research, Performance Systems International, MIT Lab for Computer Science, May 1990. [4] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M. and S. Waldbusser, "Protocol Operations for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1905, January 1996. [5] McCloghrie, K. and F. Kastenholz, "Evolution of the Interfaces Group of MIB-II", RFC 1573, Hughes LAN Systems, FTP Software, January 1994. [6] "MCNS Data Over Cable Services Cable Modem Radio Frequency Interface Specification SP-RFID01-970326", MCNS, March 1997. [7] L. Steinberg, "Techniques for Managing Asynchronously Generated Alerts", RFC 1224, May 1991. [8] "MCNS Data Over Cable Services Operations Support System Interface Specification SP-OSSII01-970403", MCNS, March 1997. 7. Security Considerations The docsDevNmAccessTable limits network management station access to devices implementing this MIB, thus providing protection against configuration changes imposed by unauthorized network management stations. Expires November 1998 [Page 31] INTERNET-DRAFT MCNS Cable Device MIB May 1998 It should be noted, however, that this protextion does not prevent unauthorized access by using wrong IP source address information. Also, it should be noted that depending of the SNMP version in use the SNMP data packets may be transmitted unencrypted. Dealing with this kind of security problems is outside the scope of this specification. 8. Author's Address Guenter Roeck cisco Systems 170 West Tasman Drive San Jose, CA 95134 U.S.A. Phone: +1 408 527 3143 Email: groeck@cisco.com Expires November 1998 [Page 32]