2.10.2 Configuring an extended MIB definition file

(1) Extended MIB objects in non-table format

The figure below shows the macro template that you can use when defining MIB objects in non-table format. You must fill in the fields shown in italics.

1. ModuleName

   Specify the name of your MIB module.

2. comment

   Write a comment as required. Note that any comment must be preceded by --.

3. enterpriseName

   Specify the enterprise ID that you registered with the Internet Assigned Numbers Authority.

   objectID

   Specify an object identifier corresponding to the enterprise ID that you specified for enterpriseName. For example, Hitachi's enterprise ID is hitachi and its corresponding object ID is {enterprises 116}.

4. nodeName

   Specify the node name of your MIB object. You can have multiple node name entries and make any node a child of another node.

   objectID

   Specify the name of the parent node of nodeName and the object identifier of nodeName.

5. Object

   Specify the label of the object.

6. data_type

   Specify a data type for Object. Table 2-6 lists the data types supported by SNMP Agent.

   Table 2‒5: Data types

   Data type	Explanation
   INTEGER#1	A simple type consisting of positive and negative integers, including zero. Do not use the value zero as an enumerated type.
   OCTET STRING	A simple type taking zero or more octets, each octet being an ordered sequence of eight bits.
   OBJECT IDENTIFIER	A type denoting an authoritatively named object. An example is 1.3.6.1.2.1.1.0
   NULL	A simple type consisting of a single value, also called null. This type can only be used with defining an object associated with a command.
   NetworkAddress	A type representing an IP address.
   Counter#2	A type representing a non-negative integer which calculates change and increases until it reaches a maximum value. When it reaches the maximum value, it wraps around and starts increasing again from zero.
   Counter64	A Counter type whose maximum is 264-1.
   Gauge#2	A type representing a non-negative integer which can increase or decrease, but which latches at a maximum value.
   TimeTicks#2	A type representing a non-negative integer which indicates the time in hundredths of a second that elapsed since a certain point in time.
   Opaque	A type representing an arbitrary encoding.
   DisplayString	A type representing textual information taken from the NVT ASCII character set.
   PhysAddress	A type representing a media address. Most media addresses are in binary representation. For example, an Internet address is represented as a string of six octets.

   #1: The maximum value is 2³¹ - 1.

   #2: The maximum value is 2³² - 1.

7. access_level

   Specify the level of access allowed. Valid values are:

   read-only

   Means you can perform GetRequests but not SetRequests on the object.

   read-write

   Means you can perform both GetRequests and SetRequests on the object.

8. condition

   Specify the required implementation condition. Valid values are mandatory, optional, obsolete, and deprecated. Except in special cases, specify mandatory.

9. comment

   Write a comment on the object after the label of the object.

10. read_command

    Specify the name of the command that you want SNMP Agent to execute when it receives a GetRequest or GetNextRequest. The read_command parameter follows the READ-COMMAND label. When specifying read_command, use the full path name. If the access_level value following the ACCESS label is read-only or read-write, you must not omit read_command. The output destination must be either the standard output or standard error.

11. command_completion_wait_time ~ <1- or 2-digit number>((1 to 90))<<3>>

    Specify the number of seconds you want SNMP Agent to wait for the completion of read_command. The command_completion_wait_time parameter follows the READ-COMMAND-TIMEOUT label. If read_command is not completed within command_completion_wait_time seconds, SNMP Agent forces read_command to terminate and returns a noSuchName error for SNMPv1 or noSuchInstance for SNMPv2c to the manager. The command_completion_wait_time parameter is optional. If you do not specify command_completion_wait_time, the agent waits for 3 seconds.

12. write_command

    Specify the name of the command that you want SNMP Agent to execute when it receives a SetRequest. The write_command parameter follows the WRITE-COMMAND label. When specifying write_command, use the full path name. If the access_level value following the ACCESS label is read-write, you must not omit write_command.

13. command_completion_wait_time ~ <1- or 2-digit number>((-1, 1 to 90)) <<3>>

    Specify the number of seconds you want SNMP Agent to wait for the completion of write_command. The command_completion_wait_time parameter follows the WRITE-COMMAND-TIMEOUT label. If you specify -1, SNMP Agent returns a response without waiting for the completion of write_command. If write_command is not completed within command_completion_wait_time seconds, SNMP Agent forces write_command to terminate and returns a genErr for SNMPv1 or commitFailed for SNMPv2c to the manager. The command_completion_wait_time parameter is optional. If you do not specify command_completion_wait_time, the agent waits for 3 seconds. SNMP Agent processes one command at a time. Furthermore, the agent waits for a response from each command before processing the next command. This parameter has no bearing on the access level or file read/write permissions.

14. parent_node

    Specify the name of the parent node. parent_node must be a node name you have already defined.

    subidentifier

    Specify the number that uniquely identifies the parent_node object.

To Page Top

(2) Extended MIB objects in table format

To define an SNMP table, you must code the SYNTAX SEQUENCE OF and INDEX clauses. The figure below shows the macro template that you can use when defining MIB objects in table format. You must fill in the fields shown in italics.

This macro template is based on a MIB table that consists of objects 1 and 2. Note that the fields identical to those in non-table format are not explained below.

1. table_name

   Specify a label for your MIB table.

2. entry_data_type

   Specify a data type for the entries of your MIB table. Usually, you will use the first character (in uppercase) of the MIB table entry label. The entry_data_type parameter specifies the data type of columns in the MIB table. In this example, objects 1 and 2 are columns of the MIB table.

3. file_command

   When the agent receives an SNMP GetRequest, GetNextRequest, or SetRequest, the agent executes the file_command before either reading or creating the file_name. When the agent receives an SNMP SetRequest, the agent also executes the file_command after the file_name has been created. The file_command parameter follows the FILE-COMMAND label. When specifying file_command, use the full path name.

   You can specify a monitoring time of 90 seconds or less during which SNMP Agent will wait for a command response, using the -fcmdguard option of the extsubagt command. The default monitoring time is 10 seconds. If no response returns during this period, SNMP Agent will execute kill on this command and perform as follows.

   For SNMPv1

   SNMP Agent returns a genErr error to the manager.

   For SNMPv2c

   If SNMP Agent has received get_request, it returns a noSuchName error to the manager.^#

   If SNMP Agent has received get_next_request, it returns an EndOfMibView error to the manager.^#

   If SNMP Agent has received set_request, it returns a genErr error to the manager.

   #: A value in the VarBind list. The status is normal.

   You can set the extsubagt options so that they will always be effective when the operating system starts or when the snmpstart command is executed. For details about the option settings for the extsubagt process, see 3.1 Starting SNMP Agent.

4. file_command_execution_interval ~ <number>((0 to 2147483647))<<10>>

   When the agent receives an SNMP GetRequest or GetNextRequest, the agent executes the file_command if the agent last executed the file_command more than file_command_execution_interval seconds ago.

   The file_command_execution_interval parameter follows the FILE-COMMAND-FREQUENCY label. The unit is the second. If the received request is a SetRequest, SNMP Agent does not check the time that elapsed since file_command was last executed. The file_command_execution_interval parameter is valid only if you specified file_command after the FILE-COMMAND label. The file_command_execution_interval parameter is optional. The default value is 10 seconds.

5. pipe_in_name

   Specify the name of the file that the UNIX process uses to notify SNMP Agent of the completion of processing after writing data into the file specified after the PIPE-OUT-NAME label. The pipe_in_name parameter follows the PIPE-IN-NAME label. When specifying pipe_in_name, use the full path name.

   You can specify a monitoring time of 90 seconds or less from the time data is written to pipe_out_name to the time processing results are written, using the -pipeguard option of the extsubagt command. The default monitoring time is 20 seconds.

   If the monitoring time extends past a certain period, it might cause the next request to be written before the processing results of the current request are written. For cases when such a request-response mismatch occurs, an identification number can be added to the beginning of the data to be written to pipe_in_name so that responses can be easily matched against requests. You can also specify this identification number by using the -invokeid option of the extsubagt command.

   The following table shows the data to be passed to pipe_in_name.

   Table 2‒6: Data to be passed to pipe_in_name

   Data item	Value to be passed
   Identification number	Identifies the request for the processing result. This identification number is added only when extsubagt's option (-invokeid) is specified. The format is xxxxxxxxxx.yyyyyyyy (where xxxxxxxxxx: absolute time in seconds, yyyyyyyy: microseconds).
   Result code	0

   SNMP Agent behaves as follows if the contents of pipe_in_name are not 0 (4-byte numeric value) or if processing results are not written into pipe_in_name within the specified monitoring time.

   For SNMPv1

   SNMP Agent returns a genErr error to the manager.

   For SNMPv2c

   If SNMP Agent has received get_request, it returns a noSuchName error to the manager.^#

   If SNMP Agent has received get_next_request, it returns an EndOfMibView error to the manager.^#

   If SNMP Agent has received set_request, it returns a genErr error to the manager.

   #: A value in the VarBind list. The status is normal.

   You can set the extsubagt options so that they will always be effective when the operating system starts or when the snmpstart command is executed. For details about the option settings for the extsubagt process, see 3.1 Starting SNMP Agent.

6. pipe_out_name

   Specify the name of the file into which SNMP Agent writes the data to be passed to the UNIX process. When SNMP Agent receives a GetRequest, GetNextRequest, or SetRequest, SNMP Agent writes the data into this file before reading the file_name file specified after the FILE-NAME label. If the received request is a SetRequest, SNMP Agent writes data into the pipe_out_name file before and after reading the file_name file. The pipe_out_name parameter follows the PIPE-OUT-NAME label. When specifying pipe_out_name, use the full path name. The pipe_out_name parameter is optional. Note, however, that you must use the PIPE-OUT-NAME and PIPE-IN-NAME labels in a pair. As in the case with pipe_in_name, you can add an identification number to the beginning of the data to be written to pipe_out_name. Specify this identification number using the -invokeid option of the extsubagt command.

   The table below shows the data to be passed to pipe_out_name. These data items are separated by a space. The data is of the character string type. A \0 is appended to the end of the data.

   Table 2‒7: Data to be passed to pipe_out_name

   Data item	Explanation
   Identification number	Identifies a request. This identification number is added only when it is specified using the -invokeid option of the extsubagt command. The format is xxxxxxxxxx.yyyyyyyy (where xxxxxxxxxx is the absolute time in seconds and yyyyyyyy represents the fragment in microseconds).
   Manager's IP address	Manager's IP address in the Internet dot notation
   Community name	Community name specified in the request
   Object identifier	Object identifier specified in the request. The object identifier is in the dot notation.
   Object syntax	The syntax of the object being requested is passed as one of the following values: Integer, OctetString, ObjectIdentifier, Null, NetworkAddress, IpAddress, Counter, Counter64, Gauge, TimeTicks, Opaque, DisplayString, or PhysAddress.
   PDU type	Type of the request. Valid values are GetRequest, GetNextRequest, SetRequest, and PostSetRequest. PostSetRequest is the value that SNMP Agent passes to the UNIX process after reading the file_name file.
   Instance name	Suffix specified in the request
   Set value	Only when the request type is SetRequest, SNMP Agent passes the Set value in the SetRequest to the UNIX process.

   You can set the options of the extsubagt process to be always enabled at startup or during snmpstart command execution. For details about the option settings for the process, see 3.1 Starting SNMP Agent.

7. pipe_writing_interval ~ <number>((0 to 2147483647))<<10>>

   When SNMP Agent receives a GetRequest or GetNextRequest, the agent writes to the pipe_out_name if the agent last wrote to the pipe_out_name more than pipe_writing_interval seconds ago. The pipe_writing_interval parameter follows the PIPE-FREQUENCY label. The unit is the second. If the received request is a SetRequest, SNMP Agent does not check the time that elapsed since pipe_out_name was last written. The pipe_writing_interval parameter is valid only if you specified both the PIPE-IN-NAME and PIPE-OUT-NAME labels. The default value is 10 seconds.

8. APPEND-COMMUNITY-NAME: {true|false}

   If you specify true, when SNMP Agent receives a request (GetRequest, GetNextRequest, or SetRequest), it names the file that it reads or writes by appending the community name specified in the request to the file name file_name specified in the FILE-NAME label. If you specify false, SNMP Agent reads or writes the file whose file name is file_name (that is, the community name is not appended). You can omit the entire APPEND-COMMUNITY-NAME: {true|false} line. If you omit it, false is assumed.

9. file_name

   Specify the name of the file that SNMP Agent reads or writes when it receives a GetRequest, GetNextRequest, or SetRequest. The file_name parameter follows the FILE-NAME label. When specifying file_name, use the full path name. You must not omit the file_name parameter.

   Before execution of file_command, or before a write to pipe_out_name, SNMP Agent checks whether the specified file exists. If the file does not exist, an error occurs and the MIB value cannot be acquired. SNMP Agent checks for existence of the file, but does not check the contents of the file.

10. entry_name

    Specify the label of a MIB table entry. The data type of the object is determined by entry_data_type. After the INDEX label in the definition of the object, you specify a MIB object whose MIB value uniquely identifies the entry row within the MIB table column. In this example, object_1 is specified.

11. object_1

    The following provides notes on defining MIB objects as columns in a MIB table.

To Page Top

(3) Notes

Note that the /etc/SnmpAgent.d/snmpd.extend file differs from the RFCs in the following areas:

• The imports and exports clauses are not required in the /etc/SnmpAgent.d/snmpd.extend file and will be ignored if added.

• The DESCRIPTION clause is required. Use this field to define the commands you want to execute. By adding a description of the command in the DESCRIPTION field, you will be able to check the details of commands that are executed against requests from the manager.

• If you specify a label two or more times in the DESCRIPTION clause, the second and subsequent labels are interpreted as the values of the first label.

• You must specify the labels in the DESCRIPTION clause in the order in which they appear in the definition macro template. If they are out of order, a definition statement analysis error will result.

• When you define extended MIB objects in table format by using the extended MIB object definition function, define them using no more than 255 columns for the table.

• Object names and entry names that you define must be no longer than 59 characters.

To Page Top