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 14-6 for details on using trace.

Table 14-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 14.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 14-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

14.5 SNMP Log Files

Unless the SNMP_TRACE option is set, output from the SNMP master agent and subagent processes to SYS$OUTPUT is redirected to the following files:

• TCPIP$SNMP_RUN.LOG
• TCPIP$OS_MIBS.LOG
• TCPIP$HR_MIB.LOG

The output is written to these files continuously while SNMP processes are running. Buffering may cause a delay in writing to disk; therefore, if a process is terminated abnormally, some data may be lost.

While processes are running, output for SYS$ERROR can be redirected to other files. See Section 14.4.3 for information about controlling this. In addition, the master agent and subagents may write to SYS$ERROR. This output is redirected to the following files:

• TCPIP$SNMP_RUN.LOG
• TCPIP$OS_MIBS.ERR
• TCPIP$HR_MIB.ERR

Unlike a regular log or a trace log, this output is written when the corresponding SNMP process terminates. Therefore, abnormal termination can cause data to be lost.

All of the listed log files are located in the SYS$SYSDEVICE:[TCPIP$SNMP] directory. The configuration-related files described in Section 14.4.3 are also stored there. TCP/IP Services does not allow you write to log files in other directories.

The log level and specific events during processing determine how much information is recorded in the log files; log files can be empty or nonexistent.

The log files contain startup and event information and additional messages, depending on the logging level specified for an agent. The SNMP logging facility uses three logging levels:

• Trace (logs trace, warning, and error messages)
• Warning (logs warning and error messages)
• Error

The default logging level for the master agent and standard subagents is Warning. Because the Chess example subagent does not use a default, messages are captured only if you specify tracing, as described in Section 14.6.4.

Many logging options are configurable using the text configuration file SYS$SYSDEVICE:[TCPIP$SNMP]TCPIP$VMS_SNMP_CONF.DAT; see Table 14-3 for more details.

The following log files exist under normal production conditions if special configuration options are not used. In most cases, a new version of each file is created each time SNMP is started:

Agent	Process	SYS$OUTPUT	SYS$ERROR
Master agent	TCPIP$SNMP	TCPIP$SNMP_RUN.LOG	TCPIP$SNMP_RUN.LOG
Resident subagent	TCPIP$SNMP	TCPIP$SNMP_RUN.LOG	TCPIP$SNMP_RUN.LOG
OS_MIBS 1	TCPIP$OS_MIBS	TCPIP$OS_MIBS.LOG	TCPIP$OS_MIBS.ERR
HR_MIB	TCPIP$HR_MIB 1	TCPIP$HR_MIB.LOG	TCPIP$HR_MIB.ERR

If the configuration option SNMP_GEN_LOGFILE is set, files in the preceding table continue to be used for SYS$ERROR data. For SYS$OUTPUT data, as soon as the agents detect the option, data is written to the following files, where process-ID is the hexadecimal process ID of the process listed:

Agent	Process	SYS$OUTPUT
Master agent	TCPIP$SNMP	TCPIP$ESNMP_SERVER process-ID.LOG
Resident subagent	TCPIP$SNMP	TCPIP$ESNMP_RESIDENT_SUBAGENT process-ID.LOG
OS_MIBS	TCPIP$OS_MIBS	TCPIP$OS_MIBS process-ID.LOG
HR_MIB	TCPIP$HR_MIB	TCPIP$HR_MIB process-ID.LOG

Unless it is suppressed, the timestamp gives a line-by-line record of when output was written to each file and is useful in resolving timing-related problems.

The SNMP_GEN_LOGFILE option does not affect the name of the output file for customer written subagents. Customer-written subagents generate files based on the IMAGENAME symbol in SYS$SYSDEVICE:[TCPIP$SNMP]TCPIP$EXTENSION_MIB_RUN.COM.

For details about logging from customer extension subagents, refer to the Compaq TCP/IP Services for OpenVMS SNMP Programming and Reference guide.

14.6 Solving SNMP Problems

The following sections contain information about how to analyze and solve many SNMP problems. Be sure to configure SNMP according to the instructions in this guide, and use the information here and in the Compaq TCP/IP Services for OpenVMS SNMP Programming and Reference guide when writing your own subagents.

14.6.1 Multiple SNMP Processes Displayed for SHOW SYSTEM Command

When you enter the DCL command SHOW SYSTEM during the TCPIP or SNMP startup sequence, the process TCPIP$SNMP_n may appear in the display without the subagent processes (TCPIP$OS_MIBS and TCPIP$HR_MIB). This is because TCPIP$SNMP is the main SNMP process started by the TCP/IP kernel when the SNMP service is enabled; it starts the subagents as detached processes, and then continues to run as the master agent. The number at the end of this process name reflects the number of times this main process has started since SNMP has been enabled.

14.6.2 Problems Starting and Stopping SNMP Processes

If there are startup errors noted in the SNMP log files, or if SNMP startup seems normal but one or more of the SNMP processes disappears, follow these steps:

1. Check the log files for any errors indicating timeouts, protection problems, or configuration errors.
2. Start up the master agent and subagents by running the images interactively and enabling tracing (see Section 14.6.4).

To verify the SNMP installation, enter the command SHOW CONFIGURATION SNMP, as described in Section 14.4.2.

To stop all SNMP processes, enter:

$ @SYS$STARTUP:TCPIP$SNMP_SHUTDOWN

If you disable the SNMP service by entering the DISABLE SERVICE SNMP command, automatic restarts are prevented, but detached SNMP master and subagent processes are not stopped.

14.6.3 Restarting MIB Subagent Processes

Usually the SNMP master agent and subagent processes start up and are shut down together as described in Section 14.1.1.

If the SNMP master agent process stops for any reason, TCP/IP Services attempts to restart it and, if successful, increments the count (n) in the process name TCPIP$SNMP_n. As part of the startup sequence, any subagents that have stopped will be restarted. If a subagent process has not stopped, an attempt to restart it will have no effect because OpenVMS does not allow a duplicate process name (unlike the SNMP master agent, subagent names do not include a startup count).

If the master agent continues to run but a subagent stops, there is no automatic restart attempt. You can correct the problem by doing one of the following:

• Restart TCP/IP Services.
• Restart SNMP.
• Manually stop the TCPIP$SNMP_n process to force a master agent restart.
• Configure the SNMP variable AUTRESTARTS and stop all the subagent processes. See Section 14.4.3 for more information.

To get trace log messages you can:

• Configure SNMP to enable trace output while SNMP continues processing.
• Enable tracing while running SNMP interactively.

To configure SNMP to log tracing messages while it is running, set the snmp_trace configuration option. With this option enabled, trace output is produced and written to standard logs (see Section 14.5) when agents are run in normal production mode.

See Section 14.4.3 for details about the configuration options and about how to enable those options dynamically or without running interactively.

To obtain trace log messages interactively, follow these steps:

1. Shut down SNMP. Enter:

   $ @SYS$STARTUP:TCPIP$SNMP_SHUTDOWN

2. From separate windows, run the master agent and subagents interactively. For example, run each image by entering the following commands in separate windows:

   $ MCR TCPIP$ESNMP_SERVER -T $ MCR TCPIP$OS_MIBS -TRACE $ MCR TCPIP$HR_MIB -TRACE

   
   To specify custom subagents located in directories other than SYS$SYSTEM, use the MCR command and specify the full directory path. For example, to run the Chess example subagent with trace logging, enter the following command:

   $ MCR SYS$COMMON:[SYSHLP.EXAMPLES.TCPIP.SNMP]TCPIP$CHESS_SUBAGENT -TRACE

When agents are run interactively, output comes to the terminal unless the SNMP_GEN_LOGFILE option is enabled.

Running in trace mode can produce a great deal of output, and also slow down performance significantly. Programs like browsers may need to allow a longer timeout interval under these circumstance. For example, use the -w with the supplied MIB browser.

For more information about the MIB browser supplied with TCP/IP Services, and on using tracing with custom subagents, see the Compaq TCP/IP Services for OpenVMS SNMP Programming and Reference guide.

The type of trace data written depends on the way the subagent routines are programmed, except for logging handled within eSNMP API routines. For more details, see the Chess example code.

14.6.5 Processing Set Requests and Traps

To make sure that the master agent processes SNMP Set requests from management clients correctly, follow these steps:

1. Configure SNMP to allow the master agent to process Set requests, either by using the TCPIP$CONFIG.COM configuration procedure or by using the SET CONFIGURATION SNMP command.
2. Make sure that the management client is configured correctly for Get and Set requests, as described in the Compaq TCP/IP Services for OpenVMS SNMP Programming and Reference guide.
3. Configure write communities as needed on the OpenVMS server. Refer to Section 14.6.5.2.2 for more information.
4. Make sure that the requested MIB variable is defined with write access and implemented as such in the subagent. Refer to the Compaq TCP/IP Services for OpenVMS SNMP Programming and Reference guide for more information.

If SNMP is not responding to Set requests after you follow these steps, refer to Section 14.6.6 for troubleshooting procedures and Section 14.6.5.2.2 to check the community configuration information.

14.6.5.1 Enabling Set Request Processing and Authentication Traps

On an OpenVMS server, configure SNMP with the /FLAGS=SETS qualifier to the management command SET CONFIGURATION SNMP, or enable SNMP during the configuration procedure (TCPIP$CONFIG) by answering Yes to the question Do you want to allow clients modify (SET) access?

To enable set requests and traps on an existing SNMP configuration, enter the SET CONFIGURATION SNMP command with the /FLAGS=options qualifier, specifying the SETS option to enable set requests and the AUTHEN_TRAPS option to enable sending authentication failure traps.

When you enter the SET CONFIGURATION SNMP command and qualifiers, take the following information into consideration:

• SNMP functions without the need to configure flags for set commands (/FLAGS=SETS) and authentication traps (/FLAGS=AUTHEN_TRAPS). Note that when you enter the SHOW CONFIGURATION SNMP command, the keywords associated with these flags are displayed as follows:

  Flags: AuthenTraps Sets

• The /FLAGS=SETS qualifier is required to enable SNMP client set command requests. If set commands are not enabled, the client receives a " no such variable " message, even if access type requirements are met. (See the command guidelines in Section 14.6.5.1.)
• The /FLAGS=AUTHEN_TRAPS qualifier allows the SNMP master to send trap messages to specified trap community addresses when MIB access with a community name is not supported by the agent. This also allows the master to send trap messages when the agent does not grant the host the access required for a request (for example, READ for a get request or WRITE for a set request).

For example, to enable response to set requests and to allow authentication traps on an existing SNMP configuration, enter the following command:

TCPIP> SET CONFIGURATION SNMP/FLAGS=(SETS,AUTHEN_TRAPS)

See the HP TCP/IP Services for OpenVMS Management Command Reference guide for detailed information about the SET CONFIGURATION SNMP command.

Restart SNMP after making any changes to the configuration.