snmpd.conf File

Purpose

Defines a sample configuration file for the snmpdv1 agent.

Description

The snmpd.conf file provides the configuration information for the snmpdv1 agent. This file can be changed while the snmpdv1 agent is running. If the refresh or kill -1 command is issued, the snmpdv1 agent will reread this configuration file. The snmpdv1 agent must be under System Resource Control (SRC) for the refresh command to force the reread. This file is part of Simple Network Management Protocol Agent Applications in Network Support Facilities.

This configuration file contains:

Entries for Community names
Access privileges and view definitions for incoming Simple Network Management Protocol (SNMP) request packets
Entries for host destinations for trap notification
Entries for log file characteristics
Entries for snmpd-specific parameters
Entries for SNMP Multiplexing Protocol (SMUX) association configurations
Entries for the sysLocation and sysContact variables.

The snmpd.conf file must be owned by the root user. If the snmpd.conf file is not owned by root, or if the snmpdv1 daemon cannot open the configuration file, the snmpdv1 daemon issues a FATAL message to the logfile if logging is enabled and snmpdv1 terminates.

Certain rules apply for specifying particular parameters in entries in the snmpd.conf configuration file. Some entries require the specification of object identifiers or object names or both. The following rules apply:

An object identifier is specified in dotted numeric notation and must consist of at least three elements. The maximum number of elements in the object identifier is 50. Elements are separated by a . (dot). The first element must be a single digit in the range of 0 to 2. The second element must be an integer in the range of 1 to 40. The third and subsequent elements must be integers in the range of 1 to the size of an unsigned integer.
An object name consists of a textual name with an optional numeric instance. The object name must be known to the snmpdv1 agent. Object names typically are names of nodes in the Management Information Base (MIB) tree. If the root of the MIB tree, iso, is specified as an object name, the numeric instance is absolutely required. A . (dot) separates the textual name from the numeric instance.

Community Entry

The community entry specifies the communities, associated access privileges and MIB views the snmpdv1 agent allows. See example 1 for a sample entry. A community entry must be in the following format:

community CommunityName IPAddress NetMask Permissions ViewName

The following definitions apply to the variables in a community entry:

Item	Description
CommunityName	The community name.
IPAddress	The host name, IPv4 address in dotted-decimal format, or IPv6 address for the specified community name.
NetMask	A network mask in dotted-decimal format for the specified IPv4 address, or a prefix length in the range of 0 through 128 for the specified IPv6 address.
Permissions	Specifies one of: readOnly writeOnly readWrite none. The Permissions string is case-insensitive.
ViewName	A unique object identifier in dotted numeric notation that is associated with a portion of the MIB tree to which the specified community name allows access. The ViewName value is the same as that specified in the view entry.

The minimum specification required for a community entry is:

community CommunityName

The default values for this minimum community entry are:

Item	Description
IPAddress	`0.0.0.0`
NetMask	`0.0.0.0`
Permissions	`readOnly`
View	`iso.3`

Fields to the right of the minimum entry are optional, with the limitation that no fields to the left of a specified field are omitted. Any information to the right of the ViewName variable is ignored. If an IPAddress of 0.0.0.0 is specified, the default NetMask is 0.0.0.0. If an IPAddress other than 0.0.0.0 is specified, the default NetMask is 255.255.255.255.

The Permissions default is readOnly. If the ViewName is not specified, the view for this community defaults to ISO, the entire MIB tree. For example:

community    public     192.100.154.1

is a valid entry with the default values:

Item	Description
NetMask	`255.255.255.255`
Permissions	`readOnly`
View	`iso.3`

The following entry is not valid because the required NetMask variable to the left of the Permissions variable is not specified:

community  public   192.100.154.1
readWrite

In this case, the value in the Permissions variable is accepted as the NetMask value. Since the value in thePermissions variable is not in the format required for the NetMask variable, an error will occur. The snmpdv1 agent logs an EXCEPTIONS message if logging is enabled. In the case of an invalid community entry, the snmpdv1 agent ignores the entry.

View Entry

The view entry specifies the MIB subtrees to which a particular community has access. See example 3 for a sample entry. A view entry must be in the following format:

view   ViewName      MibSubtree...

The following definitions apply to the variables in the view entry:

Item	Description
ViewName	Specifies a unique object identifier in dotted-numeric notation that is associated with a portion of the MIB tree. This ViewName value is the same as that in the community entry and must be formatted as described there.
MibSubtree	A list of MIB subtrees, or MIB groups, specified as either an object name or an object identifier, that is associated with the ViewName variable. If the MIBSubtree list is not specified, the view defaults to iso, the entire MIB tree.

Together, the view entry and its associated community entry define an access privilege or MIB view allowed by the snmpdv1 agent.

In the case of an invalid view entry, the snmpdv1 agent logs an EXCEPTIONS message, if logging is enabled, and ignores the view entry.

If a ViewName is specified in the community entry, but there is no view entry to describe that ViewName, snmpdv1 agent logs an EXCEPTIONS message stating that there is no such view for the community. The snmpdv1 agent will allow no access for that community and view association.

Trap Entry

The trap entry specifies the hosts the snmpdv1 agent notifies in the event a trap is generated. See Example 2 for a sample entry. A trap entry must be in the following format:

trap  CommunityName  IPAddress ViewName TrapMask

In this format, the variable definitions are as follows:

Item	Description
CommunityName	The community name to be encoded in the SNMP trap packet.
IPAddress	The host name, or IPv4 address in dotted-decimal format, or IPv6 address for the specified community name.
ViewName	The snmpdv1 agent only checks the ViewName to verify that the format is valid and that there are no duplicate ViewName variables specified.
TrapMask	The trap mask in hexadecimal format. The bits from left to right stand for coldStart trap, warmStart trap, linkDown trap, linkUp trap, authenticationFailure trap, egpNeighborLoss trap, and enterpriseSpecific trap. The rightmost bit does not have any meaning. A value of 1 will enable the corresponding trap to be sent. Otherwise, the trap is blocked. For example: `hexadecimal bits meaningh fe 1111 1110 block no traps 7e 0111 1110 block coldStart trap be 1011 1110 block warmStart trap 3e 0011 1110 block coldStart trap and warmStart trap` The minimum specification required for a trap entry is: `trap CommunityName IPAddress` The default value of TrapMask for this minimum trap entry is `fe`. There is no trap blocked for this case. Fields to the right of the minimum entry are optional, with the limitation that no fields to the left of a specified field are omitted. There should be no information to the right of the TrapMask variable. In the case of an invalid trap entry, the snmpdv1 agent places an EXCEPTIONS message in the log file if logging is enabled and ignores the trap entry. It is assumed that all hosts listed in the trap entries are listening on well-known UDP port 162 for SNMP traps. Because community views for traps are not supported, the snmpdv1 agent will send trap messages for all traps generated as indicated by the TrapMask variable to the hosts listed in the trap entries. If no trap entry appears in the snmpd.conf file, the snmpdv1 agent will not send out trap messages upon the generation of a trap.

Logging Entry

The logging entry specifies the characteristics for the snmpdv1 agent logging activities if logging is not directed from the snmpd command with the -f option. See example 4 for a sample entry. A logging entry must be in the following format:

logging   FileName     Enablement
logging   size=Limit   level=DebugLevel

The following definitions apply to the fields in the logging entries:

Item	Description
FileName	Specifies the complete path and file name of the log file.
Limit	Specifies the maximum size in bytes of the specified log file. If the limit is specified as 0, the file size is unlimited.
DebugLevel	Specifies the level of logging, which can be one of the following: 0 All NOTICES, EXCEPTIONS, and FATAL messages 1 Level 0 plus DEBUG messages 2 Level 1 plus a hexadecimal dump of incoming and outgoing packets 3 Level 2 plus an English version of the request and response packets
Enablement	Specifies whether logging is active. The following options are available: enabled Turns logging on. disabled Turns logging off.

There is no default log file. The Enablement default is disabled. The log file size Limit default is 0, which means unlimited. The DebugLevel default is 0 if the snmpd command is invoked without the -d option. If the -d option is specified, the default DebugLevel is the value specified by the -d option on the snmpd command line.

The size= and level= entries are absolutely required if a size or debug level are specified. There can be no spaces around the = (equal sign).

There are no restrictions regarding the order in which the variables are entered in the logging entries. A logging entry can contain single or multiple variables.

If the value for the size= field or DebugLevel variable cannot be converted into an integer, the default size and debug level are used. Because the snmpd command sets the log file configuration parameters immediately upon reading them, the parameters in the logging entry are not necessarily ignored if the snmpd command determines there is an invalid field in that entry. For example, in the following invalid logging entry:

logging   size=100000    garbagestuff    enabled

The snmpd command will set the size parameter, but will discard all information from the field value of garbagestuff to the end of the line. In addition, an EXCEPTIONS message will be logged if logging is enabled.

snmpd Entry

The snmpd entry specifies configuration parameters for the snmpdv1 agent. See example 5 for a sample entry. An snmpd entry must be in the following format:

snmpd   Variable=Value

The = (equal sign) is absolutely required; there can be no spaces around it.

The following definitions apply to the snmpd entry:

Item	Description
Variable	Specifies the specific configuration parameter. Variable can be one of the following values: maxpacket querytimeout.
Value	Specifies the value of the specific variable.

The configurable variables and allowable values are:

Item	Description
maxpacket	The maximum packet size, in bytes, that the snmpdv1 agent will transmit. The minimum to which this variable can be set is 300 bytes. The maximum value to which this variable can be set is 56KB. If there is no snmpd entry for maxpacket, the system socket default levels will be used.
querytimeout	The time interval in seconds at which the snmpdv1 agent will query the interfaces to check for interface status changes. The minimum value to which querytimeout can be set is 30 seconds. If 0 is specified, the snmpdv1 agent will not query the interfaces for status changes. If there is no snmpd entry for querytimeout, the default value of 60 seconds is used.

The = (equal sign) is absolutely required; there can be no white space around it. There are no restrictions on the order in which the variables are entered in the snmpd entry. An snmpd entry can contain single or multiple variables.

The snmpdv1 agent sets the snmpd specific parameters immediately upon reading them. If the values are invalid, the snmpdv1 agent ignores them. If the snmpdv1 agent encounters an invalid field in the entry, processing is terminated for that entry and the snmpdv1 agent logs an EXCEPTIONS message if logging is enabled.

smux Entry

The smux entry specifies configuration information for SMUX associations between the snmpdv1 agent and SMUX peer clients. See example 6 for a sample entry. A smux entry must be in the following format:

smux   ClientOID Password  IPAddress  NetMask

The following definitions apply to the smux entry:

Item	Description
ClientOID	Specifies the unique object identifier in dotted numeric notation of the SMUX peer client. The ClientOID must match the ObjectID specified in the /etc/snmpd.peers file.
Password	Specifies the password that the snmpdv1 agent requires from the SMUX peer client to authenticate the SMUX association. The Password must match the Password in the /etc/snmpd.peers file.
IPAddress	The hostname, or IPv4 address in dotted notation, or IPv6 address of the host on which the SMUX peer client is running.
NetMask	Specifies a network mask in dotted decimal notation for the specified IPv4 address, or a prefix length in the range of 0 through 128 for the specified IPv6 address.

The minimum specification for the smux entry is:

smux   ClientOID   Password

The default values for this minimum smux entry are:

Item	Description
IPAddress	`127.0.0.1`
NetMask	`255.255.255.255`

Fields to the right of the minimum entry are optional, with the limitation that no fields to the left of a specified field are omitted. Any information to the right of NetMask is ignored. If no password is specified, there is no confirmation for the SMUX association. If neither theIPAddress nor NetMask are specified, the SMUX association is limited to the local host.

In the case of an invalid smux entry, the snmpdv1 agent logs an EXCEPTIONS message if logging is enabled and the snmpdv1 agent ignores that smux entry.

sysLocation and sysContact Entry

The sysLocation and sysContact entries specify the values of the sysLocation and sysContact variables. The entry is specified in the following format:

sysLocation  "Austin, Texas, USA, XYZ, Bld 905, 5C-11"
sysContact   "Bill Roth, Amber Services, 1-512-849-3999"

The first part of the entry specifies the variable to be set, sysLocation or sysContact. The second part is a quoted character string representing the variable's value. The length of this string should not exceed 256 characters. If more than one entry is in the file, the last entry is used to define the variable. If there is not an entry for a particular variable, the value is defined to be the NULL string. If there is not a quoted string after the variable name, the first word on the line is used as the value. If there is nothing after the variable name, the NULL string is assumed.

The snmpdv1 daemon uses the defined configuration file, whether it is the default file or specified from the command line, to save and read variables. The daemon does not need to be refreshed to get these new variables.

Note: Since these variables are settable, the snmpdv1 daemon writes to the configuration file to update these variables on a set request. If you are editing the file and a set request changes the variables, the set request could be lost when the edited file is saved. This can be avoided by shutting down the daemon to change the configuration file, or by using the snmpinfo command to set the variable through normal methods.

Comments are specified by a # (pound sign) character and can be located anywhere in the snmpd.conf file. A comment begins at the # character and continues to the end of the line.

Note: It does not matter in which order the specific configuration entries for community, traps, views, logging, snmpd, and smux are placed in the snmpd.conf file. There is no order dependency for the various entries.

Examples

Example of community entries in the snmpd.conf file:
```
#  Community specifications
community public
community private  192.100.154.7  255.255.255.255    readWrite   1.17.2
community monitor  192.100.154.1  255.255.255.0      readWrite   1.17.2
community private  oilers
community simple   giants
community test     0.0.0.0        0.0.0.0            none
community nobody   0.0.0.0        255.255.255.255    readWrite   1.17.35
community ipv6test 0::0           0
community ipv6monitor  2000:1:1:1:209:6bff:feae:6d67  64     readWrite   1.17.2
```
The first entry exemplifies the minimum required specification for a community entry. The IP address defaults to 0.0.0.0. The network mask defaults to 0.0.0.0. The permissions default to readOnly. The view defaults to the entire MIB tree. This configuration enables the snmpdv1 agent to accept all readOnly requests under the community name public regardless of the IP address. Write or set requests are rejected.

The second entry limits the snmpdv1 agent to accept readWrite requests under the community name private only from IP address 192.100.154.7 for MIB variables that are associated with the view name 1.17.2.

The third entry enables the snmpdv1 agent to accept readWrite requests under the community name monitor from all IP addresses that start with 192.100.154, as indicated by the network mask, for all MIB variables that are associated with the view name 1.17.2.

The fourth entry sets the network mask to the default 255.255.255.255 and the permissions to the default, readOnly. This configuration enables the snmpdv1 agent to accept readOnly requests under the community name private from the host named oilers for the entire MIB tree. The reuse of the community name private is independent of the usage in the second example entry.

The fifth entry sets the network mask to the default 255.255.255.255 and the default permissions to readOnly. This configuration enables the snmpdv1 agent to accept readOnly requests for the entire MIB tree under the community name simple only from the host giants. Write or set requests are rejected.

The sixth entry causes the snmpdv1 agent to reject all requests under the community name test, regardless of the IP address, because of the permission restriction of none.

The seventh entry causes the snmpdv1 agent to reject all requests under the community name nobody because the network mask limits the IP address to entry 0.0.0.0, which is reserved and not available for a host.

The eighth entry causes the snmpdv1 agent to accept all requests through the IPv6 network under the community name ipv6test.

The ninth entry causes the snmpdv1 agent to accept read and write requests under the community name ipv6monitor from all IP addresses that start with 2000:1:1:1:209:6bff:feae:6d67, as indicated by the network prefix length for all MIB variables that are associated with the view name 1.17.2.
Example of trap entries in the snmpd.conf file:
```
#  Trap host notification specifications
trap traps   192.100.154.7
trap traps   129.35.39.233
trap events  giants
trap public  oilers  1.2.3       be
trap private 129.35.42.2101.2.4        7etrap events  2000:1:1:1:209:6bff:feae:6d67
```
The first entry specifies that the snmpdv1 agent is to notify the host with IP address 192.100.154.7 of all traps generated. The community name embedded in the trap packet will be traps.

The second entry specifies that the snmpdv1 agent is to notify the host with IP address 129.35.39.233 of all traps generated. The community name embedded in the trap packet will be traps.

The third entry specifies that the snmpdv1 agent is to notify the host giants of all traps generated. The community name embedded in the trap packet will be events.

The fourth entry specifies that the snmpdv1 agent is to notify the host oilers of all traps generated except for the warmStart trap. The community name embedded in the trap packet will be public. The ViewName,1.2.3, is ignored.

The fifth entry specifies that the snmpdv1 agent is to notify the host 129.35.42.210 of all traps generated except the coldStart trap. The community name embedded in the trap packet will be private. The ViewName, 1.2.4, is ignored.

The sixth entry specifies that the snmpdv1 agent is to notify the IPv6 host 2000:1:1:1:209:6bff:feae:6d67 of all of the traps generated. The community name embedded in the trap packet will be events.
Examples of view entries in the snmpd.conf file:
```
#     View specifications
view  1.17.2 system enterprises view
view  1.17.35
view  2.10.1 iso.3
```
The first entry associates the view name 1.17.2 with the system, enterprises, and view MIB groups. A community name that is associated with view 1.17.2 will only be associated with the MIB variables in these three groups. Thus, a host that has read permissions with this community name association can only get values for MIB variables in these specified groups.

The second and third entries configure the snmpdv1 agent to allow access to the entire MIB tree for hosts that have access privileges associated with these specified view names.
Examples of logging entries in the snmpd.conf file:
```
#   Logging specifications
logging    /tmp/snmpdlog enabled
logging    level=2   size=100000 
```
These logging entries configure the snmpdv1 agent to log messages at debug level 2 and below to the file named /tmp/snmpdlog. The size parameter limits the file size of the /tmp/snmpd log file to 100,000 bytes. When the log file reaches 100,000 bytes, the log file is rotated such that the full file is renamed to /tmp/snmpdlog.0 and the new log file is named /tmp/snmpdlog.
Example of snmpd entries in the snmpd.conf file:
```
#       snmpd parameter specifications
snmpd   maxpacket=2048
snmpd   querytimeout=120
```
The first snmpd entry limits the size of packets transmitted by the snmpdv1 agent to 2048 bytes.

The second entry sets the querytimeout parameter to 120 seconds. This configures the snmpdv1 agent to query all the interfaces known to the TCP/IP kernel every two minutes for status changes.
Examples of smux entries in the snmpd.conf file:
```
#    smux configuration
smux 1.3.6.1.4.1.2.3.1.2.2       #gated
```
This smux entry configures the snmpdv1 agent to allow the SMUX association only the gated SMUX peer client with no authentication. The SMUX peer must be running on the local host.
```
#    smux configuration
smux 1.3.6.1.4.1.2.3.1.2.2   private  #gated
```
This smux entry configures the snmpdv1 agent to allow the SMUX association only the gated SMUX peer client having the passwordprivate. The SMUX peer must be running on the local host.
```
#    smux configuration
smux 1.3.6.1.4.1.2.3.1.2.2 private 0.0.0.0  0.0.0.0
```
This smux entry configures the snmpdv1 agent to allow the SMUX association only the gated SMUX peer client having the passwordprivate. The SMUX peer can be running on any host.
```
#    smux configuration
smux 1.3.6.1.4.1.2.3.1.2.2 private 192.100.154.7 255.255.255.255
```
This smux entry configures the snmpdv1 agent to allow the SMUX association only the gated SMUX peer client having the passwordprivate. The gated SMUX peer must be running on the host with IP address 192.100.154.7
```
#    smux configuration
smux 1.3.6.1.4.1.2.3.1.2.2 private 192.100.154.1 255.255.255.0
```
This entry configures the snmpdv1 agent to allow the SMUX association only the gated SMUX peer client having the password private. The gated SMUX peer can be running on any host in the network defined by 192.100.154.
```
#    smux configuration
smux 1.3.6.1.4.1.2.3.1.2.2 private 2000:1:1:1:209:6bff:feae:6d67  64
```
This entry configures the snmpdv1 agent to allow the SMUX association with only the gated SMUX peer client that has the private password. The gated SMUX peer can be running on any IPv6 host in the network defined by 2000:1:1:1:209:6bff:feae:6d67.
Note: The SMUX peer client object identifier must be unique. Only one form of the preceding examples of smux entries for the gated SMUX peer client can be in the snmpd.conf file.

Example of sysLocation and sysContact entries in the snmpd.conf file:

# Definitions for sysLocation and sysContact
sysLocation   "Austin, Texas, USA, XYZ, Bld 905, 5C-11"
sysContact   "Bill Roth, Amber Services, 1-512-849-3999"

These entries set the value for the sysLocation and sysContact variables.