IPCDN Working Group Doug Jones INTERNET-DRAFT YAS Broadband Expires April 2003 October, 2002 Cable Gateway Remote Diagnostic Tools MIB Cable Gateway Device Management Information Base for CableHome Compliant WAN Gateway Devices draft-jones-cable-gateway-tools-mib-00 Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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 "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Copyright Notice Copyright (C) The Internet Society (1999). All Rights Reserved. Abstract This memo defines a 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 CableHome compliant WAN Gateway Devices and home routers. Specifically, this MIB defines managed objects for both a connection speed tool and an ICMP "ping" tool between the Gateway and devices on the LAN. This memo specifies a MIB module in a manner that is compliant to the SNMP SMIv2. The set of objects is consistent with the SNMP framework and existing SNMP standards. Jones Expires March 2003 [Page 1] Internet Draft Cable Gateway Device MIB October 2002 This memo is a submission to 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@ietf.org and/or the editor. Table of Contents 1 The SNMP Management Framework ................................... 2 2 Glossary ........................................................ 3 2.1 CATV .......................................................... 3 2.2 Cable Gateway Device .......................................... 3 2.3 Portal Services ............................................... 4 3 Overview ........................................................ 4 3.1 Structure of the MIB .......................................... 4 3.2 Management requirements ....................................... 4 4 Definitions ..................................................... 5 5 Acknowledgments ................................................ 12 6 References ..................................................... 12 7 Security Considerations ........................................ 12 8 Intellectual Property .......................................... 12 9 Author's Address ............................................... 13 10 Full Copyright Statement ...................................... 13 1. The SNMP Management Framework The SNMP Management Framework presently consists of five major components: o An overall architecture, described in RFC 2571 [1]. o Mechanisms for describing and naming objects and events for the purpose of management. The first version of this Structure of Management Information (SMI) is called SMIv1 and described in STD 16, RFC 1155 [2], STD 16, RFC 1212 [3] and RFC 1215 [4]. The second version, called SMIv2, is described in STD 58, RFC 2578 [5], STD 58, RFC 2579 [6] and STD 58, RFC 2580 [7]. o Message protocols for transferring management information. The first version of the SNMP message protocol is called SNMPv1 and described in STD 15, RFC 1157 [8]. A second version of the SNMP message protocol, which is not an Internet standards track protocol, is called SNMPv2c and described in RFC 1901 [9] and RFC Jones Expires March 2003 [Page 2] Internet Draft Cable Gateway Device MIB October 2002 1906 [10]. The third version of the message protocol is called SNMPv3 and described in RFC 1906 [10], RFC 2572 [11] and RFC 2574 [12]. o Protocol operations for accessing management information. The first set of protocol operations and associated PDU formats is described in STD 15, RFC 1157 [8]. A second set of protocol operations and associated PDU formats is described in RFC 1905 [13]. o A set of fundamental applications described in RFC 2573 [14] and the view-based access control mechanism described in RFC 2575 [15]. Managed objects are accessed via a virtual information store, termed the Management Information Base or MIB. Objects in the MIB are defined using the mechanisms defined in the SMI. This memo specifies a MIB module that is compliant to the SMIv2. A MIB conforming to the SMIv1 can be produced through the appropriate translations. The resulting translated MIB must be semantically equivalent, except where objects or events are omitted because no translation is possible (use of Counter64). Some machine readable information in SMIv2 will be converted into textual descriptions in SMIv1 during the translation process. However, this loss of machine readable information is not considered to change the semantics of the MIB. 2. Glossary The terms in this document are derived either from normal cable system usage, or from the documents associated with CableLabs' CableHome specification process. 2.1. CATV Originally "Community Antenna Television", now used to refer to any cable or hybrid fiber and cable system used to deliver video signals to a community. 2.2 Cable Gateway Device A cable gateway device passes data traffic between the cable operator's broadband data network (the Wide Area Network, WAN) and the Local Area Network (LAN) in the cable data service subscriber's residence or business. In addition to passing traffic between the WAN and LAN, the cable gateway device provides several services including a DHCP client and a DHCP server [RFC2131], a TFTP server [RFC1350], management services as enabled by SNMPv1/v2c/v3 agent compliant with the RFCs listed in Section 1, and security services including stateful packet inspection firewall functionality and software code image verification techniques. Jones Expires March 2003 [Page 3] Internet Draft Cable Gateway Device MIB October 2002 2.3 Portal Services A logical element aggregating the set of CableHome-specified functionality in a CableHome compliant cable gateway device. 3. Overview This MIB provides a set of objects required for the management of CableHome compliant residential gateway devices. The MIB is derived from the CableHome 1.0 specification [1]. Please note that the CableHome 1.0 specification requires residential gateways to implement SNMPv1, SNMPv2c, and SNMPv3 and to process IPv4 customer traffic. Design choices in this MIB reflect those requirements. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2129 [2]. 3.1. Structure of the MIB This MIB is structured into two groups: o The cabhCtpConnSpeed group contains objects needed to test the connection speed between the Gateway and a LAN device. o The cabhCtpPing Group provides objects allowing the manager to send an ICMP ping from the Gateway to a LAN device. 3.2 Management requirements In addition to the explicit requirements in this specification, the Cable Gateway MUST support all applicable CableHome and IETF requirements and MIB objects. Jones Expires March 2003 [Page 4] Internet Draft Cable Gateway Device MIB October 2002 4. Definitions CABH-CTP-MIB DEFINITIONS ::= BEGIN IMPORTS MODULE-IDENTITY, OBJECT-TYPE FROM SNMPv2-SMI TruthValue FROM SNMPv2-TC OBJECT-GROUP, MODULE-COMPLIANCE FROM SNMPv2-CONF InetAddressType, InetAddress FROM INET-ADDRESS-MIB clabProjCableHome FROM CLAB-DEF-MIB; --============================================================================ -- -- History: -- -- Date Modified by Reason -- 04/05/02 Issued I01 -- 09/20/02 Issued I02 -- 10/25/02 IETF I-D revisions -00 -- --============================================================================= cabhCtpMib MODULE-IDENTITY LAST-UPDATED "200210250000Z" -- October 25, 2002 ORGANIZATION "CableLabs Broadband Access Department" CONTACT-INFO "Kevin Luehrs Postal: Cable Television Laboratories, Inc. 400 Centennial Parkway Louisville, Colorado 80027-1266 U.S.A. Phone: +1 303-661-9100 Fax: +1 303-661-9199 E-mail: k.luehrs@cablelabs.com" DESCRIPTION "This MIB module defines the diagnostic controls offered by the CableHome Test Portal (CTP)." ::= { clabProjCableHome 5 } -- Textual conventions cabhCtpObjects OBJECT IDENTIFIER ::= { cabhCtpMib 1 } cabhCtpBase OBJECT IDENTIFIER ::= { cabhCtpObjects 1 } cabhCtpConnSpeed OBJECT IDENTIFIER ::= { cabhCtpObjects 2 } cabhCtpPing OBJECT IDENTIFIER ::= { cabhCtpObjects 3 } -- -- The following group describes the base objects in the Cable Home -- Management Portal. -- cabhCtpSetToFactory OBJECT-TYPE SYNTAX TruthValue MAX-ACCESS read-write STATUS current DESCRIPTION "Setting this object to true(1) causes all the tables in the CTP MIB to be cleared, and all CTP MIB objects with default values set back to those default values. Reading this object always returns false(2)." ::={cabhCtpBase 1} -- -- Parameter and results from Connection Speed Command -- cabhCtpConnSrcIpType OBJECT-TYPE SYNTAX InetAddressType MAX-ACCESS read-write STATUS current DESCRIPTION "The IP Address type used as the source address for the Connection Speed Test." DEFVAL { ipv4 } ::= { cabhCtpConnSpeed 1 } cabhCtpConnSrcIp OBJECT-TYPE SYNTAX InetAddress MAX-ACCESS read-write STATUS current DESCRIPTION "The IP Address used as the source address for the Connection Speed Test. The default value is the value of cabhCdpServerRouter (192.168.0.1)." REFERENCE "CableHome Specification Section 6.4.4" DEFVAL { 'c0a80001'h } -- 192.168.0.1 ::= { cabhCtpConnSpeed 2 } cabhCtpConnDestIpType OBJECT-TYPE SYNTAX InetAddressType MAX-ACCESS read-write STATUS current DESCRIPTION "The IP Address Type for the CTP Connection Speed Tool destination address." DEFVAL { ipv4 } ::={ cabhCtpConnSpeed 3 } cabhCtpConnDestIp OBJECT-TYPE SYNTAX InetAddress MAX-ACCESS read-write STATUS current DESCRIPTION "The IP Address used as the destination address for the Connection Speed Test." ::= { cabhCtpConnSpeed 4 } cabhCtpConnProto OBJECT-TYPE SYNTAX INTEGER { udp (1), tcp (2) } MAX-ACCESS read-write STATUS current DESCRIPTION "The protocol used in the Connection Speed Test. TCP testing is optional." DEFVAL { udp } ::= { cabhCtpConnSpeed 5 } cabhCtpConnNumPkts OBJECT-TYPE SYNTAX INTEGER (1..65535) MAX-ACCESS read-write STATUS current DESCRIPTION "The number of packets the CTP is to send when triggered to execute the Connection Speed Tool." DEFVAL { 100 } ::= { cabhCtpConnSpeed 6 } cabhCtpConnPktSize OBJECT-TYPE SYNTAX INTEGER (64..1518) MAX-ACCESS read-write STATUS current DESCRIPTION "The size of the test frames." REFERENCE "" DEFVAL { 1518 } ::= { cabhCtpConnSpeed 7 } cabhCtpConnTimeOut OBJECT-TYPE SYNTAX INTEGER (0..600000) -- Max 10 minutes UNITS "milliseconds" MAX-ACCESS read-write STATUS current DESCRIPTION "The timeout value for the response. A value of zero indicates no time out and can be used for TCP only." DEFVAL {30000} -- 30 seconds ::= { cabhCtpConnSpeed 8 } cabhCtpConnControl OBJECT-TYPE SYNTAX INTEGER { start(1), abort(2) } MAX-ACCESS read-write STATUS current DESCRIPTION "The control for the Connection Speed Tool. Setting this object to start(1) causes the Connection Speed Tool to execute. Setting this object to abort(2) causes the Connection Speed Tool to stop running. This parameter should only be set via SNMP." DEFVAL {abort } ::={ cabhCtpConnSpeed 9 } cabhCtpConnStatus OBJECT-TYPE SYNTAX INTEGER { notRun(1), running(2), complete(3), aborted(4), timedOut(5) } MAX-ACCESS read-only STATUS current DESCRIPTION "The status of the Connection Speed Tool." DEFVAL { notRun } ::={ cabhCtpConnSpeed 10 } cabhCtpConnPktsSent OBJECT-TYPE SYNTAX INTEGER (0..65535) MAX-ACCESS read-only STATUS current DESCRIPTION "The number of packets the CTP sent after it was triggered to execute the Connection Speed Tool." ::= { cabhCtpConnSpeed 11 } cabhCtpConnPktsRecv OBJECT-TYPE SYNTAX INTEGER (0..65535) MAX-ACCESS read-only STATUS current DESCRIPTION "The number of packets the CTP received after it executed the Connection Speed Tool." ::= { cabhCtpConnSpeed 12 } cabhCtpConnRTT OBJECT-TYPE SYNTAX INTEGER (0..600000) UNITS "millisec" MAX-ACCESS read-only STATUS current DESCRIPTION "The resulting round trip time for the set of packets sent to and received from the target LAN IP Device." ::= { cabhCtpConnSpeed 13 } cabhCtpConnThroughput OBJECT-TYPE SYNTAX INTEGER (0..65535) MAX-ACCESS read-only STATUS current DESCRIPTION "The average round-trip throughput measured in kilobits per second." ::= { cabhCtpConnSpeed 14 } -- -- Parameters and Results for Ping Command -- cabhCtpPingSrcIpType OBJECT-TYPE SYNTAX InetAddressType MAX-ACCESS read-write STATUS current DESCRIPTION "The IP Address Type for CTP Ping Tool source address." DEFVAL { ipv4 } ::={ cabhCtpPing 1 } cabhCtpPingSrcIp OBJECT-TYPE SYNTAX InetAddress MAX-ACCESS read-write STATUS current DESCRIPTION "The IP Address used as the source address for the Ping Test. The default value is the value of CabhCdpServerRouter (192.168.0.1)." REFERENCE "CableHome 1.0 Specification Section 6.4.4" DEFVAL { 'c0a80001'h } ::= { cabhCtpPing 2 } cabhCtpPingDestIpType OBJECT-TYPE SYNTAX InetAddressType MAX-ACCESS read-write STATUS current DESCRIPTION "The IP Address Type for the CTP Ping Tool destination address." DEFVAL { ipv4 } ::={ cabhCtpPing 3 } cabhCtpPingDestIp OBJECT-TYPE SYNTAX InetAddress MAX-ACCESS read-write STATUS current DESCRIPTION "The Destination IP Address used as the destination address for the Ping Test." ::= { cabhCtpPing 4 } cabhCtpPingNumPkts OBJECT-TYPE SYNTAX INTEGER (1..4) MAX-ACCESS read-write STATUS current DESCRIPTION "The number of packets to send to each host." DEFVAL {1} ::= { cabhCtpPing 5 } cabhCtpPingPktSize OBJECT-TYPE SYNTAX INTEGER (64..1518) MAX-ACCESS read-write STATUS current DESCRIPTION "The size of the test frames." DEFVAL {64} ::= { cabhCtpPing 6 } cabhCtpPingTimeBetween OBJECT-TYPE SYNTAX INTEGER (0..600000) UNITS "milliseconds" MAX-ACCESS read-write STATUS current DESCRIPTION "The time between sending one ping and the next." DEFVAL { 1000 } ::= { cabhCtpPing 7 } cabhCtpPingTimeOut OBJECT-TYPE SYNTAX INTEGER (1..600000) UNITS "milliseconds" MAX-ACCESS read-write STATUS current DESCRIPTION "The time out for ping response (ICMP reply) for a single transmitted ping message (ICMP request)." DEFVAL { 5000 } -- 5 seconds ::={ cabhCtpPing 8 } cabhCtpPingControl OBJECT-TYPE SYNTAX INTEGER { start(1), abort(2) } MAX-ACCESS read-write STATUS current DESCRIPTION "The control for the Ping Tool. Setting this object to start(1) causes the Ping Tool to execute. Setting this object to abort(2) causes the Ping Tool to stop running. This parameter should only be set via SNMP." DEFVAL {abort } ::={ cabhCtpPing 9 } cabhCtpPingStatus OBJECT-TYPE SYNTAX INTEGER { notRun(1), running(2), complete(3), aborted(4), timedOut(5) } MAX-ACCESS read-only STATUS current DESCRIPTION "The status of the Ping Tool." DEFVAL { notRun } ::={ cabhCtpPing 10 } cabhCtpPingNumSent OBJECT-TYPE SYNTAX INTEGER (0..4) MAX-ACCESS read-only STATUS current DESCRIPTION "The number of Pings sent" ::={ cabhCtpPing 11 } cabhCtpPingNumRecv OBJECT-TYPE SYNTAX INTEGER (0..255) MAX-ACCESS read-only STATUS current DESCRIPTION "The number of pings received." ::= { cabhCtpPing 12 } cabhCtpPingAvgRTT OBJECT-TYPE SYNTAX INTEGER (0..600000) UNITS "millisec" MAX-ACCESS read-only STATUS current DESCRIPTION "The resulting average of round trip times for acknowledged packets." ::= { cabhCtpPing 13 } cabhCtpPingMaxRTT OBJECT-TYPE SYNTAX INTEGER (0..600000) UNITS "millisec" MAX-ACCESS read-only STATUS current DESCRIPTION "The resulting maximum of round trip times for acknowledged packets." ::= { cabhCtpPing 14 } cabhCtpPingMinRTT OBJECT-TYPE SYNTAX INTEGER (0..600000) UNITS "millisec" MAX-ACCESS read-only STATUS current DESCRIPTION "The resulting minimum of round trip times for acknowledged packets." ::= { cabhCtpPing 15 } cabhCtpPingNumIcmpError OBJECT-TYPE SYNTAX INTEGER (0..255) MAX-ACCESS read-only STATUS current DESCRIPTION "Number of ICMP errors." ::= { cabhCtpPing 16 } cabhCtpPingIcmpError OBJECT-TYPE SYNTAX INTEGER (0..255) MAX-ACCESS read-only STATUS current DESCRIPTION "The last ICMP error." ::= { cabhCtpPing 17 } --========================================================================== -- -- notification group is for future extension. -- cabhCtpNotification OBJECT IDENTIFIER ::= { cabhCtpMib 2 0 } cabhCtpConformance OBJECT IDENTIFIER ::= { cabhCtpMib 3 } cabhCtpCompliances OBJECT IDENTIFIER ::= { cabhCtpConformance 1 } cabhCtpGroups OBJECT IDENTIFIER ::= { cabhCtpConformance 2 } -- -- Notification Group -- -- compliance statements cabhCtpBasicCompliance MODULE-COMPLIANCE STATUS current DESCRIPTION "The compliance statement for devices that implement Portal Service feature." MODULE --cabhCtpMib -- unconditionally mandatory groups MANDATORY-GROUPS { cabhCtpGroup } ::= { cabhCtpCompliances 3 } cabhCtpGroup OBJECT-GROUP OBJECTS { cabhCtpSetToFactory, cabhCtpConnSrcIpType, cabhCtpConnSrcIp, cabhCtpConnDestIpType, cabhCtpConnDestIp, cabhCtpConnProto, cabhCtpConnNumPkts, cabhCtpConnPktSize, cabhCtpConnTimeOut, cabhCtpConnControl, cabhCtpConnStatus, cabhCtpConnPktsSent, cabhCtpConnPktsRecv, cabhCtpConnRTT, cabhCtpConnThroughput, cabhCtpPingSrcIpType, cabhCtpPingSrcIp, cabhCtpPingDestIpType, cabhCtpPingDestIp, cabhCtpPingNumPkts, cabhCtpPingPktSize, cabhCtpPingTimeBetween, cabhCtpPingTimeOut, cabhCtpPingControl, cabhCtpPingStatus, cabhCtpPingNumSent, cabhCtpPingNumRecv, cabhCtpPingAvgRTT, cabhCtpPingMinRTT, cabhCtpPingMaxRTT, cabhCtpPingNumIcmpError, cabhCtpPingIcmpError } STATUS current DESCRIPTION "Group of objects for CableHome CTP MIB." ::= { cabhCtpGroups 1 } END Jones Expires March 2003 [Page 11] Internet Draft Cable Gateway Device MIB October 2002 5. Acknowledgements The terms in this document are derived either from normal cable system usage, or from the documents associated with CableLabs' CableHome specification process. 6. References [1] "CableHome 1.0 Specification SP-CH1.0-I02-020920", CableLabs, September 2002, http://www.cablelabs.com/projects/cablehome/ specifications/. [2] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. 7. Security Considerations There are a number of management objects defined in this MIB that have a MAX-ACCESS clause of read-write and/or read-create. Such objects may be considered sensitive or vulnerable in some network environments. The support for SET operations in a non-secure environment without proper protection can have a negative effect on network operations. It is thus important to control even GET access to these objects and possibly to even encrypt the values of these object when sending them over the network via SNMP. Not all versions of SNMP provide features for such a secure environment. SNMPv1 by itself is not a secure environment. 8. Intellectual Property The IETF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on the IETF's procedures with respect to rights in standards-track and standards-related documentation can be found in BCP-11. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF Secretariat. Jones Expires March 2003 [Page 12] Internet Draft Cable Gateway Device MIB October 2002 The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director. 9. Author's Address Doug Jones YAS BBV 400 Centennial Parkway Louisville, CO 80027 USA phone: +1 303 661 6823 email: doug@yas.com 10. Full Copyright Statement Copyright (C) The Internet Society (1998). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE." Jones Expires March 2003 [Page 13]