You can configure SNMP in three ways, which can be used in combination:

• Using the standard TCPIP$CONFIG.COM procedure and the SET CONFIGURATION SNMP command. These methods write configuration information into the TCP/IP Services configuration database file TCPIP$CONFIGURATION.DAT. Section 14.4.1 describes how to use TCPIP$CONFIG to initially configure SNMP.
• Editing the text configuration file TCPIP$VMS_SNMP_CONF.DAT, located in the SYS$SYSDEVICE:[TCPIP$SNMP] directory. This method provides options not available with TCPIP$CONFIG and with the SET CONFIGURATION SNMP command.

  Note Although the OpenVMS SNMP configuration file is based on the UNIX implementation, there are several important differences. For example, the option snmpEnableAuthenTraps is not used. See the description of specific options for details.

  
  The configuration file is described in Section 14.4.3.
• Assigning logical names. This method provides the same options as the text configuration file. For more information, see Section 14.4.3.

If the same option is defined in multiple ways, the configuration methods are resolved as follows:

• Values specified through TCPIP$CONFIG or SET CONFIGURATION SNMP take precedence over any options specified in the TCPIP$VMS_SNMP_CONF.DAT file or set with logical names.
• Values specified in the TCPIP$VMS_SNMP_CONF.DAT file take precedence over logical name settings.

SNMP runs as a TCP/IP service. To be sure all SNMP-related files are included and enabled properly, run the TCPIP$CONFIG configuration procedure to configure SNMP initially or to set up a new configuration. When you enable SNMP during TCPIP$CONFIG, the procedure prompts you for the correct parameters.

When you run TCPIP$CONFIG after a TCP/IP Services upgrade, be sure to disable and then reenable the SNMP service.

You supply the following information about your host when you configure SNMP initially during TCPIP$CONFIG or when you issue the SET CONFIGURATION SNMP command to modify your existing SNMP configuration. For detailed information about the SET CONFIGURATION SNMP command and qualifiers, see the HP TCP/IP Services for OpenVMS Management Command Reference manual.

• The name of the person to contact about the system. For example:

  TCPIP> SET CONFIGURATION SNMP/CONTACT="Sam Spade"

• The physical location of the system. For example:

  TCPIP> SET CONFIGURATION SNMP - _TCPIP> /LOCATION=(FIRST="Falcon Building",SECOND="Los Angeles, CA")

• The community information used to authenticate requests from a network manager and to determine the addresses to which trap messages are sent.
  SNMP network management clients are grouped into communities as specified in RFC 1157. You can define one or more communities, which your master agent uses to authenticate requests.
  The parameters you specify for each community are as follows:
  • Community name
    The name associated with the community. The standard community is "public." You can choose not to provide this community name when you run TCPIP$CONFIG. Answer no to the question "Do you want to provide the public community." If you disable the public community, you might need to reconfigure SNMP clients in your environment.
    Community names are case sensitive. When you use TCPIP$CONFIG to specify a community name, do not use quotation marks to preserve the case; the case is preserved exactly as you enter it. However, if you customize your existing SNMP configuration using the SET CONFIGURATION SNMP command, make sure you enclose the community name in quotation marks to preserve the case. If you do not enclose the community name in quotation marks, the name is changed to all uppercase.
    The community name must be a string of alphanumeric characters. You cannot include a space or other nonalphanumeric character in the community name.
    You can also modify the community name using the community option in the configuration file, as described in Table 14-4.

  • Community address
    The address associated with the community. One community name can have multiple addresses in its entry. For example:

    TCPIP> SET CONFIGURATION SNMP /ADDRESS=(6.10.1.2,100.2.2.1)

    
    Specifying address 0.0.0.0 for READ and WRITE allows any host the type of access specified. To allow any network manager to monitor your system remotely, specify the standard community name ( public , in lowercase letters) with address 0.0.0.0. For example:

    TCPIP> SET CONFIGURATION SNMP /COMMUNITY="public" /ADDRESS=0.0.0.0

    
    Traps are sent to UDP port 162 on hosts for all trap addresses regardless of community name. The use of address 0.0.0.0 on a trap means that traps are not sent unless another address is also specified.

  • Types of access
    The types of access associated with the community are described in the following table:

    Access Type	Allows the Master Agent and Subagent to...
    READ	Respond to a client's read requests (gets) for network information. Default. Members of a read-only community do not have write access to the SNMP MIB objects.
    TRAP	Send alert messages (traps) to a client as a result of unusual events. For example, a trap message is sent to the client as a result of a get request that specifies an unauthorized community string ( authenticationFailure ).
    WRITE	Process client write requests (sets) on your host's MIB data items.

For example, to allow the master agent to respond to client get requests, enter:

TCPIP> SET CONFIGURATION SNMP /COMMUNITY="public" /TYPE=READ

To configure your host to allow client set requests, use the /FLAGS=SETS qualifier. For example:

TCPIP> SET CONFIGURATION SNMP /COMMUNITY="public" /FLAGS=SETS

14.4.2 Displaying the Current SNMP Configuration

To display configuration information in the SNMP configuration database, use the SHOW CONFIGURATION SNMP command. If you want to display the addresses that the agent recognizes as members of the community, use the /FULL qualifier. For example:

TCPIP> SHOW CONFIGURATION SNMP /FULL SNMP Configuration Flags: AuthenTraps Sets Contact: Sam Spade Location First: Falcon Building Second: Los Angeles, CA Community Type address_list public Read 0.0.0.0 writeit Read Write 9.20.208.53 trapit Read Trap 9.20.208.53, 9.20.208.100

In this example, the configuration allows read access to any client on any host through the public community and read/write access to the client on host 9.20.208.53 through the writeit community. In addition, trap messages are sent to UDP port 162 on hosts 9.20.208.53 and 9.20.208.100.

Alternatively, you can display the configuration options in the SNMP configuration text file described in Section 14.4.3. For more information, see Section 14.6.5.2.

14.4.3 SNMP Options

You can configure the way SNMP runs by entering SNMP options into the SNMP configuration file TCPIP$VMS_SNMP_CONF.DAT.

When it starts, the SNMP master agent creates the temporary file SYS$SYSDEVICE:[TCPIP$SNMP]TCPIP$TMP_SNMP_CONF.DAT from data in the standard TCP/IP configuration database file TCPIP$CONFIGURATION.DAT. For troubleshooting purposes, a few versions of this file are preserved. The master agent appends this temporary file to TCPIP$VMS_SNMP_CONF.DAT to produce the master configuration file TCPIP$SNMP_CONF.DAT.

When the standard OS_MIBS and HR_MIB subagents start up, they read TCPIP$SNMP_CONF.DAT. Only the master agent and these standard subagents use values in the text files.

By default, custom subagents do not take advantage of the configuration options. To take advantage of these options, you must assign a logical that is visible to the subagent process. The following example shows how to define TCPIP$SNMP_GEN_LOGFILE logical to set the snmp_gen_logfile configuration option:

$ ASSIGN/SYSTEM 1 TCPIP$SNMP_GEN_LOGFILE

If a configuration option is not handled by the eSNMP API, the subagent must include an explicit genenv() or similar call to access the value of the option.

14.4.3.1 Using Logical Names to Configure SNMP

Most configuration options have a corresponding logical name. In some cases, you can define system logical names as an alternative to entering a value in the text file. For a list of the options and their associated logical names, see Section 14.4.3.4.

14.4.3.2 Dynamic Options

Some options are available for you to change dynamically; that is, without shutting down and restarting the SNMP service. To change configuration values dynamically, you can do one of the following:

• Define the appropriate logical name.
• Edit the configuration file, then define snmp_signal to be sighup . Be sure to deassign snmp_signal afterwards to prevent continuous rereading of the configuration file.

The master agent and the subagents convert lines in the configuration file that begin with the OpenVMS-specific config command to user-mode process logicals by adding the prefix TCPIP$. For example, SNMP_GEN_LOGFILE becomes TCPIP$SNMP_GEN_LOGFILE. (This mechanism does not apply to options with other keywords, such as trap .) Because the logicals are local to agent processes, they are not visible to a DCL command SHOW LOGICAL issued in another process.

If there are lines with duplicate configuration tags, the last line supersedes all others. Because the temporary file TCPIP$TMP_CONF.DAT (described in Section 14.4.3) is appended after the user-editable TCPIP$VMS_SNMP_CONF.DAT file, the standard TCPIP configuration values from that temporary file always supersede those from the user-edited file.

Lines in the configuration file that begin with a pound sign (#) are ignored. The pound sign is the comment character.

Option names and values are not case sensitive. Boolean values are considered on if the option is present with no value. Otherwise, they are considered off. Thus, to turn off an option that was enabled at startup, you must specify zero as the value.

If you specify a value that is longer than the limit, the value is converted to hexadecimal and then truncated. For example, if you specify the value 257 in place of an 8-bit unsigned value, it is converted to hexadecimal (0101) and truncated to 1.

14.4.3.4 SNMP Configuration Options

Most of the SNMP options set in the TCPIP$VMS_SNMP_CONF.DAT file must be entered using the following syntax:

config option-name value

There are several types of SNMP configuration options:

• Logging options, described in Table 14-3. These options control the way messages are logged.
• Operation options, described in Table 14-4. These options control the operational settings for SNMP. Some of these options cannot be set by using a logical name.
• Timing options, described in Table 14-5. These options control the way timeouts are handled.
• Testing and troubleshooting options, described in Table 14-6. These options are useful when you are testing SNMP functions and troubleshooting subagent problems.
• Backward-compatibility options, described in Table 14-7. These options are available to provide compatibility with subagents developed under previous versions of SNMP.

Except for the community name, option values are not case sensitive.

Table 14-3 SNMP Logging Options

SNMP_GEN_LOGFILE
Logical name:	TCPIP$SNMP_GEN_LOGFILE
Format:	config SNMP_GEN_LOGFILE 1
Description:	Redirects messages to SYS$OUTPUT and records them in the following files: TCPIP$ESNMP_SERVER process-id.LOG, where process-id is the 8-digit hexadecimal process identifier of the master agent. TCPIP$ESNMP_RESIDENT_SUBAGENT process-id.LOG, where process-id is the 8-digit hexadecimal process identifier of the resident subagent. TCPIP$OS_MIBS process-id.LOG, where process-id is the 8-digit hexadecimal process identifier of the MIB II subagent. TCPIP$HR_MIB process-id.LOG, where process-id is the 8-digit hexadecimal process identifier of the Host Resources MIB subagent.
Type:	Dynamic
SNMP_SUPPRESS_LOGGING_TIMESTAMP
Logical name:	TCPIP$SNMP_SUPPRESS_LOGGING_TIMESTAMP
Format:	config SNMP_SUPPRESS_LOGGING_TIMESTAMP 1
Description:	Specifies whether a timestamp is included in the log message. If not defined, a timestamp is included. The value can be 1 (to prevent timestamp information from being included) or 0 (to allow timestamp information to be included; the default).
Type:	Dynamic
SNMP_VERBOSE_LOGGING
Logical name:	TCPIP$SNMP_VERBOSE_LOGGING
Format:	config SNMP_VERBOSE_LOGGING 1
Description:	Specifies whether to log detailed information or not. The value can be 1 (to log detailed information) or 0 (to log the default amount of information).
Type:	Dynamic

Table 14-4 SNMP Operation Options

COMMUNITY
Logical name:	Not available
Format:	COMMUNITY name address type
Description:	Specifies the community name. See Section 14.4 for more information about specifying a community name.
Type:	Dynamic
SNMPENABLEAUTHENTRAPS
Logical name:	Not available
Format:	SNMPENABLEAUTHENTRAPS
Description:	This configuration option reflects the setting of the /FLAGS=AUTHENTICATION qualifier to the SET CONFIGURATION SNMP command and is included in the configuration file for backward compatibility. This option in the configuration file is ignored.
Type:	Not dynamic
SNMP_RESTARTS
Logical name:	TCPIP$SNMP_RESTARTS
Format:	config SNMP_RESTARTS 5
Description:	Specifies the maximum number of times to restart a subagent. The default for OS_MIBS and HR_MIB is 3.
Type:	Not dynamic
SNMP_SELECT_ERROR_LIMIT
Logical name:	TCPIP$SNMP_SELECT_ERROR_LIMIT
Format:	config SNMP_SELECT_ERROR_LIMIT 500
Description:	Specifies the number of iterations for the error limit. The default value is 100.
Type:	Not dynamic
SNMP_SIGNAL
Logical name:	TCPIP$SNMP_SIGNAL
Format:	DEFINE TCPIP$SNMP_SIGNAL value
Description:	Simulates a UNIX-style signal that affects the way agents operate. Following is a list of values: SIGUSR1---causes a dump of MIB registration area with contexts to the following log file: SYS$SYSDEVICE:[TCPIP$SNMP]TCPIP$SNMP_DUMP.LOG SIGHUP---rereads the configuration file. SIGINT---causes the process to exit. SIGTERM---same as SIGINT. SIGUSR2---turns on tracing. SIGCHLD---turns off tracing. Do not set this option in the configuration text file. After setting the logical name, be sure to reset it to prevent system performance problems.
Type:	Dynamic
SYSNAME
Logical name:	Not available
Format:	SYSNAME host-name
Description:	Specifies the SNMP host name. This host name is used only by SNMP. You can reset the host name by editing this option and then restarting the master agent.
Type:	Not dynamic
SYSCONTACT
Logical name:	Not available
Format:	SYSCONTACT contact-information
Description:	Specifies the contact information. Do not modify this option. Use TCPIP$CONFIG or the SET CONFIGURATION SNMP command to change the information associated with this option.
Type:	Not dynamic
SYSLOCATION
Logical name:	Not available
Format:	SYSLOCATION host-location
Description:	Specifies the host or contact location information. Do not modify this option. Use TCPIP$CONFIG or the SET CONFIGURATION SNMP command to change the information associated with this option.
Type:	Not dynamic
trap
Logical name:	Not available
Format:	trap trap-name version IP-address
Description:	Specifies: The name of the trap ( trap-name). Whether to trap for SNMP Version 1 requests only ( version). Specify V1 for Version 1 traps only. Specify V2C for both Version 1 and Version 2 traps. The internet address of the client ( address). Do not specify 0.0.0.0 for the client address. For information about setting individual trap types depending on the destination host, see Section 14.6.5.3.
Type:	Not dynamic

Table 14-5 Timing and Timeout Handling Options

AGENTX_SESSION_TIMEOUT
Logical name:	TCPIP$AGENTX_SESSION_TIMEOUT
Format:	config AGENTX_SESSION_TIMEOUT seconds
Description:	Specifies the default timeout for a session between a subagent and the master agent. Subagents can supersede this value when they register their MIBs. The value of this option is used by both the master agent and the subagent. Normally, all subagents running on the same host have the same timeout value, which is specified by this option. When the subagent reads the value of this option, the value is interpreted as follows: If the option is not defined, the default value of 3 seconds is assumed. If the option is set to 0, the timeout value used by the master agent is used. If the option is set to a nonzero integer, that value is used instead of the master agent's default timeout value. When the master agent reads the value of this option, the value is interpreted as follows: If the option is not defined, the default value of 3 seconds is assumed. If the option is set to a value greater than 0, this timeout value is used, unless a different value has been specified for the subagent. Do not set the value of this option to 0. The maximum value you can specify is 255. This option can be used to increase the timeout for communication between the master agent and subagents on a slow system.
Type:	Dynamic
SNMP_MASTER_TIMEOUT
Logical name:	TCPIP$SNMP_MASTER_TIMEOUT
Format:	config SNMP_MASTER_TIMEOUT seconds
Description:	Specifies (in seconds) the default time to wait listening for an SNMP request. The default is 10 seconds.
Type:	Not dynamic
SNMP_ARE_YOU_THERE_TIME
Logical name:	TCPIP$SNMP_ARE_YOU_THERE_TIME
Format:	config SNMP_ARE_YOU_THERE_TIME seconds
Description:	Specifies the time subagents wait between sending the esnmp_are_you_there() message to the master agent. For the OS_MIBS and the HR_MIB, the default is 5400 seconds (90 minutes). If you also specify the SNMP_INACT_TIME option, make sure the value of the SNMP_ARE_YOU_THERE_TIME option is less than or equal to the value of the SNMP_INACT_TIME option.
Type:	Dynamic
SNMP_POLL_TIME
Logical name:	TCPIP$SNMP_POLL_TIME
Format:	config SNMP_POLL_TIME seconds
Description:	Specifies the interval between times that interface counts and other values are reset for standard subagents.
Type:	Dynamic
SNMP_INACT_TERM
Logical name:	TCPIP$SNMP_INACT_TERM
Format:	config SNMP_INACT_TERM n
Description:	In this format, n can be 1 (to terminate the master agent) or 0 (to never terminate the master agent). Specify the amount of time to wait using the SNMP_INACT_TIME option.
Type:	Dynamic
SNMP_INACT_TIME
Logical name:	TCPIP$SNMP_INACT_TIME
Format:	config SNMP_INACT_TIME seconds
Description:	Specifies (in seconds) the amount of time that must pass before the subagent is considered inactive (that is, the amount of time during which the master agent receives no message from the subagent). See also the SNMP_INACT_TERM and SNMP_ARE_YOU_THERE_TIME options.
Type:	Dynamic