Chapter 7. Configuration Files

This chapter describes the configuration files used with the Agent Integrator and other BEA Manager SNMP products. It includes the following sections:

"BEA Manager Configuration File (beamgr.conf)" describes beamgr.conf, which is the configuration file for the Agent Integrator and other BEA Manager applications.
"BEA Manager Passwords File (beamgr_snmpd.conf)" describes beamgr_snmpd.conf, which contains the community strings used as passwords in communication between managers and agents, and passwords used in communication with SMUX subagents. This file is separate from the beamgr.conf file because it should be secured with read and write access permitted for root only. This file is used by the subagents shipped with the Agent Integrator (or subagents generated using the BEA Manager Agent Development Kit) when they are run as standalone agents. This file is also used by the Agent Integrator master agent and the agents shipped with the Agent Connection.

BEA Manager Configuration File (beamgr.conf)

beamgr.conf is the configuration file for the Agent Integrator and other BEA Manager applications.

Default Location

On UNIX systems: /etc/beamgr.confOn Windows NT systems: C:\etc\beamgr.conf

Description

The beamgr.conf file contains information used by the BEA Manager products (including Agent Integrator, Agent Connection, and Log Central) and the SNMP agents and SMUX subagents created using the BEA Manager Agent Development Kit. The location of this configuration file may be specified by the environment variable BEA_SM_BEAMGR_CONF. A configuration entry is composed of two or more blank or tab-separated fields:

KEYWORD parameters

If an entry happens to be too long, the backslash (\) character can be used as a continuation character at the end of the line. There should be a newline character immediately following the \ character.

The following keywords have corresponding MIB objects: TMEVENT_FILTER, SYS_INSTALL, SYS_CONTACT, SYS_NAME, SYS_LOCATION, SYS_SERVICES, and RULE_ACTION.

NON_SMUX_PEER port community|* OID_Node[,ro|rw][,priority][,timeout] ...

The explanation of the terms used in the previous entry follows.

NON_SMUX_PEER

Is the keyword for the entry.

port

Specifies the UDP port number on which the SNMP agent is listening. This value can be specified in the forms:

ip_address.port hostname.port

when the SNMP agent is remote from the Agent Integrator. If ip_address or hostname is not specified, the Agent Integrator assumes that the peer SNMP agent is on the same managed node as the Agent Integrator.

community

Specifies the community to be used by the Agent Integrator when the SNMP agent is polled. The special value * is used to specify that the Agent Integrator should use the community supplied by the SNMP manager.

OID_Node

Specifies the OID of the root of the MIB tree that is supported by this SNMP agent.

ro|rw: Specifies whether this OID tree is being exported as read-only or as read-write. The default is rw.
priority: Is a positive number that specifies the priority at which the OID tree is being exported. The lower the number, the higher the priority. If there are multiple agents/subagents supporting the same MIB tree, the subagent with the highest priority is consulted. Multiple SNMP agents and SMUX subagents may register the same subtree. However, they must do so at different priorities.; If an SNMP agent tries to register a subtree at a priority that is already taken, the Agent Integrator repeatedly increments the integer value (lowering the priority) until an unused priority is found. A special priority -1, causes the selection of the highest available priority. When a request is made to register with priority -1, registration is made at the highest available number below 20. If the priority field is missing, the MIB tree is exported at a -1 priority.
timeout: Specifies the time interval in seconds for which the Agent Integrator waits for the replies from this SNMP agent for the particular MIB group. The default value is three seconds. This default may be changed by setting the BEA_PEER_MAX_WAIT environment variable to a different value.

The access (ro or rw), priority, and timeout fields are optional. But you must specify access and priority if you wish to specify timeout, and you must specify access if you wish to specify priority for a MIB tree.

Multiple OID nodes can be listed.

Note: A subtree registration will hide the registrations by other SNMP agents/subagents of objects within the subtree. So, if an agent A registers subtree .1.3.6.1.4.1.140 and another agent/subagent, B, registers subtree .1.3.6.1.4.1.140.1, agent/subagent A will be consulted for all the objects under the .1.3.6.1.4.1.140.1 subtree.

Also, when the Agent Integrator reads this entry, an SNMP agent should be running on the specified port. Otherwise, the Agent Integrator disregards this entry. Also, if three consecutive requests to this SNMP agent time out, it is assumed that the SNMP agent specified by this entry is no longer alive and this entry is disregarded.

At any point, the utility reinit_integrator can be used to force the Agent Integrator to re-read its configuration file.

The Agent Integrator will disallow/disregard any attempt to register above, at, or below the SNMP (mib2.snmp) and SMUX subtrees of the MIB.

NON_SMUX_PEER Examples

Consider the following sample entries in the beamgr.conf file:
```
NON_SMUX_PEER 2001 snmp .1.3.6.1.2.1.1,ro
NON_SMUX_PEER 2002 squid .1.3.6.1.4.1.141 .1.3.6.1.4.1.145
NON_SMUX_PEER 2008 * .1.3.6.1.4.1,ro
NON_SMUX_PEER 2005 * .1.3.6.1.4.1.140 .1.3.6.1.4.1.145,rw
```
The first entry tells the Agent Integrator to look for an SNMP agent at port 2001. All the requests from Agent Integrator to this SNMP agent will use snmp as the community. The agent supports the subtree .1.3.6.1.2.1.1, and is available for read-only commands.
The second entry tells the Agent Integrator to look for an SNMP agent at port 2002. All the requests from Agent Integrator to this SNMP agent will use squid as the community. The agent supports the subtrees .1.3.6.1.4.1.141 and .1.3.6.1.4.1.145. Since no access option is specified, both subtrees default to rw.
The third entry specifies a non-SMUX agent at port 2008 with a community of *. The * tells the Agent Integrator to pass along the same community information it receives from the SNMP manager. For example, if the SNMP manager sends the community nevus, the Agent Integrator sends nevus along to the subagent. (Of course, nevus must be a valid community for the Agent Integrator in the first place.)
The fourth entry lists an agent at port 2005 with a community of *. The agent supports two subtrees: .1.3.6.1.4.1.140 and .1.3.6.1.4.1.145. The first subtree lists no access information, so access defaults to rw. The second subtree specifically lists rw. This means exactly the same thing. The rw could have been left off with no effect.
If the rw is redundant, then why have it at all? Because each OID node can have three arguments: access (ro or rw), priority, and time-out. If you specify any of these arguments, you must also specify all the arguments that come before it. For example, if you specify priority, you must also specify access. If you specify time-out, you must specify both access and priority.
The following entry tells the Agent Integrator to look for an agent at port 2008 with a community of *. The agent supports two subtrees. The first has an access of rw, a priority of -1, and a timeout of two seconds; the second has an access of rw, a priority of -1, and a timeout of ten seconds. Although rw and -1 are the defaults for access and priority, these values must be stated explicitly in order to include a timeout value.
```
NON_SMUX_PEER 2008 * .1.3.6.1.2.1.1,rw,-1,2 .1.3.6.1.2.1.2,rw,-1,10
```
The time-out values are the maximum amount of time the Agent Integrator waits for a response from the SNMP agent for a given object. In this case, two seconds for a response if the object falls under MIB tree .1.3.6.1.2.1.1, and ten seconds for a response if the object falls under the .1.3.6.1.2.1.2 MIB group. The default value is three seconds. This default value can be changed by setting the environment variable BEA_PEER_MAX_WAIT.
The priority value decides which agent is consulted by the Agent Integrator, in the event of a conflict. If more than one agent handles the same object, the one with the lowest number as a priority value is called. In the following entries, the agents on ports 2008 and 2009 both support object .1.3.6.1.2.1.1. The agent at port 2009 has a higher priority (5 is a higher priority than 8), so that is the one the Agent Integrator calls. Notice that this entry specifies rw access. The other entry specifies ro access, but since it has a lower priority, it is completely ignored. As far as the Agent Integrator is concerned, the only agent supporting .1.3.6.1.2.1.1 is at port 2009.
```
NON_SMUX_PEER 2008 * .1.3.6.1.2.1.1,ro,8
NON_SMUX_PEER 2009 * .1.3.6.1.2.1.1,rw,5
```
If you do not specify a priority, the default is -1. The Agent Integrator reads through the file sequentially. When it comes to an object with a -1 priority, it tries to assign it a priority of 20. If 20 has already been assigned to that MIB group (in another entry), it tries to assign 19. It keeps trying each successive lower number until it finds one that is not taken, or until it reaches 0. In that case it gives an error.
In the following entries, the Agent Integrator assigns a priority of 20 to the first entry and a priority of 19 to the second entry. Since 19 is a higher priority, the agent at port 2009 handles object .1.3.6.1.2.1.1 and the first entry is ignored. As before, the access is rw, since the entry specifying ro access is ignored.
```
NON_SMUX_PEER 2008 * .1.3.6.1.2.1.1,ro
NON_SMUX_PEER 2009 * .1.3.6.1.2.1.1
```
The MIB tree .1.3.6.1.2.1.11 is a special case, called mib2.snmp. This MIB group is always handled by the Agent Integrator itself, and should not be exported by any agent or subagent. Any registration at, above, or below this MIB tree is not allowed. For example, none of the following entries is allowed:
```
NON_SMUX_PEER 2005 * .1.3.6.1.2.1
NON_SMUX_PEER 2006 * .1.3.6.1.2.1.11
NON_SMUX_PEER 2007 * .1.3.6.1.2.1.11.7
```
The first includes mib2.snmp, the second specifies it exactly, and the third specifies a part of it.
If an SNMP agent wants to support mib2 (except for the snmp group, as it is not allowed), you need to enter each of the mib2 subtrees explicitly:
```
NON_SMUX_PEER 2002 * .1.3.6.1.2.1.1 .1.3.6.1.2.1.2 .1.3.6.1.2.1.3 \
                     .1.3.6.1.2.1.4 .1.3.6.1.2.1.5 .1.3.6.1.2.1.6 \
                     .1.3.6.1.2.1.7 .1.3.6.1.2.1.8 .1.3.6.1.2.1.9 \
                     .1.3.6.1.2.1.10
```
Note: To continue an entry on another line, use a backslash. Make sure that there are no characters (other than the carriage return) immediately following the backslash.
The Agent Integrator supports row-level registration. Consider a table with five columns and two rows. Each item in the table is a separate object, and can be identified by the column and row identifiers, in that order. The following entry:
```
NON_SMUX_PEER 2000 * .1.3.6.1.4.1.140.100.5.1.2.1
```
specifies row 1 of the second column of table object .1.3.6.1.4.1.140.100.5.1. Row 1 is not necessarily the first row. 1 is simply a unique identifier for the row.
Notice that .1.3.6.1.4.1.140.100.5.1.2 refers to the whole second column. If you want to associate the two rows with different subagents, you need to specify each object in the row:
```
NON_SMUX_PEER 2000 * .1.3.6.1.4.1.140.100.5.1.1.1 .1.3.6.1.4.1.140.100.5.1.2.1 \
                     .1.3.6.1.4.1.140.100.5.1.3.1 .1.3.6.1.4.1.140.100.5.1.4.1 \
                     .1.3.6.1.4.1.140.100.5.1.5.1
```
```
NON_SMUX_PEER 2002 * .1.3.6.1.4.1.140.100.5.1.1.2 .1.3.6.1.4.1.140.100.5.1.2.2 \
                     .1.3.6.1.4.1.140.100.5.1.3.2 .1.3.6.1.4.1.140.100.5.1.4.2 \
                     .1.3.6.1.4.1.140.100.5.1.5.2 
```
The first entry lists the object in row 1 in each of the five columns. The second entry lists the object in row 2 in each of the five columns.

The OID_CLASS Entry

This entry is used by the SMUX subagents created by the Agent Development Kit. The unix_snmpd, nt_snmpd, and pm_snmpd subagents are SMUX subagents created using the Agent Development Kit which are shipped along with snmp_integrator. Normally, SMUX subagents register all the MIB groups they know about with the SMUX master agent. But you may limit the MIB groups exported by these SMUX subagents. In order to do so, you need to add an OID_CLASS entry to beamgr.conf in the following format:

OID_CLASS agent_name OID_Node[,ro|rw][,priority] ..

An explanation of the terms used in the previous entry follows.

OID_CLASS

Is the keyword for the entry.

agent_name

Specifies the name of the SMUX subagent for which this entry is applicable.

OID_Node

Specifies the OID of the tree that is supported by this subagent.

ro|rw: Specifies whether this OID tree is being exported as read-only or as read-write. The default is rw.
priority: Is a positive number that specifies the priority at which the OID tree is being exported. The lower the number, the higher the priority. If there are multiple subagents supporting the same MIB tree, the subagent with the highest priority is consulted. If the priority field is missing, the MIB tree is exported at the highest available priority. This entry is mainly used to limit the OID subtrees being exported by the Agent Integrator or SMUX subagents generated using the Agent Development Kit. If this entry is not present, the SMUX subagent exports all the MIB groups it knows about.

Multiple OID nodes can be listed.

Example

Assume you have a SMUX subagent called my_snmpd. This subagent is created using the Agent Development Kit and supports the MIB groups .1.3.6.1.4.1.140.1, .1.3.6.1.4.1.140.2, and .1.3.6.1.2.1.1. When this subagent starts, it registers all three MIB groups as read-write with the SMUX master agent. If, for example, you want my_snmpd to only export .1.3.6.1.4.1.140.1 as read-only and .1.3.6.1.2.1 as read-write, you would need to insert an entry of the following form:

OID_CLASS my_snmpd .1.3.6.1.4.1.140.1,ro .1.3.6.1.2.1.1

The RULE_ACTION Entry

The BEA Agent Integrator can be configured to do management locally on the managed node and inform the SNMP manager selectively to reduce polling traffic generated by SNMP manager. The user can define rules in terms of MIB objects available locally using a C-like "IF" syntax and accordingly send SNMP traps or execute commands locally (or both). These MIB objects may be the one supported by the Agent Integrator itself or the one supported by one of its SMUX subagents or SNMP agents. For a discussion of RULE_ACTION entries, with examples, refer to Chapter 4, "Using Agent Integrator for Polling."

The configuration is done in the beamgr.conf file. Syntax of the entry looks like following:

RULE_ACTION rule-name frequency_in_secs \
if (VAL(oid) rel_operator value) logical_op ( cond_2 ) ...\
{ \
TRAPID_ERR=enterprise-specific-trapid\
TRAPID_OK=enterprise-specific-trapid\
COMMAND_ERR=executable\
COMMAND_OK=executable\
}