improve snmp docS

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/devmodules/dev-libs/ec@34795 72102866-910b-0410-8b05-ffd578937521

EcAlarmSinkSNMP.m

@@ -126,7 +126,7 @@ static BOOL
 heartbeat(time_t now);
 
 static void
-init_EcTrapSink(void);
+init_EcAlarmSink(void);
 
 static Netsnmp_Node_Handler alarmsTable_handler;
 
@@ -349,7 +349,7 @@ heartbeat(time_t now)
    * Send the trap to the list of configured destinations
    *  and clean up
    */
-  DEBUGMSGTL(("EcTrapSink", "Sending heartbeat trap.\n"));
+  DEBUGMSGTL(("EcAlarmSink", "Sending heartbeat trap.\n"));
   send_v2trap(var_list);
   snmp_free_varbind(var_list);
   return YES;
@@ -435,7 +435,7 @@ housekeeping(unsigned int clientreg, void *clientarg)
 
 
 static void
-init_EcTrapSink(void)
+init_EcAlarmSink(void)
 {
   netsnmp_handler_registration		*reg;
   netsnmp_table_registration_info	*tinfo;
@@ -685,7 +685,7 @@ pollHeartBeat_handler(netsnmp_mib_handler *handler,
   int32_t	*pollHeartBeat_cache = NULL;
   int32_t	tmp;
 
-  DEBUGMSGTL(("EcTrapSink", "Got instance request:\n"));
+  DEBUGMSGTL(("EcAlarmSink", "Got instance request:\n"));
 
   switch (reqinfo->mode)
     {
@@ -713,7 +713,7 @@ pollHeartBeat_handler(netsnmp_mib_handler *handler,
 	  }
 	netsnmp_request_add_list_data(requests,
 				      netsnmp_create_data_list
-				      ("EcTrapSink",
+				      ("EcAlarmSink",
 				       pollHeartBeat_cache, free));
 	break;
 
@@ -726,18 +726,18 @@ pollHeartBeat_handler(netsnmp_mib_handler *handler,
 	  {
 	    pollHeartBeat = tmp;
 	    [alarmSink _store];
-	    DEBUGMSGTL(("EcTrapSink", "updated pollHeartBeat -> %d\n", tmp));
+	    DEBUGMSGTL(("EcAlarmSink", "updated pollHeartBeat -> %d\n", tmp));
 	  }
 	else
 	  {
-	    DEBUGMSGTL(("EcTrapSink", "ignored pollHeartBeat -> %d\n", tmp));
+	    DEBUGMSGTL(("EcAlarmSink", "ignored pollHeartBeat -> %d\n", tmp));
 	    netsnmp_set_request_error(reqinfo, requests, SNMP_ERR_WRONGVALUE);
 	  }
 	break;
 
       case MODE_SET_UNDO:
 	pollHeartBeat =
-	  *((int32_t*)netsnmp_request_get_list_data(requests, "EcTrapSink"));
+	  *((int32_t*)netsnmp_request_get_list_data(requests, "EcAlarmSink"));
 	break;
 
       case MODE_SET_COMMIT:
@@ -1093,14 +1093,14 @@ static NSLock	*classLock = nil;
   p = [NSString stringWithFormat: @"tcp:%@:%@", _host, _name];
   netsnmp_ds_set_string(NETSNMP_DS_APPLICATION_ID,
     NETSNMP_DS_AGENT_X_SOCKET, [p UTF8String]);
-  if (0 != init_agent("EcTrapSink"))
+  if (0 != init_agent("EcAlarmSink"))
     {
-      NSLog(@"Unable to initialise EcTrapSink as an SNMP sub-agent");
+      NSLog(@"Unable to initialise EcAlarmSink as an SNMP sub-agent");
     }
 
   /* Initialize MIB code here
    */
-  init_EcTrapSink();
+  init_EcAlarmSink();
 
   /* Will read ecAlarmSinkSNMP.conf files.
    */
@@ -1163,7 +1163,7 @@ static NSLock	*classLock = nil;
   [pool release];
   pool = [NSAutoreleasePool new];
 
-  snmp_log(LOG_INFO,"Control-SNMP-agent is up and running.\n");
+  // snmp_log(LOG_INFO,"EcAlarmSinkSNMP startup.\n");
 
   _isRunning = YES;
   while (NO == _shouldStop)
@@ -1174,8 +1174,9 @@ static NSLock	*classLock = nil;
     }
   [pool release];
 
+  // snmp_log(LOG_INFO,"EcAlarmSinkSNMP shutdown.\n");
   /* at shutdown time */
-  snmp_shutdown("EcTrapSink");
+  snmp_shutdown("EcAlarmSink");
   _isRunning = NO;
   SOCK_CLEANUP;
 }
@@ -1428,7 +1429,7 @@ static NSLock	*classLock = nil;
   time_t	now;
   BOOL	changed = NO;
 
-  DEBUGMSGTL(("EcTrapSink", "Housekeeping timer called.\n"));
+  DEBUGMSGTL(("EcAlarmSink", "Housekeeping timer called.\n"));
 
   [_alarmLock lock];
   if (NO == _inTimeout && YES == _isRunning && NO == _shouldStop)

GNUSTEP-MIB.txt

@@ -0,0 +1,266 @@
+
+--
+--
+--
+
+GNUSTEP-MIB DEFINITIONS ::= BEGIN
+
+IMPORTS
+  MODULE-IDENTITY,
+  OBJECT-TYPE,
+  NOTIFICATION-TYPE,
+  Counter,
+  IpAddress,
+  enterprises
+    FROM SNMPv2-SMI
+  DisplayString
+    FROM SNMPv2-TC;
+
+gnustep MODULE-IDENTITY
+  LAST-UPDATED "201202191200Z"
+  ORGANIZATION "GNUstep"
+  CONTACT-INFO "Developer GNUstep <gnustep-dev@gnu.org>"
+  DESCRIPTION  "GNUstep MIB"
+  REVISION     "201202191200Z"
+  DESCRIPTION  "First revision of the MIB"
+::= { enterprises XXXXX }
+
+alarms OBJECT IDENTIFIER ::= { gnustep 1 }
+objects OBJECT IDENTIFIER ::= { gnustep 2 }
+traps OBJECT IDENTIFIER ::= { gnustep 3 }
+trapsPrefix OBJECT IDENTIFIER ::= { traps 0 }
+
+-----------------------------------------------
+-- Definition of the table of active alarms --
+-----------------------------------------------
+alarmsTable OBJECT-TYPE
+SYNTAX SEQUENCE OF AlarmsEntry
+MAX-ACCESS not-accessible
+STATUS current
+DESCRIPTION "List of active alarms in the platform."
+::= { alarms 1 }
+
+--------------------------------------------------------
+-- Definition of the tables index --
+--------------------------------------------------------
+alarmsEntry OBJECT-TYPE
+SYNTAX AlarmsEntry
+MAX-ACCESS not-accessible
+STATUS current
+DESCRIPTION "This is the index used to redirect each column."
+INDEX { notificationID }
+::= { alarmsTable 1 }
+
+-----------------------------------------------------------------------
+-- Definition of the contents of each record on the table --
+-----------------------------------------------------------------------
+AlarmsEntry ::=
+SEQUENCE {
+notificationID INTEGER,
+perceivedSeverity INTEGER,
+firstEventDate DisplayString,
+eventDate DisplayString,
+managedObject DisplayString,
+ideventType INTEGER,
+idprobableCause INTEGER,
+specificProblem DisplayString,
+proposedRepairAction DisplayString,
+additionalText DisplayString,
+trendIndicator DisplayString
+}
+
+-----------------------------------------------
+-- Definition of the fields for each record --
+-----------------------------------------------
+notificationID OBJECT-TYPE
+SYNTAX INTEGER ( 0 .. 214748647 )
+MAX-ACCESS read-only
+STATUS current
+DESCRIPTION "Single identifier of each alarm"
+::= { alarmsEntry 1 }
+
+perceivedSeverity OBJECT-TYPE
+SYNTAX INTEGER {
+indeterminate(0),
+critical(1),
+major(2),
+minor(3),
+warning(4),
+cleared(5) }
+MAX-ACCESS read-only
+STATUS current
+DESCRIPTION "Severity of the alarm"
+::= { alarmsEntry 2 }
+
+firstEventDate OBJECT-TYPE
+SYNTAX DisplayString
+MAX-ACCESS read-only
+STATUS current
+DESCRIPTION "First alarm concurrence date. Format: YYYYMMDD HH:MM:SS"
+::= { alarmsEntry 3 }
+
+eventDate OBJECT-TYPE
+SYNTAX DisplayString
+MAX-ACCESS read-only
+STATUS current
+DESCRIPTION "Alarm concurrence date. Format: YYYYMMDD HH:MM:SS"
+::= { alarmsEntry 4 }
+
+managedObject OBJECT-TYPE
+SYNTAX DisplayString (SIZE (0..127) )
+MAX-ACCESS read-only
+STATUS current
+DESCRIPTION "Single identifier of the alarm object"
+::= { alarmsEntry 5 }
+
+ideventType OBJECT-TYPE
+SYNTAX INTEGER {
+communicationsAlarm(2),
+environmentalAlarm(3),
+equipmentAlarm(4),
+processingErrorAlarm(10),
+qualityofServiceAlarm(11) }
+MAX-ACCESS read-only
+STATUS current
+DESCRIPTION "Identifier of the type of event"
+::= { alarmsEntry 6 }
+
+
+-- The X.733 specification says that the probable cause is an OID, --
+-- but for ease of use this MIB defines it as an INTEGER whose value is --
+-- that of the rightmost part of the OID defined in X.721 specification. --
+-- For example the OID 'adapterError' {9.3.2.0.0.1} is represented as --
+-- the integer 1 and 'outOfMemory' {9.3.2.0.0.32} is represented as 32 --
+
+idprobableCause OBJECT-TYPE
+SYNTAX INTEGER
+MAX-ACCESS read-only
+STATUS current
+DESCRIPTION "Identifier of the possible event cause"
+::= { alarmsEntry 7 }
+
+specificProblem OBJECT-TYPE
+SYNTAX DisplayString
+MAX-ACCESS read-only
+STATUS current
+DESCRIPTION "Additional description of the event cause"
+::= { alarmsEntry 8 }
+
+proposedRepairAction OBJECT-TYPE
+SYNTAX DisplayString
+MAX-ACCESS read-only
+STATUS current
+DESCRIPTION "Solution suggested for the fault detected"
+::= { alarmsEntry 9 }
+
+additionalText OBJECT-TYPE
+SYNTAX DisplayString
+MAX-ACCESS read-only
+STATUS current
+DESCRIPTION "Detailed description of the problem"
+::= { alarmsEntry 10 }
+
+trendIndicator OBJECT-TYPE
+  SYNTAX DisplayString
+  MAX-ACCESS read-only
+  STATUS current
+  DESCRIPTION
+"Description of the alarm trends. For alarms by threshold.
+It can have the following values:
+0 (zero) ==>  First problem incident.
++  ==> The importance of the alarm is higher than the last one sent.
+-  ==> The importance of the alarm is lower than the last one sent."
+::= { alarmsEntry 11 }
+
+--------------------------------------------------------------------
+-- Flag for the inhibition of the traps sent during resynchronization--
+--------------------------------------------------------------------
+
+resyncFlag OBJECT-TYPE
+SYNTAX INTEGER ( 0 ..1 )
+MAX-ACCESS read-write
+STATUS current
+DESCRIPTION
+"Flag for the inhibition of the traps sent during the resynchronization process.
+1 = Resync in progress. The agent must store all traps to send them later on."
+::= { alarms  2 }
+
+------------------------------------------------
+-- Sequence number of the last trap sent --
+------------------------------------------------
+trapSequenceNumber OBJECT-TYPE
+SYNTAX INTEGER
+MAX-ACCESS read-only
+STATUS current
+DESCRIPTION "Trap sequence number"
+::= { alarms 3 }
+
+------------------------------------------------
+-- Heart beat period                     --
+------------------------------------------------
+pollHeartBeat OBJECT-TYPE
+SYNTAX INTEGER
+MAX-ACCESS read-write
+STATUS current
+DESCRIPTION "Indicates the period during which the heart-beat trap is sent. In minutes."
+::= { alarms 4 }
+
+---------------------------------------------------
+-- Definition of the alarm object table --
+---------------------------------------------------
+objectsTable OBJECT-TYPE
+SYNTAX SEQUENCE OF ObjectsEntry
+MAX-ACCESS not-accessible
+STATUS current
+DESCRIPTION "List of alarm objects of the platform."
+::= { objects 1 }
+
+--------------------------------------------------------
+-- Definition of the table index --
+--------------------------------------------------------
+objectsEntry  OBJECT-TYPE
+SYNTAX  ObjectsEntry
+MAX-ACCESS  not-accessible
+STATUS  current
+DESCRIPTION "Index of the alarm object table"
+INDEX { objectId }
+::= { objectsTable 1 }
+
+-----------------------------------------------------------------------
+-- Definition of the contents of each record on the table --
+-----------------------------------------------------------------------
+ObjectsEntry ::=
+SEQUENCE
+{
+  objectId     DisplayString
+}
+objectId OBJECT-TYPE
+SYNTAX DisplayString  (SIZE (0..127) )
+MAX-ACCESS read-only
+STATUS current
+DESCRIPTION "Single identifier of the alarm object"
+::= { objectsEntry 1 }
+
+----------------------------------------------------------------
+-- Definition of the trap sent to the alarm management area    --
+----------------------------------------------------------------
+alarmTrap NOTIFICATION-TYPE
+OBJECTS {
+trapSequenceNumber,
+notificationID,
+perceivedSeverity,
+firstEventDate,
+eventDate,
+objectId,
+ideventType,
+idprobableCause,
+specificProblem,
+proposedRepairAction,
+additionalText,
+trendIndicator
+}
+STATUS current
+DESCRIPTION "Trap format sent."
+::= { trapsPrefix 1 }
+
+END

README.SNMP

@@ -0,0 +1,62 @@
+
+Here's the sort of thing you might do to set up SNMP support on your
+system, assuming that you have net-snmp installed in the normal
+locations for something like RedHat Linux.
+
+0. Edit the example GNSTEP-MIB.txt to contain your own organisation's
+   Private Enterprise Number
+
+1. install GNUSTEP-MIB.txt in /usr/share/snmp/mibs
+
+2. edit '/etc/sysconfig/snmpd.options' to contain:
+OPTIONS="$OPTIONS -Dgnustep -Lf /var/log/snmpd"
+export OPTIONS
+so that any debug for the gnustep module would be logged
+in /var/log/snmpd
+
+3. edit '/etc/sysconfig/snmptrapd.options' to contain:
+OPTIONS="$OPTIONS -Dgnustep -Lf /var/log/snmptrapd"
+export OPTIONS
+so that any debug for the gnustep module would be logged
+in /var/log/snmptrapd
+
+4. edit /etc/snmp/snmpd.conf to get it to send traps to snmptrapd ...
+
+rwcommunity     public
+trap2sink       localhost public
+
+and to accept agentx connections via tcp ...
+
+agentxsocket    tcp:localhost:705
+master          agentx
+
+5. restart with '/etc/rc.d/init.d/snmpd restart'
+
+6. build/install/run the Control server
+
+7. test with snmpwalk ...
+
+To look at EVERYTHING:
+snmpwalk -v 1 -c public localhost GNUSTEP-MIB::gnustep
+
+To look at the current alarms table:
+snmpwalk -v 1 -c public localhost GNUSTEP-MIB::gnustep.alarms.alarmsTable
+
+To look at the current alarms table in a tabular format (rows of columns) which will be far too wide to view in a normal terminal window:
+snmptable -v 1 -c public localhost GNUSTEP-MIB::gnustep.alarms.alarmsTable
+
+To look at the managed objects table:
+snmpwalk -v 1 -c public localhost GNUSTEP-MIB::gnustep.objects
+
+You should be able to get the heartbeat poll interval with:
+snmpget -v 1 -c public localhost GNUSTEP-MIB::pollHeartBeat.0
+
+You should be able to set the heartbeat poll interval to two minutes with 
+snmpset -v 1 -c public localhost GNUSTEP-MIB::pollHeartBeat.0 i 2
+
+You should be able to set the resync flag interval with
+snmpset -v 1 -c public localhost GNUSTEP-MIB::resyncFlag.0 i 1
+and set it back to normal with
+snmpset -v 1 -c public localhost GNUSTEP-MIB::resyncFlag.0 i 0
+
+