C H A P T E R  3

Configuration Files

This chapter describes how to configure the SNMP agent.

The chapter contains the following sections:


Overview

You can configure the SNMP agent with the /etc/opt/SUNWmasf/conf/snmpd.conf file. This file defines the ports where the agent can be accessed, the access controls that it is to apply to management information, and destinations for traps. By default, only the port number requires configuring after installation if:

The default configuration used by the agent enables read-only access for the community public. If this is not required or it is inappropriate for a particular environment, configure access control as described below.

If there are systems that are to receive traps, provide a list of such hosts to the agent as described in Setting Up Trap and/or Inform Destinations.

If SNMPv3 access is required, further configure SNMPv3 and SNMPv3 users and views as described in SNMPv3 Configuration.

If the management applications using the agent are likely to require information in the MIB-II system branch, refer to Setting System Information.

You can add comments to the configuration file by making '#' the first character on the comment line.


Setting Up the Port Number

Configure the port number using the agentaddress keyword:


 agentaddress [<transport-specifier>:]<transport-address> [,...]

This makes the agent listen on the specified comma-separated list of listening addresses. At least one port must be specified for the agent to function. The transport-specifier should always be set to udp. The transport address is of the form:


hostname[:<port>]

or


<IPv4-address>[:<port>]

For example, specifying agent address as:


agentaddress 8161,localaddress:9161

makes the agent listen on UDP port 8161 on all IPv4 interfaces and UDP port 9161 only on the interface associated with the localhost address.

The agent MUST have a port number configured before it will start. No default value is provided for this port number and its value must be determined by the administrator on the basis of other agents that may be in use and the configuration of the management clients.



Note - By using ports other than 161 and 162 for SNMP agent access, you can ensure that these ports are available for use by other agents such as snmpdx or Sun Management Center, which use them by default.




Setting Up Trap and/or Inform Destinations

Syntax


trapcommunity <string>

This defines the default community string to be used when sending traps.



Note - You must use the trapcommunity command before any of the following three commands, which use this community string.



If you do not set a community string, the default value public is used.


trapsink <host>[<community>[<port>]]
trap2sink <host>[<community>[<port>]]
informsink <host>[<community>[<port>]]

These commands define the hosts to receive traps (and/or inform notifications):

You can use multiple trapsink, trap2sink and informsink lines to specify multiple destinations. You can also specify a host multiple times, in which case a trap is sent for each of the commands listed.

The daemon sends a cold start trap when it starts up. If enabled, it also sends traps on authentication failures. If <community> is not specified, the string from a preceding trap community directive is used. If no community has been specified, the value public is used. If <port> is not specified, the well-known SNMP trap port (162) is used.


CODE EXAMPLE 3-1 Using the trapsink and trap2sink Commands
....
agentaddress 8161,localhost:9161
###########################################################
# SECTION: Trap Destinations
#
# Here we defined who the agent will send traps to.
 
# trapsink: A SNMPv1 trap receiver
# arguments host [community] [portnum]
trapsink merlin public 32768
 
# trap2sink: A SNMPv2 trap receiver
# arguments host [community] [portnum]
trap2sink arthur

This results in SNMPv1 traps being sent to the system merlin on port 32768, and SNMPv2 traps being sent to arthur using the default port for traps of 162.


Configuring Access Control

The agent supports the view-based access control model (VACM) as defined in RFC 2575. It therefore recognizes the following keywords in the configuration file:

It also recognizes some easier-to-use wrapper directives:

Syntax

rocommunity and rwcommmunity


rocommunity <community>[<source>] [<OID>]
rwcommunity <community>[<source>] [<OID>]

These create read-only and read-write communities that can be used to access the agent. They are a simple wrapper around the more complex and powerful com2sec, group, access, and view directive lines. They are also not as efficient because groups are not created and the tables can be larger as a consequence. It is therefore better not to use these if you have complex situations to set up, and to reserve their use to where your setup is simple.

You can apply only one rwcommunity or rocommunity directive for each source/community combination.

rouser and rwuser


rouser <username> [noauth|auth|priv] [<OID>]
rwuser <username> [noauth|auth|priv] [<OID>]

These configure access permissions for the specified user in the VACM configuration tables. It is more efficient (and powerful) to use the combined group, access, and view directives instead, but these wrapper directives are much simpler.

These directives have no effect unless the corresponding user has been created (see SNMPv3 Configuration).

You can apply only one rwuser or rouser directive for each user.

com2sec


com2sec <username> <source> <community>

This directive specifies the mapping from a source/community pair to a security name.

The first source/community combination that matches the incoming packet is selected.

group


group <groupname> <model> <username>

This directive defines the mapping from a given security model and security name to a particular group.

access


access <groupname> <context> <model> <level> <match> <read> <write> <notify>

The access directive specifies the access permissions to be given to a particular group/security model combination.



Note - The <notify> field is ignored for the purposes of access control. All access control for traps and informs is configured by means of the trapsink, trap2sink, and informsink directives (see Setting Up Trap and/or Inform Destinations).



When <model> is v1 or v2c, set <level> to noauth, and <context> to the empty string "".

When access for a particular group with a given security model is requested, the agent determines access in the following order:

1. Entries with an matching security model (as opposed to those matching against any).

2. If there is still more than one match, the most exact <context> match.

3. If there is still more than one match, the entry with the highest security level.

view


view <viewname> <type> <subtree> [<mask>]

This defines the named view.

A bit value of 0 in the mask acts as a wildcard for the corresponding value in the OID. A bit value of 1 in the mask indicates that the corresponding value in the subtree OID is fixed.

The mask enables you to control access to one row in a table in a relatively simple way.


view cust1 included 1.3.6.1.2.1.2.2.1.1.1 ff.a0
view cust2 included 1.3.6.1.2.1.2.2.1.1.2 ff.a0

In the example above, the hex value ff.a0 has a binary equivalent of 11111111.10100000. The bit position of the first `0' is position 10, which means that the view cust1 provides access to all the objects with OIDs that match 1.3.6.1.2.1.2.2.1.x.1, where x is an integer value.

Similarly, the view cust2 provides access to all the objects with OIDs that match 1.3.6.1.2.1.2.2.1.x.2.

VACM Examples


CODE EXAMPLE 3-2 VACM Example
#     sec.name  source   community
com2sec local  localhost  private
com2sec mynet  10.10.10.0/24  public
com2sec public  default  public
 
#    group.name sec.model sec.name
group mygroup v1     mynet
group mygroup v2c     mynet
group mygroup usm     mynet
group local  v1     local
group local  v2c     local
group local  usm     local
group public v1     public
group public v2c     public
group public usm     public
 
#   view.name incl/excl subtree mask
view all  included .1       80
view system included system      fe
 
# group.name context sec.model sec.level prefix read  write notify
access mygroup ""    any    noauth  exact mib2  none none
access public ""    any    noauth  exact system none none
access local  ""    any    noauth  exact all  all  all

Default VACM Model

The default configuration of the agent, as shipped, is functionally equivalent to the following entries:


CODE EXAMPLE 3-3 Default VACM Model
com2sec public  default  public
group public  v1  public
group public  v2c public
group public  usm public
view all included .1
access public  ""  any noauth  exact all none none


SNMPv3 Configuration

This section describes the command that enables the agent to respond to SNM_v3 messages

Syntax


engineID <string>

You must configure the snmpd agent with an engineID so that it can respond to SNMPv3 messages. If you do not configure an engineID, the agent uses a default value of the engineID based on the first IP address found for the hostname of the machine. If this is inappropriate (for example, if another agent is also using the same engineID) you must configure an engineID explicitly. This line configures the engineID to the value of <string>.


createUser <username> MD5 <authpassphrase> 

MD5 enables the authentication of SNMP users. When you create an SNMPv3 user, you must also update the VACM access control tables to provide an explicit declaration of what the user can access.



Note - This entry is made in /var/opt/SUNWmasf/snmpd.dat rather than /etc/opt/SUNWmasf/conf/snmpd.conf.



The minimum pass phrase length is eight characters.



Note - When the specified user has been created, the createUser statement provided in the file is removed.




Setting System Information

This section describes the commands that you use to configure the system information in MIB-II.

Syntax


syslocation <string>
syscontact <string>
sysname <string>

These parameters set the system location, system contact, or system name for the agent. This information is reported in the system group the MIB-II tree. Normally, these objects (sysLocation.0, sysContact.0 and sysName.0) are read-write. However, if you specify the value for one of these objects by giving the appropriate token, the corresponding object becomes read-only, and subsequent attempts to set the value of the object result in a notWritable error response.


sysservices <number>

This parameter sets the value of the system.sysServices.0 object. For a host, an acceptable value is 72.

The value of sysservices is a sum based on the network layers for which the node performs transactions. For each layer, L, in the range 1 through 7, for which this node performs transactions, 2 raised to (L - 1) is added to the sum. For example, a node that performs primarily routing functions would have a value of 4 (2^(3-1)). In contrast, a node which is a host offering application services would have a value of 72 (2^(4-1) + 2^(7-1)).



Note - In the context of the Internet suite of protocols, values should be calculated accordingly.



TABLE 3-1 provides these layer values.


TABLE 3-1 Internet Protocol Layer Functionality

layer

functionality

1

Physical (for example, repeaters)

2

Datalink/subnetwork (for example, bridges)

3

Internet (for example, IP gateways)

4

End-to-end (for example, IP hosts)

7

Applications (for example, mail relays)


For systems including OSI protocols, layers 5 and 6 can also be counted.


General Configuration

This section describes the commands that enable general configuration of the agent.

Syntax


agentgroup <groupid>

Change to this groupid after opening the port. The groupid can refer to a group by name, or a number if the group number starts with #. For example, specifying agentgroup snmp causes the agent to run as the snmp group, and specifying agentgroup #10 causes the agent to run as the group with groupid 10.


agentuser <uid>

Change to this uid after opening the port. The uid can refer to a user by name, or a number if the user number starts with #. For example, specifying agentuser snmp causes the agent to run as the snmp user, and specifying agentuser #10 causes the agent to run as the user with uid 10.


authtrapenable <number>

Setting authtrapenable to 1 enables generation of authentication failure traps. The default value is disabled(2). Normally, the corresponding object (snmpEnableAuthenTraps.0) is read-write, but setting its value with this token makes the object read-only, and subsequent attempts to set the value of the object result in a notWritable error response.


Updating the SNMP Agent When It Is Running

You can update the configuration file at any time, either before starting the agent or once the agent has started. If the agent is running, it does not update its running configuration unless explicitly requested to do so.


procedure icon  To Force the SNMP Agent to Update


Co-Existence With Other Agents

The SNMP agent must be configured to use a specific network port and this cannot be shared with any other component on the system. However, master agent technologies can enable multiple SNMP agents on a system to appear as a single entity to management applications. To use such solutions, configure this agent to use a port that is known to the master agent, which then presents an aggregated OID space.