The following files are considered for configuration:
Master Agent resource configuration file
Agents registration file
Agents access control file
Master Agent status file
The Agents Resource Configuration files are used exclusively by the Master Agent. As soon as the Master Agent becomes active, it reads these files. These files store information for all those agents that the Master Agent may manage. Each entry in the configuration files also includes methods for invoking these subagents. Although a subagent might not have a configuration file, the subagent may dynamically register with the Master Agent when it becomes active. More information about dynamic invocation and registration of subagents is described in 3.2 Description of the Subagent.
Each agent may have its own resource configuration file when it opts for invocation by Master Agent and for static registration. This file contains information about the registration file associated with the subagent, in addition to the other information related to invoking the subagent. The agents registration file is described in 4.2 Agents Resource Configuration Files.
The following example shows the grammar for the resource configuration files.
<ResourceFile> : Resource | Environment Resource <Resource> : “resource” “=” “{“ ResourceList “}” <ResourceList> : /*empty*/ | ResourceList ResourceItem <ResourceItem> : “{“ StringList “}” <Environment> : “environment” “=” “{“ EnvironmentList “}” <EnvironmentList> : /*empty*/ | EnvironmentList EnvironmentListItem <EnvironmentListItem> : EnvironmentToken “=” Number <EnvironmentToken> : “poll-interval” | “Max-agent-time-out” <Number> : Integer <StringList>: StringItem | StringList StringItem <StringItem> : StringToken “=” QuotedString <StringToken> : “registration_file” |“policy” | “command” |'type”|”user” <QuotedString> : “““ AlphanumericString ”””
The following example shows the snmpdx.rsrc and mibiisa.rsrc files.
Descriptions of the variables used in the configuration file follow the example. The comment lines begin with the # character.
snmpdx.rsrc environment = { poll-interval = 5 # This is in seconds max-agent-time_out = 10000000 # This is microseconds } mibiisa.rsrc resource = { { registration_file = /etc/snmp/conf/mibiisa.reg security = “/etc/snmp/conf/snmpd.conf type = “legacy” policy = “spawn” command = “/usr/lib/bin/mibiisa -p $PORT” } }
The environment group controls the behavior of the Master Agent. This group contains the following two variables:
poll-interval - this field contains values in seconds and indicates that the Master Agent performs activities other than receiving/sending SNMP messages after the specified interval; it finds out if there is a change in the resource file (discovering if all the agents are responding) and performs other routine housekeeping activities
max-agent-time-out - the value of this field is specified in microseconds; it signifies the maximum allowed time-out a subagent may request during registration; for example, when the Master Agent sends a request to a subagent, it waits for a time_out to receive the response; this time-out may be specified in the registration file or by using dynamic registration; if an agent sets this time-out too high, it creates problems for the Master Agent and other agents; to avoid such a problem, the Master Agent must specify a maximum value for the Master Agent to wait for a response from the subagent; this maximum value of time-out is specified using this variable.
The variables in the resource group are related only to subagents. The previous example configuration file contains two entries. Each entry represents a subagent and may have the following variables with some value assigned:
registration_file - this field specifies the registration configuration file for each subagent. The Master Agent reads the various entries in this file and creates appropriate entries in its MIB table. The details of this file are explained in 4.3 Agents Registration File. This entry is mandatory for all legacy-type agents. If the value for this variable does not contain a full path, the executable checks the default directory /etc/snmp/conf.
policy - this field has two values: load and spawn. The value load specifies the Master Agent to read this registration entry and create a row entry in its MIB table. If it finds the value spawn, the Master Agent invokes the respective subagent, as stated in the command field of that entry.
command - this is the name of the subagent executable. The command may contain the full path, or if the full path is not mentioned, the executable checks the default directory /usr/lib/bin. The command may use a $PORT macro to provide the port number from which the subagent receives SNMP requests. $PORT is assigned a value by the Master Agent in the registration file of each subagent. The $PORT macro is necessary because the legacy agents or subagents may take different arguments for the port option (such as -p, -n, -port).
user - this subagent is run according to the user specified in this entry.
Each agent has its own agent registration file. This provides the Master Agent and each subagent file with its own file version. The registration file contains information pertinent to each agent. It also includes the name of the agent, the subtree OIDs managed by the respective agent, request time out, and the preferred port number. The following example shows the format of each entry in this file.
<Config> : <Macro> <Agents> <Macro> : “macros” “=” “{“ <MacrosList>“}” <MacrosList> : <MacrosList> <MacroItem> | empty <MacroItem> : label “=” <SubidList> <SubidsLis> : <SubidsList> “.” <Subid> | <Subid> <Subid> : “mib2” | “sun” | “enterprise” | identifier | number <Agents> : “agents” “=” “{“ <AgentList> “}” <AgentList> : <AgentList> <AgentItem> | <AgentItem> <AgentItem> : “{“ <Name> <SubtreesTables> <TimeOut> <WatchDogTimer> <Port>“}” <Name> : label “=” quotestring <SubtreesTables> : <SubtreesTables> | <Subtrees> | <Tables> <Subtrees> : “subtrees” “=” “{“ <SubtreesList> “}” <SubtreesList> : <SubtreesList> “,” <SubtreeItem> | <SubtreeItem> | empty <SubtreeItem> : <SubidsList> <Tables> : “tables” “=” “{“ <TableList>“}” <TableList> : <TableList> <TableItem> | empty| <TableItem> : “{“ <Table> <Columns> <Indexs> “}” <Table> : “table” “=” <SubidsList> <Columns> : “column” “=” <Range> <Range> : “[“ number “]” | number <Index>s : “indexs” “=” <Range> <TimeOut> : “timeout” “=” number <WatchDogTimer>: “watch-dog-time” “=” number <Port> : “port” = number
The registration file name may have any extension. The reg extension is recommended. The following is an example of an actual subtree file.
macros = { applicationTable = mib-2.27 sun = enterprise.42 } agents = { { name = “ExampleAgent” subtrees = { mib-2, sun } tables = { { #begin table table = applicationTable columns = [ 2 -15 ] indexes = [ 2 -3 ] } #end table } #end of tables timeout = 20000 # Optional. Each SNMP request time out. This is in microseconds. watch_dog_time = 300 # This is in seconds port = 4000 # Optional } } #end of agents
This configuration file consists of two groups of information:
The variables used in the agents group are as follows:
name - this variable names the subagent. Agent names must be unique, though multiple agents invoked as separate processes may have the same executable. The Master Agent uses the agent name as a key in the agent table MIB.
subtrees - Subtrees contain a list of the subtree OIDs that are managed by this particular agent. A subagent may manage multiple trees. In the previous example of an actual subtree file in use, the agent named ExampleAgent manages subtrees mib-2 and sun.
tables - the subagent registration files may be configured to manage full or partial MIB tables. The tables group contains the table name, the column numbers, and particular row numbers (indexes). In the previous actual subtree file example, the ExampleAgent manages columns 2–15 of rows 2–3 of the application table in addition to subtrees mib-2 and sun.
timeout - the timeout variable is registered with the Master Agent. The Master Agent waits for the timeout microseconds to receive a response to its SNMP requests. Each agent specifies its own timeout, though this timeout may not be greater than the max_agent_time_out defined in the Master Agent resource configuration file previously defined.
watch_dog_time - the Master Agent uses this timeout to determine if the subagent is active. The Master Agent polls the subagent only if there has been no activity between the Master Agent and the subagent for the watch_dog_time interval.
port - the port is the number that the subagent is waiting for in order to receive SNMP requests from the Master Agent. This variable is optional. Normally, the subagents do not assign a value to this variable. If this variable is missing from the configuration file, the Master Agent attempts to find an unopened port, then invokes the respective subagent with this port number. If the port is assigned a value, the Master Agent invokes the subagent with this particular port number. The subagent is invoked according to the command variable mentioned in the Master Agent resource file.
Dynamic agents developed using Solstice Enterprise Agents libraries do not need to be invoked by the Master Agent. For such agents, there may not be any entry in the Master Agent resource file. Such agents open any available port by themselves.
The agents access control file is a configuration file that stores SNMP-related community information. Every subagent and the Master Agent may have its own access control file. This file name may have any extension, although the extension acl is recommended. This file must be stored in the /etc/snmp/conf directory.
The following is an example of the grammar for the access control configuration file.
<snmp_security> : <acls> <trap_block> <acls> : /*empty*/ | “acl” “=” {<acls_list> } <acls_list> : /*empty*/ | <acls_list> <acl_item> <acl_item> : {<communities_stmt> <acl_access> <hosts> } <communities_stmt> : “communities” “=” <communities_set> <communities_set> : <communities_set> , <community_elem> | <community_elem> <community_elem>: alphanumeric_string <acl_access> : “access” “=” <acl_access_type> <acl_access_type> : read-only | read-write <hosts> : “managers” “=” <hosts_list> <hosts_list> : <hosts_list> , <host_item> | <host_item> <host_item> : alphanumeric_string <trap_block> : “trap” “=” { <traps_list> } <traps_list> : /*empty*/ | <trap_list> < trap_item> <trap_item> : { <trap_community_string> <trap_interest_hosts> <enterprise_list> } <trap_community_string> : “trap-community” “=” alphanumeric_string <trap_interest_hosts_list> : <trap_interest_hosts_list> , <trap_interest_host_item> | <trap_interest_host_item> <trap_interest_host_item> : alphanumeric_string <enterprise_list> : /*empty*/ | <enterprise_list> <enterprise_item> <enterprise_item> : { <enterprise_stmt> <trap_number_stmt> } <enterprise_stmt> : “enterprise” “=” quouted_alphanumeric_string <trap_number_stmt> : “trap-num” “=” <trap_number_list> <trap_number_list> : <trap_number_item> <trap_number_item> : <trap_range> <trap_range> : integer - integer | integer
The following is an example of the access control list file.
acl = { { communities = public, private access = read-only managers = hubble, snowbell, nanak } { communities = jerry access = read-write managers = hubble, telescope } } trap = { { trap-community = SNMP-trap hosts = hubble, snowbell { enterprise = “Sun” trap-num = 1, 2-5 } { enterprise = “3Com” trap-num = 4 } } { trap-community = competitor-trap hosts = hp_server, ibm_server, sgi { enterprise = “sun” trap-num = 1,3 } { enterprise = “snmp” trap-num = 1-32 } } }
The access control list file contains the following two groups of configuration variables.
acl - this group of variables consists of multiple triplets that include community names, access rights, and names of hosts from accepted SNMP requests (only if the requests include the configured communities). In the previous access control list file example, only GET and GET_NEXT SNMP requests that include public and private community names are accepted from hosts hubble, snowbell, and nanak. This group may contain multiple triplets.
A Master Agent may have the appropriate communities and the access rights to receive SNMP PDUs. However, if the same SNMP PDU is forwarded to a subagent, it may reject the PDU that does not have the proper rights to receive such a PDU (or does not include the proper community). A subagent might have access rights and the community to receive an SNMP PDU, but such a PDU may never reach the subagent if the Master Agent does not have the appropriate community strings and the access rights.
trap - this group of variables consists of information for sending and or /forwarding traps received from the subagents. The Master Agent uses the information specified in this group for forwarding the traps. This information specifies the names of the hosts to send the configured trap numbers. The trap PDUs contain the specified trap community. These traps are generated primarily by the subagents and are then sent to the Master Agent.
The Master Agent status file contains information for the various subagents spawned by the Master Agent. The Master Agent uses this file exclusively. The Master Agent dynamically adds information to this file, and therefore you should not edit it manually. Whenever the Master Agent spawns a subagent process, it creates an entry in this file. The purpose of this file is for Master Agent recovery, in case the Master Agent dies or is killed. When the Master Agent restarts, the entries in this file indicate the subagent(s) it previously created and the corresponding port numbers. The Master Agent reads each entry in this file and compares it with the entries in the Master Agent resource configuration file. If the entry is not found in the resource file, the Master Agent kills that process. Whenever the entries are present in both files, the Master Agent attempts to access the subagent through the port.
Three tables under Sun-specific enterprise MIB OID are defined that facilitate the Solstice Enterprise Agents technology. The following table example is meant to provide manageability of all subagents. The information in this table provides the identity of the subagent. This table contains the subagent name, and the subagent port number. An example of the subtree's OIDs managed by each subagent is not shown.
The following is an example of a MIB containing all types of MIB variables. The MIB also includes tables. When this MIB is run through mibcodegen, it generates the appropriate MIB database and the stub code to build a subagent for this MIB.
DEMO-MIB DEFINITIONS ::= BEGIN IMPORTS OBJECT-TYPE, Counter32, Gauge32 FROM SNMPv2-SMI DisplayString, TimeStamp FROM SNMPv2-TC; mib-2 OBJECT IDENTIFIER ::= { mgmt 1 } sun OBJECT IDENTIFIER ::= { enterprises 42 } demo OBJECT IDENTIFIER ::= { sun 1000 } -- -- Some objects -- demoString OBJECT-TYPE SYNTAX DisplayString MAX-ACCESS read-write STATUS current DESCRIPTION "A read-write object of type String." ::= {demo 1} demoInteger OBJECT-TYPE ::= {demoTable 1} DemoEntry ::= SEQUENCE { demoEntryIndex INTEGER, demoEntryString DisplayString, demoEntryInteger INTEGER, demoEntryOid OBJECT IDENTIFIER } SYNTAX INTEGER { up(1), down(2) } MAX-ACCESS read-write STATUS current DESCRIPTION "A read-write object of type Integer." ::= {demo 2} demoOid OBJECT-TYPE SYNTAX OBJECT IDENTIFIER MAX-ACCESS read-write STATUS current DESCRIPTION "A read-write object of type Oid." ::= {demo 3} -- A table composed of some columns demoTable OBJECT-TYPE SYNTAX SEQUENCE OF DemoEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "A table." ::= {demo 10} demoEntry OBJECT-TYPE SYNTAX DemoEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "An entry in the table demoTable." INDEX {demoEntryIndex} demoEntryIndex OBJECT-TYPE SYNTAX INTEGER (1..2147483647) MAX-ACCESS not-accessible STATUS current DESCRIPTION "An index to uniquely identify the entry." ::= {demoEntry 1} demoEntryString OBJECT-TYPE SYNTAX DisplayString MAX-ACCESS read-write STATUS current DESCRIPTION "A read-write column of type String." ::= {demoEntry 2} demoEntryInteger OBJECT-TYPE SYNTAX INTEGER { up(1), down(2) } MAX-ACCESS read-write STATUS current DESCRIPTION "A read-write column of type Integer." ::= {demoEntry 3} demoEntryOid OBJECT-TYPE SYNTAX OBJECT IDENTIFIER MAX-ACCESS read-write STATUS current DESCRIPTION "A read-write column of type Oid." ::= {demoEntry 4} demoTrap TRAP-TYPE ENTERPRISE sun VARIABLES { demoInteger, demoString, demoOid} DESCRIPTION " Trap for testing." ::= 2 demoColdLinkTrap TRAP-TYPE ENTERPRISE snmp DESCRIPTION " Trap for testing." ::= 0 END