Skip to Content
Information
Unsupported content This version of the documentation is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.

Basic Agent configuration file

The agent configuration file controls several aspects of agent operation. Those aspects peculiar to SNMPv2 are covered in a later section. The ones with generic applicability are covered here, and fall into the following categories:

  • Initial values for sysContact and sysLocation
  • Community-based access control
  • Community-based naming
  • Trap destinations
  • Choice of transport protocols
  • Subagent access control
  • Subagent protocol parameters
  • Relationship of subagents to community-based naming

The remainder of this section, through descriptions of the configuration file grammar and examples, shows how you can use the agent configuration file to meet your needs. The MultiMIB Agent and Optima OptiMaster releases 1.6 and later do accept the more limited configuration file used by toolkit releases 1.5d and earlier.

For background information, see RFC 1157 for an extensive discussion of how community-based SNMP access control works. A number of concepts from SNMPv2 are used here, even when SNMPv2 protocol is not in use. For background information, see RFC 1445, Administrative Model for version 2 of the Simple Network Management Protocol (SNMPv2).

Initial values for sysContact and sysLocation

The INITIAL directive allows you to specify the initial values for the sysContact and sysLocation variables from MIB-II. The grammar for an initialization directive is as follows:

INITIAL <varName> <string>
<varName> ::= sysLocation | sysContact

If the string contains spaces, line breaks, tabs, and so on, it must be enclosed in quotes. You may also specify the value in hexadecimal notation. The configuration file processing routines handle mapping <CR> and <LF> characters into NVT (Network Virtual Terminal) strings. See RFC 854 for a specification of the NVT conventions.

Note that these directives have an effect only when the agent is started with a non-existent non-volatile memory file. Changing the values in the configuration file and forcing the file to be re-read using a HUP signal does not change the values of the MIB variables in order to avoid confusing any managers which may have reconfigured those variables.

The following example illustrates the use of the INITIAL directive in a configuration file.

INITIAL sysLocation "Computer Room A
1190 Saratoga Avenue Suite 130
San Jose, CA 95129-3343
USA"

INITIAL sysContact "Patrick Rockecharlie
Email: <patrick_rockecharlie@peer.com>
Voice: +1 408 556-0720
Fax: +1 408 556-0735"

The actual values you select will be specific to each system. If no INITIAL directive is present for a variable, the default value chosen by the agent is the empty string unless you customize the startup code in module system.c in the following directory: agent/snmpsm/src/wrk.

Identifying transport mappings

The master agent may use multiple interfaces for SNMP and SMUX traffic. Each interface the master agent uses for listening for SNMP packets or SMUX connections requires one TRANSPORT definition in the configuration file. If no transport definitions are present, the defaults are used. If any SNMP transport mappings are present in the configuration, the default is not assumed.

Each transport mapping describes an interface over which the master agent listens for SMUX connections from subagents or SNMP requests from managers.

Subagents do not derive SMUX transport mappings from the agent configuration file. When a subagent calls mgmt_init_env() to initialize its management environment, if the first parameter is NULL, the SMUX port number to send to is derived from the TCP/IP stack's /etc/services file, or equivalent; if no SMUX port number is specified in this file, the port number specified in the file include/ame/portnums.h is used.

The syntax for the TRANSPORT clause in the agent configuration file is shown below. When appl_protocol is SNMP, transport_protocol defaults to UDP. If appl_protocol is SMUX, transport_protocol defaults to TCP. The IP address in f addr defaults to that of the master agent's host. The IP port number defaults as described above.

The syntax for the TRANSPORT clause in the agent configuration file looks like this:

TRANSPORT <name> SNMP

[OVER UDP SOCKET]
[AT <addr>]

TRANSPORT <name> SMUX
[OVER TCP SOCKET]
[AT <addr>]

addr ::= <ip-kind> | <rfc1449addr> | <full-ip> ip-kind ::= <hostid> | <hostid> <portid> | <portid>

hostid ::= <hostname> | <ip>

portid ::= PORT | : ] <#>

full-ip ::= <ip>:<#>
ip ::= <#>.<#>.<#>.<#>

rfc1449addr ::= <ip>/<#>

Note that there are many ways to enter an IP address.

The following example configures a master agent to accept SMUX connections at both the standard port and at a non-standard port. It also configures the agent to accept SNMP traffic only at a non-standard port.

TRANSPORT extraordinary SNMP
 OVER UDP SOCKET
 AT PORT 11161

TRANSPORT ordinary SMUX
 OVER TCP SOCKET
 AT PORT 199

TRANSPORT special SMUX
 OVER TCP SOCKET
 AT PORT 11199

The maximum number of concurrent SNMP and SMUX transports will be limited by your target system's limits on the number of open sockets or file descriptors per process.

Using community strings

Community strings serve many functions in SNMP. Their most common use is to provide a weak form of authentication. In this capacity, they are part of the access control framework for SNMP. They are also used to help name pieces of information in the network. The following example of how communities can be used may be helpful:

  • At IP address 192.146.153.65 at port 161, using community string "public", the value of {sysContact 0} is "Fred", and only read access is permitted.
  • At IP address 192.146.153.65 at port 161, using community string "RenMinRiBao", the value of {sysContact 0} is "Fred", but both read and write access are permitted.
  • At IP address 192.146.153.65 at port 161, using community string "subsystem1", the value of {sysContact 0} is "Joe", and only read access is permitted.

In this example, two of the community strings provide access to the same information, but with different access control policies. This third community string provides access to another set of information. Note that the manager requires external knowledge to determine whether the first two refer to the same information or to two different pieces of information that happen to have the same value.

A community string may be thought of as a key into a database table with the following information:

  • Spatial Semantics: which set of information (where a system may have multiple instances of the same information classes)
  • Temporal Semantics: when was the information retrieved or when will changes take effect (there may be caching, changes may require a reboot to take effect, and so on.)
  • Access Control Policy: who is allowed to use this information? What operations are allowed?

By now it must be clear that the community string is seriously overloaded. To support all the semantics carried by community strings, there are several configuration file entries.

COMMUNITY entries determine which community strings are valid. If no COMMUNITY entries are present, any community will be accepted by the agent. For each community, the set of supported operations is specified by the ALLOW clause. The MEMBERS clause in a community entry restricts the set of managers allowed to use that community. If the MEMBERS clause is absent from a COMMUNITY entry, any manager may use that community.

<communityDefinition>::=COMMUNITY <communityName>
ALLOW <op> [,<op>]* [OPERATIONS]
AS ENTITY <entityName>]
MEMBERS <addr> [,<addr>] ]

<communityName> ::= <name>
<op> ::= ALL | GET | SET | TRAP | RESPONSE | GET-NEXT | GET-BULK | INFORM | NOTIFY

The ALL keyword serves as a shorthand for listing the possibilities.

The optional AS ENTITY clause provides any naming semantics associated with this community. An entity definition associates spatial/temporal properties with a label. The spatial/temporal entity is defined using the following grammar:

<entityDefinition> ::= ENTITY <EntityName>
DESCRIPTION <String>
WITH TIME DOMAIN <oid>]

<entityName> ::= <name>

The following example shows how a system might be configured to provide read-only and read-write access both to its standard resources and a special subsystem:

ENTITY SpecialSubsystem
DESCRIPTION "The ultra-enhanced subsystem"

COMMUNITY public
ALLOW GET OPERATIONS

COMMUNITY public1
ALLOW GET OPERATIONS
AS ENTITY SpecialSubsystem

COMMUNITY "YingXio'ng"
ALLOW ALL OPERATIONS

COMMUNITY "Jia-oTo-ng"
ALLOW ALL OPERATIONS
AS ENTITY SpecialSubsystem
MEMBERS bigboss.megalith.com, 192.146.153.65

Thus, to access information from the "ultra-enhanced subsystem", a manager would have to use either community "public1" or "Jia-oTo-ng". Using community "public" or "YingXio'ng" would access the default spatial-temporal entity. Furthermore, use of the community "Jia-oTo-ng" is restricted to operations with a source address from system "bigboss.megalith.com" or 192.146.153.65; operations with any other source address would not be accepted with this community.

Note the close relationship between the community-to-entity mapping and the subagent-to-entity association described in the section on controlling subagent communications, and how to use it to extend SNMP naming by community string.

To avoid unintended access, be sure the ENTITY, COMMUNITY and ALLOW/DENY SUB_AGENT specifications are complete; that is, taken together, the definitions in the configuration file must cover all aspects of the configuration.

Controlling trap destinations

MANAGER entries in the configuration file define SNMP trap destinations. Destinations specified in this manner are independent of destinations specified by means of the SNMPv2 party MIB.

<trapDestination> ::= MANAGER <addr>
[ON TRANSPORT <transportName>]
[SEND [ALL | NO] TRAPS
[TO PORT <#> ]
[WITH COMMUNITY <String>]]

See previous text for a description of the meaning of transportName. If it is not supplied, whatever is being used for primary SNMP traffic will be used.

If the PORT clause is not supplied, snmp-trap from your systems /etc/services or whatever you have built into the agent by editing include/ame/portnums.h will be used.

If the COMMUNITY clause is absent, the community string "public" will appear in the traps that are sent.

The following example requests that all traps be sent to manager "fred" at both port 162 and 11162, from the non-standard snmp port defined above, using a community string of "deep dark secret".

MANAGER fred ON TRANSPORT extraordinary
SEND ALL TRAPS TO PORT 162
WITH COMMUNITY "deep dark secret"
SEND ALL TRAPS TO PORT 11162
WITH COMMUNITY "deep dark secret"

The number of trap destinations is limited only by available memory.

Reloading the configuration file

Under UNIX, the agent may be told to re-read its configuration file by giving the agent process a HUP signal. Under Windows, the master agent's window has a menu item to reload the file. This allows you to change access restrictions without stopping/restarting the agent. Error messages go to the agent's stderr, which is not necessarily the same as that of the UNIX process issuing the HUP signal. This action causes the agent to issue a warm start trap, if traps are enabled in the agent configuration file.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*

BMC PATROL Agent 9.5