DIGITAL TCP/IP Services for OpenVMS
Management


Previous Contents Index

10.7.4 Querying the NTP Server with NTPQ

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.


Chapter 11
Configuring SNMP

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:

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:

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:
    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:

11.2 SNMP Executable and Command Files

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:

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

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.

Important

You cannot use TCPIP$CONFIG to customize your existing SNMP configuration; TCPIP$CONFIG is intended only to set up a new SNMP configuration or modify an existing configuration.

To customize the current SNMP configuration (for example, to specify an additional community name and address), you must enter the SET CONFIGURATION SNMP command with applicable qualifiers.

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.

11.4.1 Modifying the Default Timeout

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 32 -1 (default 100). When defining the error limit, remember:

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.


Previous Next Contents Index