The z/OS UNIX snmp command

The z/OS UNIX snmp command provides the following SNMP manager functions from the z/OS® UNIX shell:

Query SNMP agents for network management information.
Receive and format SNMP traps and notifications.

Use the snmp command to issue SNMP requests to agents and to process SNMP responses returned by agents. This command supports a maximum SNMP response packet size of 65 535 bytes. SNMPv1, SNMPv2c, and SNMPv3 requests are supported.

Use the snmp command with the trap request type to receive and format traps and notifications.

Note: snmp is a synonym for the osnmp command in the z/OS UNIX shell. The osnmp command syntax is the same as that for the snmp command.

Format

Getting MIB Variables:


         .- -d 0-----------.  .- -h localhost---.   
>>-snmp--+-----------------+--+-----------------+--------------->
         '- -d debug_level-'  '- -h target host-'   

   .- -r 2------------.  .- -c public----------.   
>--+------------------+--+---------------------+---------------->
   '- -r retry number-'  '- - c community_name-'   

   .- -t 3-------------.                     
>--+-------------------+--+-----+--+-----+---------------------->
   '- -t timeout value-'  '- -v-'  '- -a-'   

>--+-get-----------------------------------------------------+-->
   +-getnext-------------------------------------------------+   
   | .- -m 10--------------.  .- -n 0-------------.          |   
   '-+---------------------+--+-------------------+--getbulk-'   
     '- -m max repetitions-'  '- -n non-repeaters-'              

   .--------------.   
   V              |   
>----mib_variable-+--------------------------------------------><

Setting the MIB Variables:


         .- -d 0-----------.  .- -h localhost---.   
>>-snmp--+-----------------+--+-----------------+--------------->
         '- -d debug_level-'  '- -h target host-'   

   .- -r 2------------.  .- -c public---------.   
>--+------------------+--+--------------------+----------------->
   '- -r retry number-'  '- -c community_name-'   

   .- -t 3-------------.                          
>--+-------------------+--+-----+--+-----+--set----------------->
   '- -t timeout value-'  '- -v-'  '- -a-'        

   .----------------------------------.   
   V                                  |   
>----mib_variable--+---------+--value-+------------------------><
                   '-vartype-'

Walking the MIB Tree:


         .- -d 0-----------.  .- -h localhost---.   
>>-snmp--+-----------------+--+-----------------+--------------->
         '- -d debug_level-'  '- -h target host-'   

   .- -r 2------------.  .- -c public---------.   
>--+------------------+--+--------------------+----------------->
   '- -r retry number-'  '- -c community_name-'   

   .- -t 3-------------.                     
>--+-------------------+--+-----+--+-----+---------------------->
   '- -t timeout value-'  '- -v-'  '- -a-'   

>--+-walk-----------------------------------------------------+-->
   | .- -m 10--------------.  .- -n 0-------------.           |   
   '-+---------------------+--+-------------------+--bulkwalk-'   
     '- -m max repetitions-'  '- -n non-repeaters-'               

>--mib_variable------------------------------------------------><

Displaying snmp Help:


>>-snmp-- -?---------------------------------------------------><

Receiving a Trap:


         .- -d 0-----------.  .- -p 162---------.         
>>-snmp--+-----------------+--+-----------------+--trap--------><
         '- -d debug_level-'  '- -p port_number-'

Finding a MIB Variable Name:


         .- -d 0-----------.                           
>>-snmp--+-----------------+--findname--mib_variable-----------><
         '- -d debug_level-'

Parameters

-d debug_level

Specifies the debug level. The valid debug levels are 0-4. The default level is 0, which means no debug. Each higher trace level includes all the trace messages from the lower levels.

-h target host

Specifies the target host to which you want to send a request. This can be an IPv4 (dotted decimal) or IPv6 (colon hexadecimal) address, a host name, or a winSNMP name in the OSNMP.CONF configuration file. If you do not specify a host, the default is your local host.

Restriction: You cannot specify scope information as part of the host name or the IP address of the target host.

-r retry number

Specifies the maximum number of times to retry the command if it timed out. The default is 2.

-c community_name

Specifies the community name that is used to access the specified variables at the destination SNMP agent. If you do not specify a community name, the default name is public. Community names are not required when using the user-based security model.

Note: Community names are case-sensitive.

-t timeout value

Specifies the amount of time (in seconds) that the snmp command waits for a reply from the SNMP agent. The default value is 3.

-v

Specifies that the output from a request is displayed using verbose output. Use of this option causes the values to be returned with the textual name in place of the MIB object identifier.

-a

Specifies that the request packet is sent using the physical interface addresses, rather than a VIPA address (if one is available) as the originating IP address. By default, the snmp command now uses the VIPA address. Alternately, the NOSVIPA option can be configured in the OSNMP.CONF file.

-m max repetitions

Applies only to getbulk and bulkwalk requests. This is ignored if the function request is not a getbulk or bulkwalk. Maximum repetitions is the number of lexicographic successors to be returned for each variable binding pair after the first -n number successors. For example, starting with successor -n number+1, return -m number of successors for each variable binding pair. The default is 10.

-n nonrepeaters

Applies only to getbulk or bulkwalk requests. This is ignored if the function request is not a getbulk or bulkwalk. The value nonrepeaters is the number of variable binding pairs (name and value), starting with the first, for which only a single successor is returned. The default value is 0.

mib_variable

Specifies the Management Information Base (MIB) object, using its object descriptor (textual name), object identifier in ASN.1 notation, or a combination of the two. When used with walk and bulkwalk requests, this is the MIB object prefix. A prefix can be any leading portion of the complete object identifier. When used with findname, this is the object identifier in ASN.1 notation.

vartype

Specifies the type of value being set. To complete an SNMP SET request, the SMI_type must be known. If no type is specified, snmp searches first the MIBS.DATA file and then the compiled MIB to determine the type. If the variable is not found, an error is returned. If a vartype is specified, the vartype takes precedence over any type that can be assigned in the MIB. The vartype and value must be compatible. For example, if you specify a type of "number" and a value of "foo", an error is returned because "foo" is not a number. The vartype parameter is not case-sensitive. Valid variable types are:

bitstring
counter
counter32
counter64
display or displaystring
integer
integer32
ipaddress
gauge
gauge32
nsapaddress
null
objectidentifier or OID
octetstring
opaque
opaqueascii
timeticks
uinteger

value

Specifies the value to be set by the SET function. If white space is needed in the value, you must enclose the value in double quotation marks ("). If you want to set a variable to a value that is also a type, you must specify the type.

-?

Displays help information.

-p port_number

Specifies the number of the port that listens for traps. If a port number is not specified, the snmp command trap function listens on the well-known port 162, the default port for snmp traps.

SNMP request types:

get: Sends a request to an SNMP agent for a specific management information base (MIB) variable. The snmp command then waits for a response or times out.
getnext: Sends a request to an SNMP agent for the next MIB variable that lexicographically follows the mib_variable value specified. The snmp command then waits for a response or times out.
getbulk: Obtains the value of the variables in the MIB tree specified by the OID or MIB variable name. A single getbulk request performs the same function as a series of getnext requests with fewer data exchanges between the snmp command and the SNMP agent.
set: Sends a request to an SNMP agent to set a specific MIB variable. The snmp command then waits for a response or times out.
walk: Issues a getnext request for a specified prefix, then continues to issue getnext requests for as long as there are variables that match the specified prefix. A prefix can be any leading portion of the complete object identifier.
bulkwalk: Issues a GETBULK request for a specified prefix, then continues to issue GETBULK requests for as long as there are variables that match the specified prefix.
trap: Listens for SNMP traps and displays trap information when they occur. Uses the default well-known port 162 or the port number specified on the -p option. The snmp trap function continues to listen for traps until the process is killed or canceled.
findname: Sends a request that a search be done to obtain the textual name, for a given mib_variable input, whose internal ASN.1 value best matches the input ASN.1 value. The search first checks the MIBS.DATA file, and if a matching textual name is not found, continues with the compiled MIB. Only one mib_variable is allowed per snmp findname invocation.

Usage

The set operation is not supported on all MIB objects. The set operation might be rejected if the agent or subagents managing the MIB object do not support SET.
getbulk and bulkwalk are SNMPv2 functions. If the target agent supports only SNMPv1, the target agent ignores your request. As a result, your request times out.
The function keywords are not case-sensitive. The - options and variable types and values are case-sensitive.
In order to issue the snmp trap command, you must be in superuser mode if the use of the low port numbers is restricted by the UDPCONFIG statement in the TCP/IP profile. Low port access is required in order to bind to well-known port 162. If you are not in superuser mode, you receive error EZZ3301I Error return from bind() : EDC5111I Permission denied.
For more information about the UDPCONFIG statement, see the z/OS Communications Server: IP Configuration Reference.
In order to listen to traps from NetView® SNMP and z/OS UNIX snmp command at the same time, use the -p port_number parameter on the snmp command. Only one management application at an IP address can listen on a port at a time. Specifying -p on the snmp trap command enables a port other than well-known port 162 to be used. Both ports must be configured as agent trap destinations.
An snmp command that is not authenticated (by using an acceptable community name or user name) will time out.
The snmp command uses two configuration files: MIBS.DATA and OSNMP.CONF. Sample files are shipped in the/usr/lpp/tcpip/samples directory. For information about these configuration files, see the z/OS Communications Server: IP Configuration Reference.
The snmp command supports sending SNMPv1, SNMPv2c, and SNMPv3 requests. The snmp command uses the OSNMP.CONF file to determine whether it sends an SNMPv1, SNMPv2c, or SNMPv3 request. If the target specified by way of the -h parameter matches a winSNMP name in the OSNMP.CONF file, snmp sends the request using the parameters specified on the entry. If the -h parameter is not specified, then the request will be sent as an SNMPv1 request. If the -h parameter is specified and is not found in the OSNMP.CONF file, the following error message is issued:
```
EZZ3306I Error converting <name> to Entity
```

Examples

Getting the MIB variable
The following requests MIB object sysName.0:
```
snmp get sysName.0
1.3.6.1.2.1.1.5.0 = MVS SNMP
```
The following requests MIB object myName.0, where myName is defined in the MIBS.DATA file to be the same object identified by sysName.0:
```
snmp get myName.0
1.3.6.1.2.1.1.5.0 = MVSX SNMPv2 Agent
```
Getting the next MIB variable
The following requests the next logical MIB object:
```
snmp getnext udp
1.3.6.1.2.1.7.1.0 = 653
```
The following requests the next logical object, using the -v option to have value displayed with textual name instead of object identifier:
```
snmp -v getnext udp
udpInDatagrams.0 = 653
```
Setting the MIB variable
The following sets MIB object sysName.0 to a value of ’MVSX SNMPv2 Agent’:
```
snmp set sysName.0  "MVSX SNMPv2 Agent"
1.3.6.1.2.1.1.5.0 = MVSX SNMPv2 Agent
```
The following sets MIB object usmUserAuthKeyChange.1.2.2.117.49 to a hexadecimal value. Backward slashes are included in the value before each single quote to indicate to the UNIX shell that the single quote is part of the string to be passed to the snmp command. The 'h at the end of the value indicates that a hexadecimal value is passed.
```
snmp set usmUserAuthKeyChange.1.2.2.117.49       
\'3eca6ff34b59010d262845210a40165678dd9646e31e9f890480a233dbe1114d\'h 
```

Walking the MIB tree

The following returns by name all objects beginning with the same object identifier prefix:

snmp -v walk udp 

udpInDatagrams.0 = 13  
udpNoPorts.0 = 7       
udpInErrors.0 = 0      
udpOutDatagrams.0 = 20 
udpLocalAddress.0.0.0.0.161 = 0.0.0.0                                           
udpLocalAddress.0.0.0.0.514 = 0.0.0.0                                           
udpLocalAddress.0.0.0.0.4001 = 0.0.0.0                                          
udpLocalAddress.0.0.0.0.50003 = 0.0.0.0                                         
udpLocalAddress.9.42.103.27.1029 = 9.42.103.27                                  
udpLocalPort.0.0.0.0.161 = 161                                                  
udpLocalPort.0.0.0.0.514 = 514                                                  
udpLocalPort.0.0.0.0.4001 = 4001                                                
udpLocalPort.0.0.0.0.50003 = 50003                                              
udpLocalPort.9.42.103.27.1029 = 1029                                            
udpEndpointProcess.0.0.161.0.0.0.33 = 0                                         
udpEndpointProcess.0.0.514.0.0.0.28 = 0                                         
udpEndpointProcess.0.0.4001.0.0.0.44 = 0                                        
udpEndpointProcess.0.0.50003.0.0.0.70 = 0                                       
udpEndpointProcess.1.4.9.42.103.27.1029.0.0.0.67 = 0                            
udpEndpointProcess.2.0.4002.2.16.32.1.13.184.0.0.0.0.0.0.0.0.0.0.0.1.9002.45 = 0
udpEndpointProcess.2.16.255.1.0.0.0.0.0.0.0.0.0.0.0.0.1.0.5003.0.0.0.46 = 0

Walking the tree using bulkwalk

The following returns by name all objects beginning with the same object identifier prefix, but with fewer data packages to be exchanged between the snmp command and the SNMP agent.

The bulkwalk request type is an SNMPv2 function. The -h parameter identifies a host, loopback, defined in the OSNMP.CONF file as an agent that supports SNMPv2 or SNMPv3.

snmp -h loopback -v -m 10 bulkwalk udp      

udpInDatagrams.0 = 2125                
udpNoPorts.0 = 7                       
udpInErrors.0 = 0                      
udpOutDatagrams.0 = 2132               
udpLocalAddress.0.0.0.0.161 = 0.0.0.0  
udpLocalAddress.0.0.0.0.514 = 0.0.0.0  
udpLocalAddress.0.0.0.0.4001 = 0.0.0.0 
udpLocalAddress.0.0.0.0.50009 = 0.0.0.0                                         
udpLocalAddress.9.42.103.27.1030 = 9.42.103.27                                  
udpLocalPort.0.0.0.0.161 = 161                                                  
udpLocalPort.0.0.0.0.514 = 514                                                  
udpLocalPort.0.0.0.0.4001 = 4001                                                
udpLocalPort.0.0.0.0.50009 = 50009                                              
udpLocalPort.9.42.103.27.1030 = 1030                                            
udpEndpointProcess.0.0.161.0.0.0.34 = 0                                         
udpEndpointProcess.0.0.514.0.0.0.36 = 0                                         
udpEndpointProcess.0.0.4001.0.0.0.44 = 0                                        
udpEndpointProcess.0.0.50010.0.0.0.80 = 0                                       
udpEndpointProcess.1.4.9.42.103.27.1031.0.0.0.78 = 0                            
udpEndpointProcess.2.0.4002.2.16.32.1.13.184.0.0.0.0.0.0.0.0.0.0.0.1.9002.45 = 0
udpEndpointProcess.2.16.255.1.0.0.0.0.0.0.0.0.0.0.0.0.1.0.5003.0.0.0.46 = 0     
udpHCInDatagrams.0 = 2125                                                       
udpHCOutDatagrams.0 = 2132

Getting multiple MIB variables
The following requests multiple MIB objects using the getbulk request type. The getbulk request type returns the next logical object for one or more MIB objects listed on the command. In the following example, the -n option indicates that only one next logical object is requested for the first two variables (sysObjectId and ifNumber). For all other objects in the list (ifName, ifHCInOctets, ifHCOutOctets), the -m option indicates that 5 repetitions are requested. As a result of this command, the following SNMP data is returned:
- sysObjectId - the SNMP OID (object identifier) that identifies the agent
- ifNumber - the total number of interfaces defined to the TCP/IP stack with which the agent is associated
- The ifName, ifHCInOctets, and ifHCOutOctets values for the first 5 interfaces defined to the stack
The getbulk request type is an SNMPv2 function. The -h parameter identifies a host, loopback, defined in the OSNMP.CONF file as an agent that supports SNMPv2 or SNMPv3.
```
snmp -h loopback -v -n 2 -m 5 getbulk sysObjectId ifNumber ifName ifHCInOctets ifHCOutOctets

sysObjectID.0 = 1.3.6.1.4.1.2.3.13   
ifNumber.0 = 31                      
ifName.1 = LOOPBACK     
ifHCInOctets.1 = 108028 
ifHCOutOctets.1 = 108028
ifName.2 = LOOPBACK     
ifHCInOctets.2 = 107868 
ifHCOutOctets.2 = 107868
ifName.3 = LOOPBACK6    
ifHCInOctets.3 = 160    
ifHCOutOctets.3 = 160   
ifName.4 = LCS1         
ifHCInOctets.4 = 0      
ifHCOutOctets.4 = 0     
ifName.5 = TR1          
ifHCInOctets.5 = 0      
ifHCOutOctets.5 = 0     
     
```
Finding the name of an ASN.1 variable
The following sends a request that a search be done to obtain the textual name, for a given mib_variable input, whose internal ASN.1 value best matches the input ASN.1 value. The search begins with the MIBS.DATA file and, if not found, continues with the compiled MIB. Only one mib_variable is allowed per snmp findname command invocation:
```
snmp findname 1.3.6.1.2.1.6.13.1.2
1.3.6.1.2.1.6.13.1.2 found as: tcpConnLocalAddress
```
```
snmp findname 1.3.6.1.2.1.6.13.1.2.0
1.3.6.1.2.1.6.13.1.2.0 found as: tcpConnLocalAddress.0
```
```
snmp findname 1.3.6.1.2.
1.3.6.1.2. found as: mgmt
```
Sending requests with the physical interface address as originating address:
By default, the snmp command no longer sets the SO_IGNORESOURCEVIPA socket option to force the originating address in the request packet to be that of the physical interface over which the packet is sent. A source VIPA address, if one is configured, is used instead. To cause the snmp command to use the physical address instead, the -a option can be specified. This implies that the SNMP agent receiving the request must be configured to accept requests from the physical interface address rather than the source VIPA address.
To have the snmp command use the physical interface address as the originating address, use the -a parameter on the snmp command:
```
   snmp -a get sysUpTime.0
   1.3.6.1.2.1.1.3.0 = 2950600
```
Alternately, if an entry exists in the OSNMP.CONF file for hostA that specifies NOSVIPA, the following command would achieve the same results:
```
   snmp -h hostA get sysUpTime.0
   1.3.6.1.2.1.1.3.0 = 2950600	
```