Subject: [OPS-AREA] suggested updates to draft-asai-vmm-mib-03.txt

From: Michael MacFaden <[email-masked]>
Date: Tue, 7 May 2013 11:27:05 -0700 (PDT)

Juergen wrote:
>can you please send this message to the OPSAWG mailing list? We need
>to move discussions over to the list.

Attached please find my suggested patch to the draft-asai-vmm-mib-03.txt

In short:

1. Introduce a new TC called VirtualMachineList. It
   is a clone of Q-BRIDGE-MIB PortList

2. Introduce a new managed object, vmBulkNotificationsEnabled, to report which type 
   of events to receive, either bulk or existing per vm notifications.

3. Adds a parallel set of notifications to match: vmRuning, vmShutdown, vmPaused,
vmSuspended, vmCrashed, vmDeleted that only send a new accessible-for-notify 
variable vmAffectedVMs using SYNTAX VirtualMachineList.

Lastly,  I've added some comments (grep mrm) about what clients
should expect with vmName, vmUUID, vmIndex based on my prior
deployment experience with the similarly structured VMWARE-VMINFO-MIB.

Once patched, the VM-MIB should be syntactically correct to smilint -l9. 
Here are the pre-existing diagnostics before/after the patch.

$smilint -l 9 ./UUID-TC-MIB ./VM-MIB
./UUID-TC-MIB:71: warning: current type `UUID' is not referenced in this module
./UUID-TC-MIB:82: warning: current type `UUIDorZero' is not referenced in this module

Thanks
Mike MacFaden

--- draft-asai-vmm-mib-03.txt	2013-05-06 09:57:55.000487000 -0700
+++ draft-mrm-vmm-mib-01.txt	2013-05-06 13:12:01.000086000 -0700
@@ -520,7 +520,7 @@
            FROM SNMPv2-SMI
        OBJECT-GROUP, MODULE-COMPLIANCE, NOTIFICATION-GROUP
            FROM SNMPv2-CONF
-       TEXTUAL-CONVENTION, PhysAddress
+       TEXTUAL-CONVENTION, PhysAddress, TruthValue
            FROM SNMPv2-TC
        SnmpAdminString
            FROM SNMP-FRAMEWORK-MIB
@@ -943,6 +943,23 @@
                of the virtual machine to the next re-initialization."
         SYNTAX      Integer32 (1..2147483647)
 
+   VirtualMachineList ::= TEXTUAL-CONVENTION
+       DISPLAY-HINT "1x"
+       STATUS       current
+       DESCRIPTION
+        "Each octet within this value specifies a set of eight
+        Virtual Machine vmIndex, with the first octet specifying
+        Virtual Machine 1 through 8, the second octet specifying
+        Virtual Machine 9 through 16, etc.
+        Within each octet, the most significant bit represents
+        the lowest numbered vmIndex, and the least significant bit
+        represents the highest numbered vmIndex.  Thus, each Virtual
+        Machine of the host is represented by a single bit within the
+        value of this object.  If that bit has a value of '1',
+        then that Virtual Machine is included in the set of Virtual Machines;
+        the Virtual Machine is not included if its bit has a value of '0'."
+        SYNTAX      OCTET STRING
+        
 
    -- The hypervisor group
    --
@@ -1092,7 +1109,10 @@
        STATUS       current
        DESCRIPTION
                "A unique value, greater than zero, identifying the
-               virtual machine."
+               virtual machine. The value assigned to a given Virtual
+               machine may not persist across a reboot. A command generator
+               must use the vmUUID to identify a given Virtual Machine of
+               interest. (mrm -note- same design as IF-MIB/ifIndex)"
        ::= { vmEntry 1 }
 
    vmName OBJECT-TYPE
@@ -1109,7 +1129,10 @@
        STATUS       current
        DESCRIPTION
                "The virtual machine's 128-bit UUID or the zero-length
-               string when a UUID is not available."
+               string when a UUID is not available. The UUID if set
+               must uniquely identify a VM from all other Virtual Machines
+               in an administrative region. (*mrm -note- explain
+               case when this value may be empty."
        ::= { vmEntry 3 }
 
    vmOSType OBJECT-TYPE
@@ -1702,6 +1725,25 @@

    -- Notification definitions:
+
+   vmBulkNotificationsEnabled OBJECT-TYPE
+       SYNTAX       TruthValue
+       MAX-ACCESS   read-only
+       STATUS       current
+       DESCRIPTION
+               "Indicates if notification generator will send notifications
+                per VM or per set of VMs."
+       ::= { vmObjects 100 }
+   
+   vmAffectedVMs OBJECT-TYPE
+       SYNTAX       VirtualMachineList
+       MAX-ACCESS   accessible-for-notify
+       STATUS       current
+       DESCRIPTION
+               "A complete list of Virtual Machines whose state has changed.
+                This object is the only object sent with bulk notifications."
+       ::= { vmObjects 101 }
+      
    vmRunning NOTIFICATION-TYPE
        OBJECTS      {
                        vmName,
@@ -1710,15 +1752,29 @@
                     }
        STATUS       current
        DESCRIPTION
-               "This notification is generated when the operational
+              "This notification is generated when the operational
                state of a virtual machine has been changed to
                `running' from some other state.  The other state is
                indicated by the included value of vmOperState."
        ::= { vmNotifications 1 }
 
+   vmsRunning NOTIFICATION-TYPE
+       OBJECTS      {
+                       vmAffectedVMs
+                    }
+       STATUS       current
+       DESCRIPTION
+               "This notification is generated when the operational
+                state of one or more virtual machine has been changed to
+                `running' from a all prior states except for 'running.'
+                Management stations are encouraged to subsequently
+                poll the subset of VMs of interest for vmOperState."
+       ::= { vmNotifications 10 }
+       
+
    vmShutdown NOTIFICATION-TYPE
        OBJECTS      {
-                       vmName,
+                       vmName,       
                        vmUUID,
                        vmOperState
                     }
@@ -1730,6 +1786,18 @@
                indicated by the included value of vmOperState."
        ::= { vmNotifications 2 }
 
+   vmsShutdown NOTIFICATION-TYPE
+       OBJECTS      {
+                      vmAffectedVMs
+                    }
+       STATUS       current
+       DESCRIPTION
+               "This notification is generated when the operational
+               state of one or more virtual machine has been changed to
+               `shutdown' from a state other than `shutdown`.
+                Management stations are encouraged to subsequently
+                poll the subset of VMs of interest for vmOperState."
+       ::= { vmNotifications 20 }

@@ -1752,6 +1820,19 @@
                indicated by the included value of vmOperState."
        ::= { vmNotifications 3 }
 
+   vmsPaused NOTIFICATION-TYPE
+       OBJECTS      {
+                       vmAffectedVMs
+                    }
+       STATUS       current
+       DESCRIPTION
+               "This notification is generated when the operational
+               state of one or more virtual machines have been changed to
+               `paused' from a state other than `paused.`
+                Management stations are encouraged to subsequently
+                poll the subset of VMs of interest for vmOperState."
+       ::= { vmNotifications 30 }
+       
    vmSuspended NOTIFICATION-TYPE
        OBJECTS      {
                        vmName,
@@ -1766,6 +1847,19 @@
                indicated by the included value of vmOperState."
        ::= { vmNotifications 4 }
 
+   vmsSuspended NOTIFICATION-TYPE
+       OBJECTS      {
+                       vmAffectedVMs
+                    }
+       STATUS       current
+       DESCRIPTION
+               "This notification is generated when the operational
+               state of one or more virtual machines have been changed to
+               `suspended' from a state other than 'suspended.' 
+                Management stations are encouraged to subsequently
+                poll the subset of VMs of interest for vmOperState."
+       ::= { vmNotifications 40 }
+       
    vmCrashed NOTIFICATION-TYPE
        OBJECTS      {
                        vmName,
@@ -1780,6 +1874,18 @@
                vmOperState."
        ::= { vmNotifications 5 }
 
+   vmsCrashed NOTIFICATION-TYPE
+       OBJECTS      {
+                       vmAffectedVMs
+                    }
+       STATUS       current
+       DESCRIPTION
+               "This notification is generated when one or more virtual
+                machines have been crashed. 
+                Management stations are encouraged to subsequently
+                poll the subset of VMs of interest for vmOperState."
+       ::= { vmNotifications 50 }
+       
    vmDeleted NOTIFICATION-TYPE
        OBJECTS      {
                        vmName,
@@ -1798,11 +1904,24 @@
        STATUS       current
        DESCRIPTION
                "This notification is generated when a virtual machine
-               has been deleted. The previos state of the virtual
+               has been deleted. The prior state of the virtual
                machine is indicated by the included value of
                vmOperState."
        ::= { vmNotifications 6 }
 
+   vmsDeleted NOTIFICATION-TYPE
+       OBJECTS      {
+                       vmAffectedVMs
+                    }
+       STATUS       current
+       DESCRIPTION
+               "This notification is generated when one or more
+                virtual machines have been deleted.
+                Management stations are encouraged to subsequently
+                poll the subset of VMs of interest for vmOperState."
+
+       ::= { vmNotifications 60 }
+       
    -- Compliance definitions:
    vmGroups       OBJECT IDENTIFIER ::= { vmConformance 1 }
    vmCompliances  OBJECT IDENTIFIER ::= { vmConformance 2 }
@@ -1822,6 +1941,13 @@
            vmNetworkGroup,
            vmNotificationGroup
        }
+       GROUP vmBulkNotificationsVariablesGroup
+       DESCRIPTION
+            "Necessary only if vmNotificationOptionalGroup is implemented."
+       GROUP  vmNotificationOptionalGroup
+       DESCRIPTION
+            "Support for bulk notifications is optional. If not
+             implemented then vmBulkNotificationsEnabled must report false(2)"
        ::= { vmCompliances 1 }
 
    vmReadOnlyCompliances MODULE-COMPLIANCE
@@ -1891,7 +2017,8 @@
            vmHvObjectID,
            vmHvUpTime,
            vmNumber,
-           vmTableLastChange
+           vmTableLastChange,
+           vmBulkNotificationsEnabled
        }
        STATUS       current
        DESCRIPTION
@@ -2010,17 +2137,42 @@
        }
        STATUS       current
        DESCRIPTION
-
+          "A collection of notifications for virtual machines
+           controlled by a hypervisor."
+       ::= { vmGroups 7 }

 Asai, et al.            Expires October 12, 2013               [Page 36]
 
 Internet-Draft       Virtual Machine Monitoring MIB           April 2013
 
+   vmBulkNotificationsVariablesGroup OBJECT-GROUP
+   OBJECTS {
+       vmAffectedVMs
+   }
+   STATUS       current
+   DESCRIPTION
+       "The variables used in vmNotificationOptionalGroup
+        virtual network interfaces controlled by a hypervisor."
+    ::= { vmGroups 8 }
+
+
+   vmNotificationOptionalGroup NOTIFICATION-GROUP
+    NOTIFICATIONS {   
+           vmsRunning,
+           vmsShutdown,
+           vmsPaused,
+           vmsSuspended,
+           vmsCrashed,
+           vmsDeleted
+       }
+       STATUS       current
+       DESCRIPTION
+          "A collection of notifications for bulk notification
+           of changes to virtual machine state (vmOperState) as
+           reported by a given hypervisor."
+       ::= { vmGroups 9 }
 
-               "A collection of notifications for virtual machines
-               controlled by a hypervisor."
-       ::= { vmGroups 7 }
 
    END