CISCO-CABLE-METERING-MIB.mib

--
-- ********************************************************************
-- CISCO-CABLE-METERING-MIB.my:
--       Cisco Cable Metering MIB file 
--
-- March 2004, Sunethra Jawahar
--
-- Copyright (c) 2004 by Cisco Systems, Inc.
-- All rights reserved.
-- ********************************************************************
--
--
-- This is the MIB module for Usage Based Metering for 
-- DOCSIS-compliant Cable Modem Termination Systems (CMTS).
-- 
-- Usage Based Metering is a software feature provided in the CMTS 
-- so that cable operators can perform subscriber account 
-- management and metering in a uniform and consistent manner. 
-- It involves the implementation of Subscriber Account Management
-- Interface Specification (SAMIS) as defined by DOCSIS-OSSI 
-- specification.
--


CISCO-CABLE-METERING-MIB DEFINITIONS ::= BEGIN


IMPORTS
        MODULE-IDENTITY,
        NOTIFICATION-TYPE,
        OBJECT-TYPE,
        Unsigned32
                FROM SNMPv2-SMI
        TruthValue,
        RowStatus,
        DateAndTime,
        TEXTUAL-CONVENTION
                FROM SNMPv2-TC
        OBJECT-GROUP,
        MODULE-COMPLIANCE,
        NOTIFICATION-GROUP
                FROM SNMPv2-CONF
        InetAddress,
        InetAddressType,
        InetPortNumber
                FROM INET-ADDRESS-MIB
        SnmpAdminString 
                FROM SNMP-FRAMEWORK-MIB
        ciscoMgmt
                FROM CISCO-SMI;

ciscoCableMeteringMIB MODULE-IDENTITY
        LAST-UPDATED    "200403300000Z"
        ORGANIZATION    "Cisco Systems, Inc."
        CONTACT-INFO
            "        Cisco Systems
                     Customer Service

             Postal: Cisco Systems
                     170 West Tasman Drive
                     San Jose, CA 95134
                     U.S.A.
             Phone:  +1 800 553-NETS
             E-mail: cs-ubr@cisco.com"

        DESCRIPTION
            "This is the MIB module for Usage Based Metering for the
             DOCSIS-compliant Cable Modem Termination Systems (CMTS).
 
             Usage Based Metering is a software feature provided in the
             CMTS so that cable operators can perform subscriber 
             account management and metering in a uniform and 
             consistent manner. 
             It involves the implementation of Subscriber Account 
             Management Interface Specification (SAMIS) as defined by 
             DOCSIS-OSSI specification. Usage-Based Metering is 
             essential in the processing of bills based on services 
             rendered to and consumed by paying subscribers. The SAMIS 
             specification focuses primarily on bandwidth centric 
             usage-based metering scenarios.
             The DOCSIS 1.1 RFI specification provides a mechanism for 
             a Cable Modem (CM) to register with its Cable Modem 
             Termination System (CMTS) and to configure itself based 
             on external Quality of Service (QoS) parameters when it 
             is powered up or reset. The principal mechanism for 
             providing enhanced QoS is to classify packets traversing 
             the RF MAC interface into a Service Flow. 
             A Service Flow is a unidirectional flow of packets that is
             provided a particular Quality of Service. 

             The mediation system can then rate the charges differently 
             for each of the Service Flow traffic counts based on 
             its Service Class. Thus, the mediation system obtains from 
             the CMTS the traffic counts for each named Service Flow 
             (identified by SFID) that a subscribers CM uses during 
             the metering data collection interval. The Usage Based 
             Metering requirement is that the CMTS must be able to 
             provide formatted Subscriber Usage 
             Metering Records for all subscribers attached to the CMTS,
             on demand to an external collection system. Optionally, 
             the metering records can be stored locally so that it is 
             available via ftp to the external collection server.

             The CMTS provides two configuration options to handle the
             export of metering data.
             Local :
             Store the record locally on the CMTS after collection. The
             metering system should then(operating at its own schedule)
             take the file out of the CMTS and is also responsible for
             deletion of the local file on the CMTS.  The deletion of 
             the file is an indication to the metering collector to 
             start construction of the new metering record which will 
             then be written to the local filesystem and the cycle 
             continues.

             Streaming: 
             Stream the records to an external collection system as
             they get generated.  The time interval in which the record
             will be generated is configurable at the CMTS. A secure 
             and reliable stream is used to transport the metering 
             record out of the CMTS. 
             In case the connection to external metering system is 
             not possible, CMTS will retry establishing channel for a 
             max specified times. 

             The MIB allows for configuration of the parameters that 
             control the metering record collection like interval, 
             amount of metering information required, location or IP 
             address of the collection server, and metering filename. 
             In addition it provides for some important notificatons to
             the NMS to indicate the success/failure of the 
             metering collection."

        REVISION        "200403300000Z"
        DESCRIPTION
            "Initial version of this MIB module."

        ::= { ciscoMgmt 424 }


CcmtrStatus ::= TEXTUAL-CONVENTION
   STATUS      current
   DESCRIPTION
       "The CcmtrStatus is used to indicate success or failure status 
       that occurred during the process of writing the metering 
       records to the non-volatile memory device or 
       during streaming them to an external mediation
       or collection server
       It has the following defined values:
       - 'unknown', indicates other reasons for failure of write/stream
          of the metering records . 
       - 'success', indicates that write of the metering file or 
          streaming to the collection server was successful.
       - 'deviceFull', indicates that there is not enough space on the 
          non-volatile memory device for writing the metering record
          file.
       - 'writeError', indicates that there was a write error when 
          trying to write the metering record file or stream to the 
          collection server.
       - 'fileNotExist', indicates that the metering file has not yet 
          been created for access by the collection server.   
       - 'connectionTimeout', indicates a failure to connect to the 
          collection server.
       - 'dataIncomplete', indicates that there was a failure during
          write or streaming and that the metering record might be 
          incomplete. "
   SYNTAX      INTEGER {
                  unknown(1),
                  success(2),
                  deviceFull(3),
                  writeError(4),
                  fileNotExist(5),
                  connectionTimeout(6),
                  dataIncomplete(7)
               }

CcmtrCollectionServer ::= TEXTUAL-CONVENTION
   STATUS      current
   DESCRIPTION
       "The CcmtrCollectionServer is used to indicate the type of
       the collection server.
       It has the following defined values:
       - 'primary', indicates that the collection server is primary
          and will be the first server to which streaming will be
          attempted. 
       - 'secondary', indicates that the collection server is
          secondary and that it will be used only if streaming
          to the primary server failed. " 
    SYNTAX      INTEGER {
                  primary(1),
                  secondary(2)
                }

ciscoCableMeteringMIBNotifs   OBJECT IDENTIFIER ::=
                                { ciscoCableMeteringMIB  0 }

ciscoCableMeteringMIBObjects OBJECT IDENTIFIER ::= 
                                { ciscoCableMeteringMIB 1 }

ccmtrMeteringConfig  OBJECT IDENTIFIER ::= 
                                { ciscoCableMeteringMIBObjects 1 }

ccmtrMetering   OBJECT IDENTIFIER ::= 
                                { ciscoCableMeteringMIBObjects 2 }

ccmtrCollectionType OBJECT-TYPE
       SYNTAX       INTEGER {
                       none(1), 
                       local(2),
                       stream(3)
                    }
       MAX-ACCESS   read-write
       STATUS       current
       DESCRIPTION
           "Current method of export for metering data. 
            The enumerations are:
            none(1)    : Metering collection has not been enabled.
            local(2)   : Store the collected metering records locally 
                         on the CMTS. 
            stream(3)  : Stream the metering records to an external 
                         collection or mediation server. "
       ::= { ccmtrMeteringConfig 1 }      
                                       

-- This scalar object will be used if one would like to store the 
-- metering records locally. 

ccmtrCollectionFilesystem OBJECT-TYPE
        SYNTAX      SnmpAdminString(SIZE(0..80))
        MAX-ACCESS  read-write
        STATUS      current
        DESCRIPTION
            "The filesystem where metering records are to be stored. 
            This object makes sense only if ccmtrCollectionType object 
            is local which indicates that the metering records are 
            to be stored in the local filesystem. 
            When ccmtrCollectionType is 'stream' this object will
            retain its set value though it will not be used. "
        ::= { ccmtrMeteringConfig 2 }

-- The following scalar objects and table will be used if one would 
-- like to stream the metering records to an external collection 
-- system. 


ccmtrCollectionTable  OBJECT-TYPE
        SYNTAX      SEQUENCE OF CcmtrCollectionEntry
        MAX-ACCESS  not-accessible
        STATUS      current
        DESCRIPTION
            "This table is used only if ccmtrCollectionType object is 
            stream which indicates that the metering records are to 
            be streamed to an external collection server. 
            It contains IP address information of the  collection 
            server. In addition it contains other configurable 
            parameters like interval, retries etc needed for 
            streaming the metering records."
        ::= { ccmtrMeteringConfig 3 }

ccmtrCollectionEntry OBJECT-TYPE
        SYNTAX      CcmtrCollectionEntry
        MAX-ACCESS  not-accessible
        STATUS      current
        DESCRIPTION
            "A set of IP attributes of the mediation or 
            collection server and configuration parameters for 
            streaming the metering records.
            An entry in this table exists for each configured
            mediation or collection server."
        INDEX { ccmtrCollectionID }
        ::= { ccmtrCollectionTable 1 }

CcmtrCollectionEntry ::= SEQUENCE {
             ccmtrCollectionID               CcmtrCollectionServer,
             ccmtrCollectionIpAddrType       InetAddressType,
             ccmtrCollectionIpAddress        InetAddress,
             ccmtrCollectionPort             InetPortNumber,
             ccmtrCollectionRowStatus        RowStatus
        }

ccmtrCollectionID OBJECT-TYPE
        SYNTAX          CcmtrCollectionServer
        MAX-ACCESS      not-accessible
        STATUS          current
        DESCRIPTION
            "Identification of a IP address and port number 
            associated with the mediation or collection server. 
            The ccmtrCollectionID is used in determining the order 
            of the IP address, port number to which the streaming will
            take place. The primary represents the first
            collection server and secondary represents the
            second collection server if streaming to the primary
            failed for any reason. Thus primary entry 
            must be created before the secondary. "
        ::= { ccmtrCollectionEntry 1 }

ccmtrCollectionIpAddrType OBJECT-TYPE
        SYNTAX      InetAddressType
        MAX-ACCESS  read-create
        STATUS      current
        DESCRIPTION
            "The type of internet address of ccmtrCollectionIpAddress."
        DEFVAL { ipv4  }
        ::= { ccmtrCollectionEntry 2 }

ccmtrCollectionIpAddress OBJECT-TYPE
        SYNTAX      InetAddress
        MAX-ACCESS  read-create
        STATUS      current
        DESCRIPTION
            "The IP address of the collection server. It will be of
            type as referred by ccmtrCollectionIpAddrType.
            The ccmtrCollectionPort should be also valid along with 
            ccmtrCollectionIpAddress for a row to be created. The 
            primary collection server IP address represented by
            ccmtrCollectionID equal to 1 must be created before the
            secondary collection server IP address. " 
        ::= { ccmtrCollectionEntry 3 }

ccmtrCollectionPort OBJECT-TYPE
        SYNTAX      InetPortNumber
        MAX-ACCESS  read-create
        STATUS      current
        DESCRIPTION
            "The port number of the collection server. This port number
            chosen should not be any of the well defined ports.
            The ccmtrCollectionIpAddress should be also valid along 
            with ccmtrCollectionPort for a row to be created. The 
            primary collection server port represented by
            ccmtrCollectionID equal to 1 must be created before the
            secondary collection server port." 
        ::= { ccmtrCollectionEntry 4 }



ccmtrCollectionRowStatus OBJECT-TYPE
        SYNTAX      RowStatus
        MAX-ACCESS  read-create
        STATUS      current
        DESCRIPTION
            "Controls and reflects the status of rows in this table. 
             It can use used for creation, modifying and deleting
             entries in this table.
             The ccmtrCollectionPort should also be valid along with 
             ccmtrCollectionIpAddress for a row to be created.
             The ccmtrCollectionID 1 represents the primary
             collection server and ccmtrCollectionID 2 represents the
             secondary collection server. Thus ccmtrCollectionID of 1
             must be created before the ccmtrCollectionID of 2."
        ::= { ccmtrCollectionEntry 8 }


ccmtrCollectionInterval OBJECT-TYPE
        SYNTAX      Unsigned32(15..1440)
        UNITS       "minutes"
        MAX-ACCESS  read-write
        STATUS      current
        DESCRIPTION
            "The interval in which the metering information is 
            collected. 
            This object makes sense only if ccmtrCollectionType object 
            is stream which indicates that the metering records 
            are to be streamed to an external collection server."
        DEFVAL { 30 }
        ::= { ccmtrMeteringConfig 4 }

ccmtrCollectionRetries OBJECT-TYPE
        SYNTAX      Unsigned32(0..5) 
        MAX-ACCESS  read-write
        STATUS      current
        DESCRIPTION
            "The number of retries to stream the metering records to 
            the external collection server before an error is flagged. 
            This object makes sense only if ccmtrCollectionType object 
            is stream which indicates that the metering records 
            are to be streamed to an external collection server."
        DEFVAL { 0 }
        ::= { ccmtrMeteringConfig 5 }

ccmtrCollectionSecure OBJECT-TYPE
        SYNTAX      TruthValue 
        MAX-ACCESS  read-write
        STATUS      current
        DESCRIPTION
            "An indication of whether the streaming to the collection 
            server should be secure or not. The value of true
            indicates that the streaming will be secure and false
            indicates non-secure. 
            However the secure option is available only if the image 
            on the CMTS allows for security.
            This object makes sense only if ccmtrCollectionType object 
            is stream which indicates that the metering records 
            are to be streamed to an external collection server."
        DEFVAL { false }
        ::= { ccmtrMeteringConfig 6 }

-- The following objects are used to change the contents of metering 
-- records based on requirements of the collection server.

ccmtrCollectionCpeList OBJECT-TYPE
        SYNTAX      TruthValue 
        MAX-ACCESS  read-write
        STATUS      current
        DESCRIPTION
            "An indication if one would like the metering records to 
            contain the CPE(Customer premises equipment) IP addresses. 
            This option is provided to improve performance.
            By default, this object is true which means the CPE 
            information will always be present."
        DEFVAL { true }
        ::= { ccmtrMeteringConfig 7 }

ccmtrCollectionAggregate OBJECT-TYPE
        SYNTAX      TruthValue 
        MAX-ACCESS  read-write
        STATUS      current
        DESCRIPTION
            "An indication if one would like only aggregate Service Flow
            information per Cable Modem to be recorded. In this case 
            the record will have a SFID of 0 and a blank Service Class 
            Name. The distinction between upstream and downstream will 
            however be maintained. The counters present in the metering
            records in this case will be the aggregate. i.e., sum of all
            upstream/downstream service flows. By default, this object 
            is false which means that the metering records will 
            contain service flow counter information for all service 
            flows per CM."
        DEFVAL { false }
        ::= { ccmtrMeteringConfig 8 }

-- The following objects are those that are required for the metering 
-- success/failure notifications 

ccmtrCollectionStatus OBJECT-TYPE
        SYNTAX      CcmtrStatus
        MAX-ACCESS  read-only
        STATUS      current
        DESCRIPTION
            "The status of the last metering data export. It indicates 
            the success or failure of writing the metering record file 
            or streaming the record to the collection server."
        ::= { ccmtrMetering 1 }

ccmtrCollectionDestination  OBJECT-TYPE
        SYNTAX      SnmpAdminString (SIZE(1..80))
        MAX-ACCESS  read-only
        STATUS      current
        DESCRIPTION
            "It represents the name of the file that is created to 
            store the metering record or the IP address and port 
            number to which the metering information was streamed in 
            both the success and failure scenerios. 
            In the case of local storage it is the filename generated 
            as the CMTS host name followed by the timestamp when the 
            file was created. 
            The file will be stored in the filesystem as specified in 
            ccmtrCollectionFilesystem.
            In the case of streaming it is the IP address and port 
            number in the format IPADDRESS:PORT# to which the last 
            streaming took place."
        ::= { ccmtrMetering 2 }

ccmtrCollectionTimestamp OBJECT-TYPE
        SYNTAX      DateAndTime
        MAX-ACCESS  read-only
        STATUS      current
        DESCRIPTION
            "The time when the last metering record was exported 
            successfully or with some failure. "  
        ::= { ccmtrMetering 3 }

ccmtrMeteringNotifEnable  OBJECT-TYPE
        SYNTAX      TruthValue
        MAX-ACCESS  read-write
        STATUS      current
        DESCRIPTION
            "An indication of whether the notifications associated
            with metering are enabled or disabled. 
            true indicates the notification is enabled and 
            false indicates the notification is disabled."
        DEFVAL { false }
        ::= { ccmtrMetering 4 }


--
-- The Cisco Cable Metering MIB Notifications
--


ccmtrCollectionNotification  NOTIFICATION-TYPE
       OBJECTS {
            ccmtrCollectionStatus,  
            ccmtrCollectionDestination,
            ccmtrCollectionTimestamp
       }
       STATUS current
       DESCRIPTION
           "A notification that is sent to indicate the success or 
            failure in creating the metering record file or streaming 
            it to the collection server.
            ccmtrCollectionStatus represents the success or 
            failure of the export. 
            ccmtrCollectionDestination and ccmtrCollectionTimestamp 
            represent the destinaton and timestamp of the export in 
            both the success and failure scenerios. 
            The receipt of this notification is 
            an indication to the collection server that the file can be
            accessed via ftp or any file transfer protocol in the case
            of local storage." 
           
       ::= { ciscoCableMeteringMIBNotifs 1 }

ciscoCableMeteringMIBConformance         OBJECT IDENTIFIER
                ::= { ciscoCableMeteringMIB 3 }

ciscoCableMeteringMIBCompliances         OBJECT IDENTIFIER
                ::= { ciscoCableMeteringMIBConformance 1 }

ciscoCableMeteringMIBGroups              OBJECT IDENTIFIER
                ::= { ciscoCableMeteringMIBConformance 2 }

-- compliance statements

ciscoCableMeteringCompliance  MODULE-COMPLIANCE
        STATUS      current
        DESCRIPTION
            "The compliance statement for CMTS devices that implement
            the Usage Based Metering feature. "
        MODULE -- this module
                MANDATORY-GROUPS {
                        ccmtrMeteringObjGroup,
                        ccmtrMeteringNotifCtrlGroup,
                        ccmtrMeteringNotifGroup
                        }
        OBJECT      ccmtrCollectionIpAddrType
        DESCRIPTION
            "Only ipv4 type of internet address is supported."
        OBJECT      ccmtrCollectionPort
        DESCRIPTION
            "Value of 0 for port number is not supported."
        OBJECT      ccmtrCollectionRowStatus
        DESCRIPTION
            "createAndGo, active and destroy are the 
             only RowStatus values that will be supported for this
             object."
        ::= { ciscoCableMeteringMIBCompliances 1 }

-- units of conformance

ccmtrMeteringObjGroup OBJECT-GROUP
        OBJECTS {
             ccmtrCollectionType,
             ccmtrCollectionFilesystem,
             ccmtrCollectionIpAddrType,
             ccmtrCollectionIpAddress, 
             ccmtrCollectionPort, 
             ccmtrCollectionInterval,
             ccmtrCollectionRetries,
             ccmtrCollectionSecure,
             ccmtrCollectionRowStatus,
             ccmtrCollectionCpeList,
             ccmtrCollectionAggregate,
             ccmtrCollectionStatus,
             ccmtrCollectionDestination,
             ccmtrCollectionTimestamp
        }
        STATUS    current
        DESCRIPTION
            "Group of objects implemented in CMTS
            providing for usage based metering configuration
            and notification information. "
        ::= { ciscoCableMeteringMIBGroups 1 }


ccmtrMeteringNotifCtrlGroup OBJECT-GROUP
        OBJECTS {
             ccmtrMeteringNotifEnable 
             
        }
        STATUS        current
        DESCRIPTION
            "The notification control which a 
            CISCO-CABLE-METERING-MIB
            is required to implement."
        ::= { ciscoCableMeteringMIBGroups 2 }

ccmtrMeteringNotifGroup NOTIFICATION-GROUP
        NOTIFICATIONS {
             ccmtrCollectionNotification
        }
        STATUS        current
        DESCRIPTION
            "The notification which a CISCO-CABLE-METERING-MIB
            is required to implement."
        ::= { ciscoCableMeteringMIBGroups 3 }


END