-- ****************************************************************************
-- ****************************************************************************
--
--             Copyright(c) 2001-2002 Mediatrix Telecom, Inc. 
--
--  NOTICE:
--   This document contains information that is confidential and proprietary
--   to Mediatrix Telecom, Inc. 
--
--   Mediatrix Telecom, Inc. reserves all rights to this document as well as
--   to the Intellectual Property of the document and the technology and
--   know-how that it includes and represents. 
--
--   This publication cannot be reproduced, neither in whole nor in part in
--   any form whatsoever without written prior approval by
--   Mediatrix Telecom, Inc. 
--
--   Mediatrix Telecom, Inc. reserves the right to revise this publication
--   and make changes at any time and without the obligation to notify any
--   person and/or entity of such revisions and/or changes. 
--
-- ****************************************************************************
-- ****************************************************************************

MX-GROUP-ADMIN-MIB
DEFINITIONS ::= BEGIN

IMPORTS
        MODULE-IDENTITY,
        OBJECT-TYPE,
        Integer32
    FROM SNMPv2-SMI
        MODULE-COMPLIANCE,
        OBJECT-GROUP
    FROM SNMPv2-CONF
        mediatrixAdmin
    FROM MX-SMI;

groupAdminMIB MODULE-IDENTITY
    LAST-UPDATED "200508230000Z"
    ORGANIZATION "Mediatrix Telecom, Inc."
    CONTACT-INFO "Mediatrix Telecom, Inc.
                  4229, Garlock Street
                  Sherbrooke (Quebec)
                  Canada
                  Phone: (819) 829-8749
                  "
    DESCRIPTION  "This MIB defines the administrative commands and status related to a
                  managed object. These objects are managed by the combination of three
                  attributes that are termed OSI States attributes.

                  This MIB follows ISO/IEC 10164-2 CCITT Recommendation X.731 with 
                  the following interpretations and extensions.

                  This MIB contains managable objects containers. The table
                  groupAdminTable contains group of entities that are manageable
                  uniquely (in another admin table) or in group( groupAdminTable).

                  The management state of a managed object represents the 
                  instantaneous condition of availability and operability of the
                  associated resource from the management point of view. 
                  Managed objects have a variety of state attributes that express
                  and control aspects of the operation of their associated
                  resource that are peculiar to each. However, the management
                  state is expected to be common to a large number of resources 
                  and, for this reason, is standardized; it expresses key aspects
                  of their usability at any given time. We used three primary 
                  factors to allocate the management state of a managed object.
                  These are:

                  operability    : indicates whether or not the resource is
                                   operational.

                  usage          : indicates whether or not the resource is
                                   actively in use at a specific instant and, if
                                   so, whether or not it has spare capacity for
                                   additional requests at that instant.

                  administration : indicates the current maintenance state of a
                                   group. This attribute reflects the result
                                   of an operator-initiated maintenance request.

                  The status of the managed object is closely related to the status of 
                  its children. These status are affected by external events such
                  as administrative commands. The behavior of the managed object
                  to these events is explained below.

                  event : receive an administrative lock (graceful) command 
                          for a group:

                          1) The administrative state of the group (groupAdminState) is
                             changed to SHUTTING DOWN.
                          2) All children are notified to set their usage state to
                             IDLE UNUSABLE gracefully.
                          3) The children change their usage state to IDLE UNUSABLE
                             as soon as their activities end.
                          4) When the usage state of all children have been set to 
                             IDLE UNUSABLE, the usage state of the group (groupUsageState)
                             is changed to IDLE UNUSABLE.
                          5) The administrative state of the group (groupAdminState)is
                             changed to LOCKED.

                  event : receive an administrative lock command (non graceful)
                          for a group:

                          1) All children are notified to set their usage state
                             to IDLE UNUSABLE immediately.
                          2) The children change their usage state to IDLE UNUSABLE
                             abruptly.
                          3) When the usage state of all children have been change to 
                             IDLE UNUSABLE, the usage state of the group (groupUsageState)
                             is changed to IDLE UNUSABLE.
                          4) The administrative state of the group (groupAdminState) is
                             changed to LOCKED.

                  event : receive an administrative unlock command for a group

                          1) All children are notified to set their usage state to
                             IDLE if:
                               * the administrative state of the child is 
                                 UNLOCKED AND
                               * the administrative states of all its parents are
                                 also UNLOCKED AND
                               * the operational state of the child is ENABLED AND
                               * the operational state of all its parents are 
                                 also ENABLED.
                          2) The usage state of the group (groupUsageState) is changed
                             to IDLE if:
                               * the administrative state of all its parents are 
                                 also UNLOCKED AND
                               * the operational state of the group is ENABLED AND
                               * the operational state of all its parents are
                                 also ENABLED.
                          3) The administrative state of the group (groupAdminState) 
                             is changed to UNLOCKED.
 
                  event : An operational problem is discovered with a group

                         1) All children are notified to set their usage state to 
                            IDLE UNUSABLE abruptly.
                         2) All children change their usage state to IDLE UNUSABLE
                            abruptly.
                         3) When the usage state of all children have been set to 
                            IDLE UNUSABLE, the usage state of the group (groupUsageState)
                            is changed to IDLE UNUSABLE.
                         4) The operational state of the group (groupOpState) is changed
                            to DISABLED.
 
                  event : An operational problem is resolved in a group
 
                         1) All children are notified to set their usage state 
                           to IDLE if:
                               * the administrative state of the child is 
                                 UNLOCKED AND
                               * the administrative state of all its parents are 
                                 also UNLOCKED AND
                               * the operational state of the child is ENABLED AND
                               * the operational state of all its parents are 
                                 also ENABLED
                         2) The usage state of the group (groupUsageState) is changed
                            to IDLE if:
                               * the administrative state of the group is UNLOCKED AND
                               * the administrative state of all its parents are 
                                 also UNLOCKED AND
                               * the operational state of all its parents are 
                                 also ENABLED
                         3) The operational state of the group (groupOpState) is changed
                            to ENABLED
                 "
                  
    -- ************************************************************************
    -- Revision history
    -- ************************************************************************
    REVISION    "200508230000Z"
    DESCRIPTION "August 23, 2005
                    Edited a typo in a DESCRIPTION.
                 August 29, 2001
                    Creation"
    ::= { mediatrixAdmin 5 }

groupAdminMIBObjects  OBJECT IDENTIFIER ::= { groupAdminMIB 1 }
groupAdminConformance OBJECT IDENTIFIER ::= { groupAdminMIB 2 }


    -- ************************************************************************
    -- if Admin table parameters
    -- ************************************************************************
    groupAdminTable OBJECT-TYPE
        SYNTAX      SEQUENCE OF GroupAdminEntry
        MAX-ACCESS  not-accessible
        STATUS      current
        DESCRIPTION "A table of managed objects."
        ::= { groupAdminMIBObjects 1 }
        
        groupAdminEntry OBJECT-TYPE
            SYNTAX      GroupAdminEntry
            MAX-ACCESS  not-accessible
            STATUS      current
            DESCRIPTION "A row in the groupAdminTable used to managed each group of 
                         objects."
            INDEX       {
                         groupAdminIndex
                        }
            ::= { groupAdminTable 1 }

            GroupAdminEntry ::= SEQUENCE 
                {
                    groupAdminIndex       Integer32,
                    groupSetAdmin         INTEGER,
                    groupAdminState       INTEGER,
                    groupOpState          INTEGER,
                    groupUsageState       INTEGER,  -- Fault state will be added later on
                    groupReset            INTEGER,
                    groupAdminType        INTEGER,
                    groupAdminDescription OCTET STRING (SIZE (0..255)),
                    groupAdminParentGroup Integer32
                }

    groupAdminIndex OBJECT-TYPE
        SYNTAX      Integer32
        MAX-ACCESS  not-accessible
        STATUS      current
        DESCRIPTION "Index of the group admin table."
        ::= { groupAdminEntry 1 }                

    groupSetAdmin OBJECT-TYPE
        SYNTAX      INTEGER {
                             noOp(0),
                             unlock(1),
                             lock(2),
                             forcelock(3)
                            }
        MAX-ACCESS  read-write
        STATUS      current
        DESCRIPTION "Command to set the administrative state of the system.
        
                     noOp      : no operation.
                     
                     Unlock    : The groupAdminState variable is set to unlocked.
                     
                     Lock      : If the groupUsageState variable's value is 
		     		 idle-unusable or idle, then the groupAdminState 
				 variable is set to locked. If activities are in 
				 progress, the groupUsageState variable's value 
				 is either busy or active, activities continue 
				 until normal completion and the groupAdminState
                                 variable is set to shuttingdown.

                     Forcelock : The groupAdminState variable is set to locked 
		     		 and the groupUsageState variable's value is 
				 updated to idle-unusable. All activities that 
				 are in progress will be terminated immediately. 
                                 No new request may be initiated."
        DEFVAL { noOp }
        ::= { groupAdminEntry 2 }                
       
    groupAdminState OBJECT-TYPE
        SYNTAX  INTEGER {
                         unlocked(1),
                         shuttingDown(2),
                         locked(3)
                        }
                    
        MAX-ACCESS  read-only
        STATUS      current
        DESCRIPTION "The administrative state of the group.
        
                     Indicates the current maintenance state of a group.
                     This attribute reflects the result of an operator-
                     initiated maintenance request.

                     Unlocked     : no operator-initiated maintenance request is
                                    affecting the operation of the group.

                     ShuttingDown : the group is in a transition state between
                                    unlocked and locked state. A group will only 
                                    transition to a locked state once all current
                                    activities are completed  No new activity will
                                    be accepted once all activities are
                                    terminated.
                     
                     Locked       : an operator-initiated request has been issued 
                                    for this group. This group and all its children
                                    are unavailable for normal operation."
        DEFVAL { unlocked }
        ::= { groupAdminEntry 3 }

    groupOpState OBJECT-TYPE
        SYNTAX  INTEGER {
                          enabled(1),
                          disabled(2)
                        }
        MAX-ACCESS  read-only
        STATUS      current
        DESCRIPTION "The operational state of the group.

                     It  reflect the  group's internal state. There are
                     certain conditions that affect the internal state of 
                     a group.

                     Enabled  : the group is operationally functional.

                     Disabled : the group is operationally non-functional due
                                to an internal condition that would not allow it 
                                to participate in normal operation."
        DEFVAL { disabled }
        ::= { groupAdminEntry 4 }

    groupUsageState OBJECT-TYPE
        SYNTAX  INTEGER {
                         idle(1),
                         active(2),
                         busy(3),
                         idle-unusable(4)
                        }
        MAX-ACCESS  read-only
        STATUS      current
        DESCRIPTION "The usage state of the group.
        
                     Indicates the running state of a group.
                     
                     Idle          : the group is not currently active, but
                                     is available for use.

                     Active        : the group is currently being used, is
                                     available for processing and still has
                                     additional capacity.

                     Busy          : the group is usable but is not available
                                     for any new additional processing requests,
                                     since all of its ressources (child) are
                                     currently being used.
                                     
                     Idle-Unusable : the group is not currently active and
                                     not available for use."
        DEFVAL { idle-unusable }
        ::= { groupAdminEntry 6 }       

    groupReset OBJECT-TYPE
        SYNTAX      INTEGER {
                             noOp(0),
                             softReset(1)
                            }
        MAX-ACCESS  read-write
        STATUS      current
        DESCRIPTION "Command to request a reset on the group.
        
                     NoOp      : no operation. In case the reset is not started,
                                 it will cancel the operation.
                     
                     SoftReset : This will conduct a software reset on the group
                                 under certain conditions:
                                 
                                 groupAdminState  result
                                 ---------------  -------------------------------
                                 Locked           start reset immediatly
                                 ShuttingDown     wait for the state to be locked
                                                  then start the reset
                                 Unlock           command is discarded"
        DEFVAL { noOp }
        ::= { groupAdminEntry 8 }                

    groupAdminType OBJECT-TYPE
        SYNTAX      INTEGER {
                              gateway(1)
                            }
        MAX-ACCESS  read-only
        STATUS      current
        DESCRIPTION "The type of resources managed by the group."
        DEFVAL { gateway }
        ::= { groupAdminEntry 11 }       

    groupAdminDescription OBJECT-TYPE
        SYNTAX      OCTET STRING (SIZE (0..255))
        MAX-ACCESS  read-only
        STATUS      current
        DESCRIPTION "The description of the group."
        ::= { groupAdminEntry 12 }       

    groupAdminParentGroup OBJECT-TYPE
        SYNTAX      Integer32
        MAX-ACCESS  read-only
        STATUS      current
        DESCRIPTION "The parent's group. This is the index (groupAdminIndex), taken
                     from this table (groupAdminTable), of the group that is the parent.
                     In case there is no parent, the value '-1' is used."
        DEFVAL { -1 }
        ::= { groupAdminEntry 15 }       


    -- ************************************************************************
    -- Conformance information
    -- ************************************************************************
    groupAdminCompliances OBJECT IDENTIFIER ::= { groupAdminConformance 1 }

    groupAdminComplVer1 MODULE-COMPLIANCE
        STATUS      current
        DESCRIPTION     
            "List of compliance groups required to support a managed group of objects."
        MODULE -- This Module
            MANDATORY-GROUPS { 
                                groupAdminGroupVer1                             }
        ::= { groupAdminCompliances 1 }

    -- ************************************************************************
    -- MIB variable grouping
    -- ************************************************************************
    groupAdminGroups OBJECT IDENTIFIER ::= { groupAdminConformance 2 }

    groupAdminGroupVer1 OBJECT-GROUP
        OBJECTS {
                    groupSetAdmin,
                    groupAdminState,
                    groupOpState,
                    groupUsageState,
                    groupReset,
                    groupAdminType,
                    groupAdminDescription,        
                    groupAdminParentGroup
                }
        STATUS current
        DESCRIPTION
            "A collection of objects that defines a group of managed objects."
        ::= { groupAdminGroups 1 }


END
