Simple Network Management Protocol (SNMP)
User's Guide
Version 5.1.1

Chapters

• SNMP Introduction
  • Top of chapter
  • Scope and Purpose
  • Prerequisites
  • Definitions
  • About This Manual
  • Where to Find More Information
• Agent Functional Description
  • Top of chapter
  • Features
  • SNMPv1, SNMPv2 and SNMPv3
  • Operation
  • Sub-agents and MIB Loading
  • Contexts and Communities
  • Management of the Agent
  • Notifications
  • Discovery
• Manager Functional Description
  • Top of chapter
  • Features
  • Operation
  • MIB loading
• The MIB Compiler
  • Top of chapter
  • Operation
  • Importing MIBs
  • MIB Consistency Checking
  • .hrl File Generation
  • Emacs Integration
  • Compiling from a Shell or a Makefile
  • Deviations from the Standard
• Running the application
  • Top of chapter
  • Configuring the application
  • Modifying the Configuration Files
  • Starting the application
  • Debugging the application
• Definition of Agent Configuration Files
  • Top of chapter
  • Agent Information
  • Contexts
  • System Information
  • Communities
  • MIB Views for VACM
  • Security data for USM
  • Notify Definitions
  • Target Address Definitions
  • Target Parameters Definitions
• Definition of Manager Configuration Files
  • Top of chapter
  • Manager Information
  • Users
  • Agents
  • Security data for USM
• Agent Implementation Example
  • Top of chapter
  • MIB
  • Default Implementation
  • Manual Implementation
• Manager Implementation Example
  • Top of chapter
  • The example manager
  • A simple standard test
• Instrumentation Functions
  • Top of chapter
  • Instrumentation Functions
  • Using the ExtraArgument
  • Default Instrumentation
  • Atomic Set
• Definition of Instrumentation Functions
  • Top of chapter
  • Variable Instrumentation
  • Table Instrumentation
• Definition of Agent Net if
  • Top of chapter
  • Mandatory Functions
  • Messages
• Definition of Manager Net if
  • Top of chapter
  • Mandatory Functions
  • Messages
• Audit Trail Log
  • Top of chapter
  • Agent Logging
  • Manager Logging
• Advanced Agent Topics
  • Top of chapter
  • When to use a Sub-agent
  • Agent Semantics
  • Sub-agents and Dependencies
  • Distributed Tables
  • Fault Tolerance
  • Using Mnesia Tables as SNMP Tables
  • Deviations from the Standard
• SNMP Appendix A
  • Top of chapter
  • Appendix A
• SNMP Appendix B
  • Top of chapter
  • Appendix B

6 Definition of Agent Configuration Files

All configuration data must be included in configuration files that are located in the configuration directory. The name of this directory is given in the config_dir configuration parameter. These files are read at start-up, and are used to initialize the SNMPv2-MIB or STANDARD-MIB, SNMP-FRAMEWORK-MIB, SNMP-MPD-MIB, SNMP-VIEW-BASED-ACM-MIB, SNMP-COMMUNITY-MIB, SNMP-USER-BASED-SM-MIB, SNMP-TARGET-MIB and SNMP-NOTIFICATION-MIB (refer to the Management of the Agent for a description of the MIBs).

The files are:

• agent.conf: see Agent Information

• standard.conf: see System Information

• context.conf: see Contexts

• community.conf: see Communities

• target_addr.conf: see Target Address Definitions

• target_params.conf: see Target Parameters Definitions

• vacm.conf: see MIB Views for VACM

• usm.conf: see Security data for USM

• notify.conf: see Notify Definitions

The directory where the configuration files are found is given as a parameter to the agent.

The entry format in all files are Erlang terms, separated by a '.' and a newline. In the following sections, the formats of these terms are described. Comments may be specified as ordinary Erlang comments.

Syntax errors in these files are discovered and reported with the function config_err/2 of the error report module at start-up.

6.1  Agent Information

The agent information should be stored in a file called agent.conf.

Each entry is a tuple of size two:

{AgentVariable, Value}.

• AgentVariable is one of the variables is SNMP-FRAMEWORK-MIB or one of the internal variables intAgentUDPPort, which defines which UDP port the agent listens to, or intAgentTransports, which defines the transport domains and addresses of the agent.

• Value is the value for the variable.

The following example shows an agent.conf file:

{intAgentUDPPort, 4000}.
{intAgentTransports,
 [{transportDomainUdpIpv4, {141,213,11,24}},
  {transportDomainUdpIpv6, {0,0,0,0,0,0,0,1}}]}.
{snmpEngineID, "mbj's engine"}.
{snmpEngineMaxPacketSize, 484}.
    

The value of intAgentTransports is a list of {Domain, Addr} tuples, where Domain is either transportDomainUdpIpv4 or transportDomainUdpIpv6, and Addr is the address in the domain. Addr can be specified either as an IpAddr or as an {IpAddr, IpPort} tuple. IpAddr is either a regular Erlang/OTP ip_address() or a traditional SNMP integer list and IpPort is an integer.

When the Addr value does not contain a port number, the value of intAgentUDPPort is used.

The legacy and intermediate variables intAgentIpAddress and intAgentTransportDomain are still supported so old agent.conf files will work.

The value of snmpEngineID is a string, which for a deployed agent should have a very specific structure. See RFC 2271/2571 for details.

6.2  Contexts

The context information should be stored in a file called context.conf. The default context "" need not be present.

Each row defines a context in the agent. This information is used in the table vacmContextTable in the SNMP-VIEW-BASED-ACM-MIB.

Each entry is a term:

ContextName.

• ContextName is a string.

6.3  System Information

The system information should be stored in a file called standard.conf.

Each entry is a tuple of size two:

{SystemVariable, Value}.

• SystemVariable is one of the variables in the system group, or snmpEnableAuthenTraps.

• Value is the value for the variable.

The following example shows a valid standard.conf file:

{sysDescr, "Erlang SNMP agent"}.
{sysObjectID, [1,2,3]}.
{sysContact, "(mbj,eklas)@erlang.ericsson.se"}.
{sysName, "test"}.
{sysServices, 72}.
{snmpEnableAuthenTraps, enabled}.
    

A value must be provided for all variables, which lack default values in the MIB.

6.4  Communities

The community information should be stored in a file called community.conf. It must be present if the agent is configured for SNMPv1 or SNMPv2c.

An SNMP community is a relationship between an SNMP agent and a set of SNMP managers that defines authentication, access control and proxy characteristics.

The corresponding table is snmpCommunityTable in the SNMP-COMMUNITY-MIB.

Each entry is a term:

{CommunityIndex, CommunityName, SecurityName, ContextName, TransportTag}.

• CommunityIndex is a non-empty string.

• CommunityName is a string.

• SecurityName is a string.

• ContextName is a string.

• TransportTag is a string.

6.5  MIB Views for VACM

The information about MIB Views for VACM should be stored in a file called vacm.conf.

The corresponding tables are vacmSecurityToGroupTable, vacmAccessTable and vacmViewTreeFamilyTable in the SNMP-VIEW-BASED-ACM-MIB.

Each entry is one of the terms, one entry corresponds to one row in one of the tables.

{vacmSecurityToGroup, SecModel, SecName, GroupName}.

{vacmAccess, GroupName, Prefix, SecModel, SecLevel, Match, ReadView, WriteView, NotifyView}.

{vacmViewTreeFamily, ViewIndex, ViewSubtree, ViewStatus, ViewMask}.

• SecModel is any, v1, v2c, or usm.

• SecName is a string.

• GroupName is a string.

• Prefix is a string.

• SecLevel is noAuthNoPriv, authNoPriv, or authPriv

• Match is prefix or exact.

• ReadView is a string.

• WriteView is a string.

• NotifyView is a string.

• ViewIndex is an integer.

• ViewSubtree is a list of integer.

• ViewStatus is either included or excluded

• ViewMask is either null or a list of ones and zeros. Ones nominate that an exact match is used for this sub-identifier. Zeros are wild-cards which match any sub-identifier. If the mask is shorter than the sub-tree, the tail is regarded as all ones. null is shorthand for a mask with all ones.

6.6  Security data for USM

The information about Security data for USM should be stored in a file called usm.conf, which must be present if the agent is configured for SNMPv3.

The corresponding table is usmUserTable in the SNMP-USER-BASED-SM-MIB.

Each entry is a term:

{EngineID, UserName, SecName, Clone, AuthP, AuthKeyC, OwnAuthKeyC, PrivP, PrivKeyC, OwnPrivKeyC, Public, AuthKey, PrivKey}.

• EngineID is a string.

• UserName is a string.

• SecName is a string.

• Clone is zeroDotZero or a list of integers.

• AuthP is a usmNoAuthProtocol, usmHMACMD5AuthProtocol, or usmHMACSHAAuthProtocol.

• AuthKeyC is a string.

• OwnAuthKeyC is a string.

• PrivP is a usmNoPrivProtocol, usmDESPrivProtocol or usmAesCfb128Protocol.

• PrivKeyC is a string.

• OwnPrivKeyC is a string.

• Public is a string.

• AuthKey is a list (of integer). This is the User's secret localized authentication key. It is not visible in the MIB. The length of this key needs to be 16 if usmHMACMD5AuthProtocol is used, and 20 if usmHMACSHAAuthProtocol is used.

• PrivKey is a list (of integer). This is the User's secret localized encryption key. It is not visible in the MIB. The length of this key needs to be 16 if usmDESPrivProtocol or usmAesCfb128Protocol is used.

6.7  Notify Definitions

The information about Notify Definitions should be stored in a file called notify.conf.

The corresponding table is snmpNotifyTable in the SNMP-NOTIFICATION-MIB.

Each entry is a term:

{NotifyName, Tag, Type}.

• NotifyName is a unique non-empty string.

• Tag is a string.

• Type is trap or inform.

6.8  Target Address Definitions

The information about Target Address Definitions should be stored in a file called target_addr.conf.

The corresponding tables are snmpTargetAddrTable in the SNMP-TARGET-MIB and snmpTargetAddrExtTable in the SNMP-COMMUNITY-MIB.

Each entry is a term:

{TargetName, Domain, Addr, Timeout, RetryCount, TagList, ParamsName, EngineId}.
or
{TargetName, Domain, Addr, Timeout, RetryCount, TagList, ParamsName, EngineId, TMask, MaxMessageSize}.

• TargetName is a unique non-empty string.

• Domain is one of the atoms: transportDomainUdpIpv4 | transportDomainUdpIpv6.

• Addr is either an IpAddr or an {IpAddr, IpPort} tuple. IpAddr is either a regular Erlang/OTP ip_address() or a traditional SNMP integer list, and IpPort is an integer.

  If IpPort is omitted 162 is used.

• Timeout is an integer.

• RetryCount is an integer.

• TagList is a string.

• ParamsName is a string.

• EngineId is a string or the atom discovery.

• TMask is specified just as Addr or as []. Note in particular that using a list of 6 bytes for IPv4 or 8 words plus 2 bytes for IPv6 are still valid address formats so old configurations will work.

• MaxMessageSize is an integer (default: 2048).

The old tuple formats with Ip address and Udp port number found in old configurations still work.

Note that if EngineId has the value discovery, the agent cannot send inform messages to that manager until it has performed the discovery process with that manager.

6.9  Target Parameters Definitions

The information about Target Parameters Definitions should be stored in a file called target_params.conf.

The corresponding table is snmpTargetParamsTable in the SNMP-TARGET-MIB.

Each entry is a term:

{ParamsName, MPModel, SecurityModel, SecurityName, SecurityLevel}.

• ParamsName is a unique non-empty string.

• MPModel is v1, v2c or v3

• SecurityModel is v1, v2c, or usm.

• SecurityName is a string.

• SecurityLevel is noAuthNoPriv, authNoPriv or authPriv.