Compaq TCP/IP Services for OpenVMS
Management

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. A few versions of this file are preserved in case they are needed for troubleshooting. 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.

13.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. See Section 13.4.3.4 for a list of the options and their associated logical names.

13.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 13.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.

13.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 13-3. These options control the way messages are logged.
• Operation options, described in Table 13-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 13-5. These options control the way timeouts are handled.
• Testing and troubleshooting options, described in Table 13-6. These options are useful when you are testing SNMP functions and troubleshooting subagent problems.
• Backward-compatibility options, described in Table 13-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 13-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 eight-digit hexadecimal process identifier of the master agent. TCPIP$ESNMP_RESIDENT_SUBAGENT process-id.LOG, where process-id is the eight-digit hexadecimal process identifier of the resident subagent. TCPIP$OS_MIBS process-id.LOG, where process-id is the eight-digit hexadecimal process identifier of the MIB II subagent. TCPIP$HR_MIB process-id.LOG, where process-id is the eight-digit hexadecimal process identifier of the Host Resources MIB subagent.
Type:	Dynamic
SNMP_SUPPRESS_LOGGING_TIMESTAMP
Logical name:	SNMP_SUPPRESS_LOGGING_TIMESTAMP
Format:	config TCPIP$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 13-4 SNMP Operation Options

COMMUNITY
Logical name:	Not available
Format:	COMMUNITY name address type
Description:	Specifies the community name. See Section 13.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 13.6.5.3.
Type:	Not dynamic

Table 13-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

Time-related parameters are important in determining the responsiveness of the SNMP agents to client requests, particularly on systems with limited memory or those that are heavily loaded.

On startup, each subagent first sets up a default session timeout (see the AGENTX_SESSION_TIMEOUT option). It then registers its MIB regions. The subagent can register each of its MIB regions with a different timeout. A value of 0 causes the session timeout for the entire subagent to be used.

The master agent listens for SNMP requests. The timeout value is 10 seconds, unless the SNMP_MASTER_TIMEOUT option has been defined. After a timeout occurs, the master agent updates counters, checks for requests, then loops to wait for another SNMP request. When an SNMP request arrives, the master agent determines which if any registered subagents can handle it. It then resets the SNMP_MASTER_TIMEOUT timeout to use the maximum of the timeouts for all MIB regions involved.

When it is not processing an SNMP request, a subagent may send are_you_there messages to the master agent at a default interval determined by the subagent. For the chess example, the default is 30 seconds; for the OS_MIBS and HR_MIB subagents, the default is 5400 seconds (90 minutes). Both values are derived from those used in the UNIX implementation of SNMP; the second value was set high to minimize system overhead.

The following relationships among configuration option values are recommended but are not enforced. See the descriptions of the specific options for details.

• SNMP_ARE_YOU_THERE_TIME and SNMP_INACT_TIME
  The SNMP_ARE_YOU_THERE_TIME option determines the time between are_you_there messages. If the SNMP_INACT_TERM option is set, and if the master agent does not receive any SNMP request or are_you_there mesages from a subagent during the time associated with the SNMP_INACT_TIME option, the master agent automatically exits. By default, the SNMP_INACT_TERM option is not set.
  If the SNMP_ARE_YOU_THERE_TIME option is not set and no external SNMP requests are received, the master agent will exit even if subagents are still active.
• SNMP_INACT_TIME and SNMP_POLL_TIME
  The values for these options should be a multiple of the value of the SNMP_MASTER_TIMEOUT option.
  The master agent checks whether these intervals have elapsed after the time specified by the SNMP_MASTER_TIMEOUT option. Therefore, a value for these two options that is not a multiple of SNMP_MASTER_TIMEOUT will have the same effect as one that is the next higher multiple.
• The client should allow a large enough timeout interval to accommodate the server to avoid query failures or unnecessary retries. Particular care is required when network load is high and when communicating with heavily used servers and those in which tracing is turned on. See Table 13-6 for details on using trace.

Table 13-6 Testing and Troubleshooting Options

ACCEPT
Logical name:	Not available
Format:	accept IP-address
Description:	If nonlocal subagents are allowed (using the SNMP_ALLOW_INET_TRANSPORT, AGENT_INET_ADDR, or AGENTX_INET_PORT option), the ACCEPT option specifies the IP address of the host from which a connection will be accepted. If these options are not set, connections from nonlocal subagents are rejected. To allow access from all subagents, specify the IP-address as 0.0.0.0.
Type:	Dynamic
AGENTX_LOCAL_PORT
Logical name:	TCPIP$AGENTX_LOCAL_PORT
Format:	config AGENTX_LOCAL_PORT port number
Description:	Specifies the local port number from which to accept nonlocal subagent connections.
Type:	Dynamic
AGENTX_INET_PORT
Logical name:	TCPIP$AGENTX_INET_PORT
Format:	config AGENTX_INET_PORT port number
Description:	Specifies the TCP/IP port number from which to accept connections from nonlocal subagents.
Type:	Dynamic
SNMP_ALLOW_INET_TRANSPORT
Logical name:	TCPIP$SNMP_ALLOW_INET_TRANSPORT
Format:	config SNMP_ALLOW_INET_TRANSPORT n
Description:	Specifies whether the master agent accepts connections from nonlocal subagents.
Type:	Dynamic
SNMP_TRACE
Logical name:	TCPIP$SNMP_TRACE
Format:	config TCPIP$SNMP_TRACE n
Description:	Allows you to direct trace log messages to standard log files when agents are running in normal production mode. (Alternatively, you can get trace logs while running the subagent in interactive mode, as described in Section 13.6.4.) Running with tracing produces a great deal of output and may slow down the system. In addition, utilities like the MIB browser ( snmp_request ) may need a longer timeout interval when running with tracing on. The type of data and the amount of data logged for custom subagents depends on how the subagents are programmed, except for the logging that is handled automatically by the eSNMP API routines. The chess example code provides some samples of using the ESNMP_LOG macro.
Type:	Not dynamic

Table 13-7 Backward-Compatibility Options

SNMP_PROHIBIT_DUPLICATE_REGISTRATIONS
Logical name:	TCPIP$SNMP_PROHIBIT_DUPLICATE_REGISTRATIONS
Format:	config SNMP_PROHIBIT_DUPLICATE_REGISTRATIONS n
Description:	In this format, n can be 1 (to set the option), or 0 (to turn the option off). If this option is set, a subagent that tries to register with the same name as a previously registered subagent will be rejected. By default, duplicate registrations are allowed; the AgentX protocol does not check for duplicate subagents based on the subagent name.
Type:	Dynamic
SNMP_V1_TRAP_DEFAULT
Logical name:	TCPIP$SNMP_V1_TRAP_DEFAULT
Format:	config SNMP_V1_TRAP_DEFAULT n
Description:	In this format, n can be 1 (to set the option), or 0 (to turn the option off). When this option is set, traps defined in the TCPIP$CONFIG.COM procedure or using the TCP/IP management command SET CONFIGURATION SNMP are sent in SNMP Version 1 format. The default is to send these types of traps in Version 2 format.
Type:	Dynamic