The NTPQ program is used to query the NTP server about its current state and to request changes to that state. NTPQ can also obtain and print a list of peers in a common format by sending multiple queries to the server.

The NTPQ program uses NTP mode 6 packets to communicate with the NTP server and thus is used to query any compatible server on the network. Note that because NTP is a UDP protocol, this communication is somewhat unreliable, especially over large distances (in terms of network topology). The NTPQ program makes one attempt to restransmit requests and times out requests if the remote host doesn't respond within the expected amount of time. NTPQ displays time values in milliseconds.

To run the NTPQ program, enter the following command:

$ RUN SYS$SYSTEM:TCPIP$NTPQ.EXE

At the NTPQ> prompt, enter commands using the following syntax:

command [options...]

You can also run NTPQ by defining a foreign command as follows:

$ ntpq:==$SYS$SYSTEM:TCPIP$NTPQ.EXE

Use the following syntax when entering commands:

$ ntpq [option...]

Table 10-6 describes the NTPQ command options. For more information, see the UNIX manual reference page ntpq(8).

Table 10-6 NTPQ Options

Option	Description
-c	Indicates that the following argument is interpreted as an interactive format command and is added to the list of commands to be executed on the specified host(s). Multiple -c options may be given.
-i	Forces NTPQ to operate in interactive mode.
-n	Outputs all host addresses in dotted-quad numeric format rather than converting to the canonical host names.
-p	Prints a list of the peers known to the server as well as a summary of their state.

The Simple Network Management Protocol (SNMP) is network management technology that facilitates the management of a TCP/IP network or internet in a vendor-independent manner. SNMP enables a network administrator to manage the various network components using a set of well-known procedures understood by all components, regardless of the vendor that manufactured them.

Configuring SNMP on your OpenVMS system allows a remote SNMP management client to obtain information about your host and to set network parameters.

This chapter reviews key concepts and describes how to configure SNMP on your host.

11.1 Reviewing Key Concepts

Systems using SNMP are divided into two categories: management consoles (sometimes called clients, network management stations, or directors) and agents (sometimes called servers). The management console is the system that issues a query; the agent runs on the system being queried. Queries are sent and received in the form of protocol data units (PDUs) inside SNMP messages, which are carried in UDP datagrams.

Depending on how you configure your host, an SNMP client can obtain information about your host and perform updates on your host's Management Information Base (MIB) data items. For example, you can configure your host to:

• Respond to a client's read requests (gets) for network information
• Send alert messages (traps) to a client as a result of events that might need to be monitored (for example, an authentication failure)
• Process client write requests (sets) on your host's MIB data items

DIGITAL TCP/IP Services for OpenVMS provides an SNMP master agent, two subagents ( MIB II and Host Resources MIB), a MIB converter and compiler, a simple MIB browser, and trap send and receive utility programs. Each subagent contains routines that perform read and write operations on its MIB data items.

Table 11-1 describes the SNMP components.

Table 11-1 SNMP Components

Component	Description
Master agent SNMP Version 2	Process name: TCPIP$ESNMP. The module that keeps track of managed objects and allows objects to register themselves. Sends information about these objects to remote SNMP management consoles. Also maintains a small set of variables for the MIB II component.
MIB II	Process name: TCPIP$OS_MIBS. Provides information about the TCP/IP protocol stack and other network activity.
Host resources MIB	Process name: TCPIP$HR_MIB. Provides information about the host system.
MIB converter	Extracts a MIB definition in ASN.1 notation in a text file into a MIB definition (.MY) file.
MIB compiler	Compiles MIB-definition files (for example, CHESS_MIB.MY) into source code templates for use in building subagents.
MIB utility programs	Act as simple clients to obtain a set of values for a MIB and to listen for and send trap messages.

11.1.1 Understanding How SNMP Operates

The TCPIP$CONFIG procedure sets up the following UDP services:

• SNMP, at well-known port 161
• eSNMP, at port 242 (used in the OpenVMS implementation as the master agent port number that is well known to the local subagents)

In addition, TCPIP$CONFIG sets up required files in the SYS$SYSDEVICE:[TCPIP$SNMP] directory.

The SNMP startup procedure (SYS$STARTUP:TCPIP$SNMP_STARTUP.COM) runs from the general TCPIP$STARTUP.COM procedure or can be run directly by the system manager.

TCPIP$SNMP_STARTUP.COM does the following:

1. Checks the TCP/IP Services license and enables the SNMP service.
2. Installs images with the required privileges (as appropriate: BYPASS, PHY_IO, and WORLD)
3. Runs SYS$SYSDEVICE:[TCPIP$SNMP]TCPIP$EXTENSION_MIB_STARTUP.COM, which installs and adjusts privileges for any additional, user-written subagents.
4. Runs a utility program that sends a UDP datagram to the SNMP port. When the port receives the datagram, the auxiliary server runs the TCPIP$SYSTEM:TCPIP$SNMP_RUN.COM procedure, which does the following:
   • Purges certain files in the SYS$SYSDEVICE:[TCPIP$SNMP] directory.
   • Runs the master agent and subagent images as detached processes.
   • Runs SYS$SYSDEVICE:[TCPIP$SNMP]TCPIP$EXTENSION_MIB_RUN.COM to start any additional subagents.
   
   As each subagent starts, it makes itself known to the master agent. This sequence includes registering the MIB subtrees that the subagent maintains and communicating the port number on which it listens.

Once SNMP has started, the following sequence occurs for each incoming SNMP request. This general sequence is standard for eSNMP implementations.

1. The master agent listens for incoming SNMP requests from clients on port 161. Authentication is limited to the validation of the community name. When a request arrives, the master agent communicates with the appropriate subagent at the registered port.
2. Subagent routines collect the requested data and return the data to the master agent.
3. The master agent responds to the client from which the original request was made.

The SNMP shutdown procedure TCPIP$SNMP_SHUTDOWN.COM runs from the general shutdown procedure TCPIP$SNMP_SHUTDOWN.COM or can be run directly by the system manager.

TCPIP$SNMP_SHUTDOWN.COM does the following:

• Stops subagent processes and removes the SNMP images.
• Runs SYS$SYSDEVICE:[TCPIP$SNMP]TCPIP$EXTENSION_MIB_SHUTDOWN.COM, which stops any additional subagent processes and deinstalls their images, if necessary.

Table 11-2 lists the names of the primary SNMP executable and command files and their locations. For a list of files that help you build your own subagent, see Table 11-9.

Table 11-2 SNMP Executable and Command Files

File	Location	Function
TCPIP$ESNMP_SERVER.EXE	TCPIP$SYSTEM	Master agent image.
TCPIP$OS_MIBS.EXE	TCPIP$SYSTEM	MIB-II subagent image.
TCPIP$HR_MIB.EXE	TCPIP$SYSTEM	Host Resources MIB subagent image.
TCPIP$SNMP_REQUEST.EXE	TCPIP$SYSTEM	Simple MIB browser.
TCPIP$SNMP_TRAPSND.EXE	TCPIP$SYSTEM	Program for sending trap messages.
TCPIP$SNMP_TRAPRCV.EXE	TCPIP$SYSTEM	Program for receiving trap messages.
TCPIP$ESNMP_SHR.EXE	SYS$SHARE	Routines in the eSNMP application programming interface (API).
TCPIP$SNMP_STARTUP.COM	SYS$STARTUP	Installs master and subagent images and runs TCPIP$SNMP_RUN.COM.
TCPIP$SNMP_RUN.COM	TCPIP$SYSTEM	Starts the master agent and subagents.
TCPIP$SNMP_SHUTDOWN.COM	SYS$STARTUP	Stops the master agent and subagents.

11.3 Log Files

Output redirected from SYS$OUTPUT for the agent process is logged to the following files:

• TCPIP$ESNMP.LOG
• TCPIP$OS_MIBS.LOG
• TCPIP$HR_MIB.LOG

Output redirected from SYS$ERROR is logged to the following files:

• TCPIP$ESNMP.ERR
• TCPIP$OS_MIBS.ERR
• TCPIP$HR_MIB.ERR

Data is flushed to the log files when the corresponding process terminates. Each invocation of the TCPIP$SNMP_RUN.COM procedure purges these files, retaining at least the last seven versions (the exact number depends on the value of the CLUSTER_NODES system parameter).

The log files are located in the SYS$SYSDEVICE:[TCPIP$SNMP] directory along with the TCPIP$SNMP_CONF.DAT file, which is a text representation of SNMP configuration data generated by the master agent during startup.

For the master agent and standard subagents, the log level is Warning. Log files for these processes include messages for Warning and Error events. The Chess example does not have a default log level. Therefore, no log messages appear. To specify a default log level for custom subagents, you can use the standard API call set_debug_level.

11.4 Configuring SNMP

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, you need to disable the current SNMP service then reenable SNMP.

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 DIGITAL 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"

• 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.
    When you enable a new SNMP configuration using TCPIP$CONFIG, do not use quotation marks (" ") to preserve the case. The case is preserved exactly as you enter it.
    When you customize your existing SNMP configuration using the SET CONFIGURATION SNMP command and applicable qualifiers, make sure you enclose the community name in double quotation marks (" ") to preserve the case. If you do not enclose the community name (or other parameter) in double quotation marks (" "), the parameter is changed to all uppercase.
  • 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:

    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 qualifier. For example:

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

You can define the logical name TCPIP$ESNMP_DEFAULT_TIMEOUT to modify the default time allowed (3 seconds) before timeout occurs due to lack of response by the subagent to the master agent. The ability to define the timeout is especially useful for slower systems and systems with heavy network traffic. The logical name is translated at startup time.

The TCPIP$ESNMP_DEFAULT_TIMEOUT timeout values are 0 to 60 seconds. (You should only use 0 for testing purposes such as simulating problems on a heavily loaded host or network.) If the value you specify contains nonnumeric digits or is outside the allowed range, the default value of 3 seconds is used.

For example, define TCPIP$ESNMP_DEFAULT_TIMEOUT to time out after 6 seconds of inactivity between the master agent and subagents:

$ DEFINE/SYSTEM TCPIP$ESNMP_DEFAULT_TIMEOUT 6

Note that when a subagent registers with the master agent, it can specify a value that overrides the value you set with logical name TCPIP$ESNMP_DEFAULT_TIMEOUT. The standard MIB-II and Host Resources MIB subagents use the default value of 3 seconds.

11.4.2 Modifying the Subagent Error Limit

In certain circumstances, some subagent programs might enter a loop where a select() call repeatedly returns a -1 error value. (Note that standard SNMP subagents and the Chess example provided in TCPIP$EXAMPLES should not exhibit this behavior.)

You can define the logical name TCPIP$SNMP_SELECT_ERROR_LIMIT to modify the number of times a -1 error value can be returned from a select() call.

The valid TCPIP$SNMP_SELECT_ERROR_LIMIT values range from 1 to less than 2 ³² -1 (default 100). When defining the error limit, remember:

• Do not use commas when defining the number.
• If defined as 0, no limit is set.
• A defined value greater than or equal to 4000000000 triggers warning messages.

For example, define TCPIP$SNMP_SELECT_ERROR_LIMIT to limit the number of times a -1 error value is returned to 1,000:

$ DEFINE/SYSTEM TCPIP$SNMP_SELECT_ERROR_LIMIT 1000

11.4.3 Ensuring Access to Mounted Data

If the proxy setup between the SNMP server and the NFS server is not correct, the Host Resources MIB subagent cannot access data that has been mounted.

To ensure access to mounted data, set up a proxy to an anonymous user (for example, to TCPIP$NOBODY) on the NFS server system. For more information about adding proxy entries, see Chapter 16.

11.5 Displaying the Current SNMP Configuration

To display stored information about the agent, use the SHOW CONFIGURATION SNMP command. Use the /FULL qualifier if you want to display the addresses that the agent recognizes as members of the community. For example, enter:

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.

11.6 Using the MIB Browser

TCP/IP Services provides the snmp_request MIB browser that acts as a simple client to handle single SNMP requests for reading and writing to a MIB. The browser sends SNMPv1 and SNMPv2 request PDUs to an agent and prints the agent's response.

To run the MIB browser, follow these steps:

1. Define a foreign command for the program:

   $ snmp_request == "$SYS$SYSTEM:TCPIP$SNMP_REQUEST"

   
   Or, you can run SYS$MANAGER:TCPIP$DEFINE_COMMANDS.COM to define all the foreign commands available with TCP/IP Services.

2. Enter the command using the following format.

   $ snmp_request agent "community" request_type [-v version] [-p port - _$ [-l] [-t] [-d] [-m max_reps] [-n non_repeaters [-w max_wait] - _$ [variable_name [data-type value]]

where variable_name is an object identifier (OID) in ASN.1 notation that is associated with each object in a MIB. For example:

$snmp_request host1 "public" getnext -d 1.3.6.1.6.3.1.1.6

Tables 11-3 through Table 11-5 describe the parameters, flags, and data-types.

11.6.1 Parameters

The snmp_request parameters are described in Table 11-3.

Table 11-3 Parameters for the snmp_request Command

Parameter	Function
agent	The host name or IP address (in dot notation) of the managed node to query. If you specify 0, 0.0.0.0., 127.0.0.1, or "localhost", the server on the browser's host is queried.
"community"	The community string to be used in the query. Case sensitive. Typically, agents are configured to permit read access to the community string "public". For accurate interpretation, be sure to enclose the name in quotation marks (" "). Note that if you do not use quotation marks, the name is changed to lowercase.
request_type	PDU type to send. Can be one of the following SNMP requests: get Sends a Get-Request PDU. getnext Sends a GetNext-Request PDU. getbulk Sends a GetBulk-Request PDU (SNMP Version 2 only). set Sends a Set-Request PDU.

For set requests, you can specify more than one group of variable_name, data-type, and value. For other requests, you can specify more than one variable_name except when you specify the -l or -t flag (valid only with a getnext or getbulk request, where only one OID is permitted). Note that data-type and value apply only to set requests.