2.10.3 Creating the shell commands to be executed during SNMP request
You must create shell commands that you specified in the /etc/SnmpAgent.d/snmpd.extend file. The following explains how to create them.
The shell commands are UNIX shell scripts or programs. The /opt/OV/prg_samples/eagent directory contains an example of creating the /etc/SnmpAgent.d/snmpd.extend file. This example contains sample shell commands.
Note the following when determining command names:
-
You specify these commands in the DESCRIPTION clause in the /etc/SnmpAgent.d/snmpd.extend file.
-
The maximum command size is 5120 characters.
-
A command can span multiple lines. End each line with a backslash (\).
-
Commands that are defined using READ-COMMAND, WRITE-COMMAND, or FILE-COMAND can be executed by a root user. Assign a file attribute to these commands to enable the commands to be executed by a root user.
The following procedure shows how to create a command.
Procedure
-
Log in to the system on which you want to execute the command.
-
Write a shell script or program.
-
Verify the operation of the shell command.
-
Check the exit code.
-
Check the arguments of the shell command.
The procedure for creating commands is as follows:
- Organization of this subsection
(2) Writing a script or program
The following explains how to write a shell script or program.
-
Arguments
You can configure SNMP Agent to pass some arguments to your command. Table 2-9 lists the available arguments. These arguments can be in any order.
Table 2‒8: Arguments Value to be passed
$i
The management station's IP address. The address is in internet dot notation.
$c
The community name used in the request.
$o
The OBJECT IDENTIFIER used in the request. The OBJECT IDENTIFIER is in dot notation.
$s
The SYNTAX of the object. One of the following values will be passed: Integer, OctetString, ObjectIdentifier, Null, NetworkAddress, IpAddress, Counter, Counter64, Gauge, TimeTicks, Opaque, DisplayString, or PhysAddress.
$r
The request issued by the management station. One of the following values will be passed: GetRequest, GetNextRequest, SetRequest, or PostSetRequest. The PostSetRequest will be passed to the file_command after the file_name has been created.
$I
The instance used in the request.
$*
This is the same as specifying $i $c $o $s $r $I.
$$
To pass a $ character as an argument value to the command, specify $$. One of the two $ characters is passed as the argument value.
Set value
Only when the request is a SetRequest or PostSetRequest, the Set value in the SetRequest is passed to the command. The Set value is passed as the last item of the argument list.
Suppose that you are defining MIB objects in non-table format so that SNMP Agent executes the /opt/OV/prg_samples/eagent/num_widgets command. To make SNMP Agent pass the manager's IP address, community name, and object identifier as arguments to the command, code the following line in the DESCRIPTION clause in the /etc/SnmpAgent.d/snmpd.extend file:
READ-COMMAND: /opt/OV/prg_samples/eagent/num_widgets $i $c $o
Suppose that you are defining MIB objects in table format so that SNMP Agent executes the /opt/OV/prg_samples/eagent/update_inetd command before reading the file specified after the FILE-NAME label. To make SNMP Agent pass the request type as an argument to the command, code the following line in the DESCRIPTION clause in the /etc/SnmpAgent.d/snmpd.extend file:
FILE-COMMAND: /opt/OV/prg_samples/eagent/update_inetd $r
If you do not specify arguments, SNMP Agent will not pass any arguments to read_command or file_command. For write_command or file_command, SNMP Agent passes only one Set value in the request if you do not specify arguments for the command.
-
Arguments that you must specify to use the same command for both get and set operations
When specifying one command for both the READ-COMMAND and WRITE-COMMAND lines, you must specify the appropriate arguments in order to distinguish between GetRequest and SetRequest. You must specify the following arguments:
READ.REQ for a get operation
WRITE.REQ for a set operation
For example, to use the /usr/bin/my_command command for both READ-COMMAND and WRITE-COMMAND, enter the following:
- READ-COMMAND
-
/usr/bin/my_command READ.REQ
- WRITE-COMMAND
-
/use/bin/my_command WRITE.REQ
-
Search path
When specifying a command name, use the full path name.
-
Return values
Output the return values from the command specified on the READ-COMMAND label to standard out or standard error.
-
Execution
The commands you created appear to be executed by /bin/sh. You can also specify shell commands such as exit, read, if, and for.
-
Exit codes
Any shell command written with a READ-COMMAND or WRITE-COMMAND label must be terminated with a 0. If this type of command is terminated with a non-zero exit code, SNMP Agent behaves as follows:
- For SNMPv1
-
If SNMP Agent has received a get-request, it returns a noSuchName error to the manager.
If SNMP Agent has received a get-next-request, it searches for the next object.
If SNMP Agent has received a set-request, it returns a genErr error to the manager.
- For SNMPv2c
-
If SNMP Agent has received a get-request, it returns a noSuchInstance error to the manager.
If SNMP Agent has received a get-next-request, it searches for the next object.
If SNMP Agent has received a set-request, it returns a commitFailed error to the manager.
The command specified after the FILE-COMMAND label must always terminate with exit code 0. If the exit code is not 0, SNMP Agent behaves as follows:
- For SNMPv1
-
If SNMP Agent has received a get-request, it returns a noSuchName error to the manager.
If SNMP Agent has received a get-next-request, it searches for the next object.
If SNMP Agent has received a set-request, it returns a genErr error to the manager.
- For SNMPv2c
-
If SNMP Agent has received a get-request, it returns a noSuchInstance error to the manager.
If SNMP Agent has received a get-next-request, it searches for the next object.
If SNMP Agent has received a non-table version of SetRequest or PostSetRequest, a type of set-request, it returns a commitFailed error to the manager.
If SNMP Agent has received a table version of SetRequest, a type of set-request, it returns a genErr error to the manager.
If SNMP Agent has received a table version of PostSetRequest, a type of set-request, it returns a commitFailed error to the manager.
All the behaviors shown above also apply when SNMP Agent's attempt to execute a user-defined shell command resulted in an error such that the command was not found.
(3) Verifying the operation of your shell command
Execute the shell command to make sure that it executes successfully.
To check whether the fmailListMsg-related command in the /etc/SnmpAgent.d/snmpd.extend file executes successfully, execute the following command:
/usr/bin/mailq
If the execution is successful, the command outputs a mail message list to standard output.
(4) Checking the exit code
Execute the following command and check the exit code. If the exit code is 0, your shell command has normally terminated.
echo $?
(5) Checking the arguments of your shell command
If your shell command has arguments, verify the arguments.
The following example checks the definition and arguments in the /etc/SnmpAgent.d/snmpd.extend file:
- Definition in the /etc/SnmpAgent.d/snmpd.extend file
READ-COMMAND:/opt/OV/prg_samples/eagent/num_widgets $i $c $o $s
- Checking the arguments
num_widgets 15.2.3.149 public 1.3.6.4.4242.3.1 Gauge