SNMP Agent Administration Guide

BEA SNMP Agent Integrator Commands

The following sections explain the commands and utilities used for the BEA SNMP Agent Integrator:

Commands

reinit_agent

Syntax

reinit_agent all | logical_agent_name [logical_agent_name]

Description

Causes the specified agents to re-read their configuration file. This utility must be run with root permissions. Using the all argument causes all SNMP agents to re-initialize. For all SNMP agents other than tux_snmpd, logical_agent_name is the name of the executable.
For example, the command:
reinit_agent snmp_integrator
causes the BEA SNMP Agent Integrator to re-read its configuration file.

snmp_integrator

Syntax

snmp_integrator [-d] [-n] [-p port | -r smux_port] [-bipaddr_list | hostname_list ]

Arguments

-d

Causes the program to display a message for each SNMP/SMUX packet sent or received.

-n

The program is not run as a daemon (UNIX only).

-p port

Specifies the UDP port on which the BEA SNMP Agent Integrator listens for SNMP requests (default: 161/udp).

-r smux_port

Specifies the TCP port used to communicate with SMUX subagents (default: 199/tcp).

-b ipaddr_list | hostname_list

If the machine where the BEA SNMP Agent Integrator is running has multiple IP addresses, by default the BEA SNMP Agent Integrator listens on all IP addresses. The -b option can be used to specify a subset of IP addresses to monitor for incoming SNMP requests.

ipaddr_list

Can consist of a single IP address or a blank-separated list of IP addresses.

hostname_list

Can consist of one host name or a blank-separated list of host names.

For example, if the machine on which the BEA SNMP Agent Integrator is running has the following IP addresses:

130.86.34.3 130.86.33.13 130.86.23.1

you can configure the BEA SNMP Agent Integrator to only service requests addressed to 130.86.23.1 by starting it with the following command:

snmp_integrator -b 130.86.23.1

Description

The snmp_integrator file is the SNMP BEA SNMP Agent Integrator executable. It allows multiple SNMP agents and SMUX subagents from any vendor to coexist on the same node and to appear as a single SNMP agent to any SNMP manager.

The BEA SNMP Agent Integrator can simultaneously support any number of:

SNMP agents
SMUX subagents
Master agents such as other SMUX or DPI master agents or any other proprietary master agents. (The master agent must respond to requests from a manager using SNMP.)

Also, the BEA SNMP Agent Integrator can coexist on the standard SNMP port (161/udp) with any other SNMP agent. It directly supports the SMUX MIB (RFC 1227) in addition to the MIB-II system(1) and snmp(3) groups.

When the program is running as an SNMP agent, it generates a coldStart trap to the host specified by the TRAP_HOST entry in the beamgr.conf file at startup. If there is no TRAP_HOST entry, the trap is sent to UDP port 162 on the host where the utility is running, with a community defined as public.

Read-write and read-only communities supported by the BEA SNMP Agent Integrator can be specified in the beamgr_snmpd.conf file. By default, read-only community is public and read-write community is iview.

Using the beamgr_snmpd.conf file, you can configure the BEA SNMP Agent Integrator to expect a password from SMUX subagents that register with it.

On Windows Systems

Messages displayed with the -d argument are sent to the Event Log.

The -n argument has no effect.

On UNIX Systems

The -d argument is usually used for debugging purposes when the program is executed on the command line. Messages displayed are sent to the standard output of the program. If the program is started by init(1M), the destination of these messages is determined by the UNIX platform and version. These messages are most frequently sent to the console.

The -n argument is usually used when the program is started by init(1M) with the respawn option.

stop_agent

Syntax

stop_agent logical_agent_name | all [logical_agent_name]

Arguments

all

Stops all SNMP agents.

logical_agent_name

For all SNMP agents other than tux_snmpd, the logical agent name is always the name of the executable.

show_agent

Syntax

show_agent all | logical_agent_name [logical_agent_name]

Description

Lists the names and PIDs of all the running agents and requested agents.

BEA SNMP Agent Utilities

The BEA SNMP Agent software provides the following utilities to help you install and test an agent or subagent:

`instsrv`	Installs an agent as a Windows service.
`snmpget`	Reports information about scalar managed objects.
`snmpgetnext`	Returns the next consecutive managed object in a MIB.
`snmptest`	Selectively performs Get, GetNext, and Set operations on any MIB object.
`snmptrap`	Sends an SNMP trap message to a host.
`snmptrapd`	Receives and logs SNMP trap messages sent on a local machine to the snmp-trap port.
`snmpwalk`	Traverses the OID tree using the SNMP GetNext request to query managed objects.

instsrv

Purpose

Used to install any module built as a Windows service under a specified name. For example, use it to reinstall the BEA SNMP Agent Integrator in a multi-version environment after uninstalling one of the versions. Applies to Windows systems only (not UNIX systems).

Synopsis

instsrv service_name [executable_file | remove]

Enter an executable_file to create a service. Enter remove to remove a service.

For example:

instrsrv snmp_integrator c:\tux81\bin\snmp_integrator.exe

Arguments

service_name

The name of the service.

executable_file

The complete path to the executable file.

snmpget

Purpose

Reports information about scalar managed objects.

Synopsis

snmpget [-d] [-p port] host community variable_name [variable_name ...]

Arguments

-d

Causes the program to display a message for each packet.

-p port

Specifies the UDP port used to communicate with the SNMP agent (default: 161).

host

The internet address or host name of the node executing the SNMP agent to be queried.

community

The community name for the transaction.

variable_name

At least one unique object identifier (OID).

Description

The snmpget utility uses SNMP Get requests to retrieve information about managed objects. You can enter one or more object identifiers as arguments on the command line. These names can be absolute, starting from the root of the tree, or relative to .iso.org.dod.internet.

Environment Variables

BEA_SM_SNMP_MIBFILE

Must be set to specify the path to mib.txt, which provides an ASCII text description of the contents of your private MIB.

Examples

The following command sends a query to the SNMP agent running on the host named topaz, using public as the community for authorization. The agent retrieves the value of the managed object beaSysHasDisk in the BEA private MIB. Note that in this example, a relative OID (private.enterprises.bea.beaSystem) is specified. .iso.org.dod.internet. is prepended to generate an absolute path.

snmpget topaz public private.enterprises.bea.beaSystem .beaSysHasDisk.0

This command returns the following information about the object:

Name: private.enterprises.bea.beaSystem.beaSysHasDisk.0 INTEGER: yes(2)

The following command sends a query to the SNMP agent running on the host named ruby, using public as the community for authorization. The agent retrieves the value of the managed objects sysDescr and sysUptime in the MIB.

snmpget ruby public mgmt.mib.system.sysDescr.0 mgmt.mib.system.sysUpTime.0

This command returns the following information:

Name: mgmt.mib.system.sysDescr.0 OCTET STRING- (ascii): Kinetics FastPath2

Name: mgmt.mib.system.sysUpTime.0 Timeticks: (2270351) 6:18:23

snmpgetnext

Purpose

Returns the next entry in a table or the next consecutive managed object in a MIB.

Synopsis

snmpgetnext [-d] [-p port] host community variable_name [variable_name ...]

Arguments

-d

Causes the program to display a message for each packet.

-p port

Specifies the UDP port used to communicate with the SNMP agent (default: 161).

host

The internet address or host name of the node executing the SNMP agent to be queried.

community

The community name of the transaction.

variable_name

At least one unique object identifier (OID).

Description

You can enter one or more object identifiers as arguments on the command line. These names can be absolute, starting from the root of the tree, or relative to .iso.org.dod.internet.

Environment Variables

BEA_SM_SNMP_MIBFILE

Must be set to specify the path to mib.txt, which provides an ASCII text description of your private MIB.

Examples

This example contacts the host named blueberry using the community name public and retrieves the value of the instance immediately following mgmt.mib.interfaces.ifTable.ifEntry.ifOutOctets.0 from the MIB:

snmpgetnext blueberry public mgmt.mib.interfaces.ifTable.ifEntry .ifOutOctets.0

Note that the instance index .0 must be appended to the end of the OID to refer to the value of the object.

The output of the previous command might look like this:

Name: mgmt.mib.interfaces.ifTable.ifEntry.ifOutOctets.1 COUNTER: 85655250

You could then enter a command that retrieves information about the next variable:

snmpgetnext blueberry public mgmt.mib.interfaces.ifTable.ifEntry .ifOutOctets.1

snmptest

Purpose

Selectively performs Get, GetNext, and Set operations on any MIB object.

Synopsis

snmptest [-d] [-p port] host community

Arguments:

-d

Causes the program to display a message for each packet.

-p port

Specifies the UDP port used to communicate with the SNMP agent (default: 161).

host

The internet address or host name of the node executing the SNMP agent to be queried.

community

The community name of the transaction.

Description

When this program is executed, it prompts you to enter an OID. The snmptest utility returns information about request and reply packets as well as the name and type of the object.

By default, the program sends a Get request packet. This can be changed by entering a value from the following table at the prompt.

Command	Request Type
`$G`	Get
`$N`	GetNext
`$S`	Set

If you choose the Set request mode, the program prompts you for a variable type from the following list.

Variable Type	Description
`a`	IP address.
`d`	Octet string as decimal bytes separated by white space (that is, 105 118 105 101 119)
`i`	Integer
`n`	Null value
`o`	Object identifier
`s`	Octet string in ASCII (that is, `bea`)
`t`	Time ticks
`x`	Octet string as hexadecimal bytes separated by white space (for example, 69 76 69 65 77)

After you specify the request type, the program prompts you to enter a value of the type you just specified. At this prompt, enter the integer (in decimal) or enter a string and press Enter. To send the request packet, press Enter again at the next prompt.

To quit the program, enter:

$Q

Environment Variables

BEA_SM_SNMP_MIBFILE

Must be set to specify the path to mib.txt, which provides an ASCII text description of your private MIB.

Examples

Start the program by entering the command:

snmptest topaz public

The program responds with:

Please enter the variable name:

Enter a variable name and press Enter:

private.enterprises.bea.beaEm.beaEmMonitorTimer.0

The program requests another variable name:

Please enter the variable name:

You can either enter another variable name, or press Enter to see the result. When you press Enter, the program displays the result of the test:

Received GET RESPONSE from 192.84.232.47 requestid 0x775efba0 errstat 0x0 errindex 0x0 Name: private.enterprises.bea.beaEm.beaEmMonitorTimer.0 INTEGER: 5000

After displaying the result, you can enter another variable name, or $Q to quit the program.

Please enter the variable name: $Q

If you enter $Q, a quit message appears:

Quitting, Good-bye

snmptrap

Purpose

Sends an SNMP trap message to a host.

Synopsis

snmptrap [-a agent_addr] [-d] [-p port] host community trap_type specific_trap variable_binding_value

Arguments

-a agent_addr

Specifies an originating address, if it is different from that of the host, where snmptrap is executed. This argument enables you to send a trap on behalf of another host.

-d

Causes the program to display a message for each packet.

-p port

Specifies the UDP port to which the SNMP trap should be sent on the target host (default: 162).

host

The Internet address or name of the host to which the SNMP trap is to be sent.

community

The community name of the transaction.

trap_type

An integer that specifies the generic type (in the range 0 to 6) of the trap to be sent.

specific_trap

An integer that identifies the enterprise-specific trap that occurs when trap_type is set to generic trap type 6.

variable_binding_value

Information to be transported within the trap packet. The program uses this as the value in the variable binding list when it sends the trap.

Description

The following table defines the valid (generic) trap types.

Name of Trap Type	Generic Trap Number	Description
`coldStart`	0	The sending agent is re-initializing itself, typically due to a reboot.
`warmStart`	1	The sending agent is re-initializing itself, typically due to a normal restart.
`linkDown`	2	One of the communication links on the agent node has failed. The first element in the variable bindings contains the name and value of the ifIndex instance for the downed interface.
`linkUp`	3	One of the communication links on the agent node has come up. The first element in the variable bindings contains the name and value of the ifIndex instance for the affected interface.
`authenticationFailure`	4	The agent is reporting it has received a request with an invalid community specification or a community with insufficient permissions to complete the request.
`egpNeighborLoss`	5	The agent is reporting that the peer relationship between an External Gateway Protocol (EGP) neighbor and an EGP peer no longer exists.
`enterpriseSpecific`	6	The sending agent is reporting that an enterprise-specific event has occurred. The value of the `specific-trap` field indicates the nature of the event.

The trap generated by this tool has a fixed variable-binding list that contains only one object-value pair. The object is:

.iso.org.dod.internet.private.enterprises.bea.beaSystem. beaTrapDescr.0

The value of this object can be specified in the variable-binding-value argument.

The enterprise field, which is part of the SNMP trap PDU header, is always:

.1.3.6.1.4.1.140.1.1

which is equivalent to:

.iso.org.dod.internet.private.enterprises.bea.beaSystem. sysDescr

Examples

The following command sends a coldStart trap to the host named topaz, using public as the community for authorization. Note that a value for the specific-trap argument must be present, even though it is ignored when the value of the trap-type argument is not 6 (enterpriseSpecific).

snmptrap topaz public 0 1 "host xyz is booting"

snmptrapd

Purpose

Receives and logs SNMP trap messages sent to the snmp-trap port.

Synopsis

snmptrapd [-d] [ -l port ] [-p]

Arguments

-d

Causes the program to display a debug message for each packet.

-l port

Specifies the UDP port to use when listening for incoming trap packets (default: 162).

-p

Causes the program to print trap information output to the standard output.

Environment Variables

BEA_SM_SNMP_MIBFILE

Must be used to specify the path to mib.txt, which provides an ASCII text description of your private MIB.

Description

This utility receives SNMP traps sent on the UDP port specified by the -l argument. If no port is specified, it uses port number 162. This utility must be able to open the snmp-trap port, which usually requires root permissions.

On UNIX platforms, if the -p argument is not specified, snmptrapd uses the UNIX syslog utility to log messages with a status of WARNING. If the LOG_LOCAL0 facility is available, it is used instead of syslog or snmptrapd.

On Windows systems, if the -p argument is not specified, the Event Log is used to log WARNING messages.

Examples

This command collects the incoming SNMP trap sent by another host, and displays it to standard output:

snmptrapd -p

When the host receives the trap, it displays the following information:

192.84.232.47: Cold Start Trap (0) Uptime: 0:00:00 Name: private.enterprises.bea. beaSystem.beaTrapDescr.0 OCTET STRING- (ascii): host xyz is booting

snmpwalk

Purpose

Traverses the OID tree using the SNMP GetNext request to query managed objects.

Synopsis

snmpwalk [-d] [-p port] host community [variable_name ...]

Arguments

-d

Causes the program to display a message for each packet.

-p port

Specifies the UDP port used to communicate with the SNMP agent (default: 161).

host

The host name or an Internet address, in "dot-dot" notation (that is, separated with periods), where the SNMP request is to be sent.

community

The community name to use in the SNMP request.

variable_name

The unique object identifier, expressed symbolically, decimally, or as a combination of both. If you do not specify a variable name, snmpwalk searches the entire MIB.

Description

This utility traverses the OID tree from the object specified on the command line. You can enter one or more object identifiers as arguments on the command line. These names can be absolute, starting from the root of the tree, or relative to .iso.org.dod.internet. If no objects are specified, snmpwalk searches the entire MIB tree supported by the SNMP agent.

Environment Variables

BEA_SM_SNMP_MIBFILE

Must be used to specify the path to mib.txt, which provides an ASCII text description of your private MIB objects.

Diagnostics

If the tree search causes the program to search beyond the end of the MIB, this message appears:

End of MIB

Examples

This is an example of an snmpwalk command:

snmpwalk blueberry public private.enterprises.bea.beaSystem

This is some of the output generated from the command:

Name: private.enterprises.bea.beaSystem.beaSysSysname.0 OCTET STRING- (ascii): SunOS

Name: private.enterprises.bea.beaSystem.beaSysNodename.0 OCTET STRING- (ascii): blueberry

SNMP Request Format

BEA SNMP Agent utilities use SNMP requests to query SNMP agents for information about managed objects. Refer to RFC 1157 (SNMP) for more information about the format of SNMP requests. For information about locating RFCs on the Internet, see SNMP Information.

MIB Variable Definition Files

When a MIB variable is used with a BEA SNMP Agent utility, the utility attempts to convert the variable to a numeric OID by searching first in a file named mib.txt in the current directory, then in a file specified in the environment variable BEA_SM_SNMP_MIBFILE, and finally in the tux_prod_dir\udataobj\snmp\etc\mib.txt file on a Windows system, or tux_prod_dir/udataobj/snmp/etc/mib.txt file on a UNIX system. These files should use ASN.1 notation and use the OBJECT TYPE macro defined in RFC 1155 (Structure of Management Information).

The mib.txt file describes the RFC 1213 (MIB-II) and the BEA private MIB objects.