DECnet-Plus for OpenVMS
Network Management

Many events are informational. They record changes to network components on both local and remote systems. Other events report potential or current problems in the physical parameters of the network.

An event report identifies the originating entity and the time when the event occurred. For those entities that report events, the DECnet-Plus Network Control Language Reference lists the events, the reason the event occurred, and any arguments reported to the event dispatcher.

You can set up event dispatching on a particular system, between two systems, or across multiple, distributed systems. Events that occur on systems running DECnet Phase IV or Phase V software can be reported by the DECnet-Plus event dispatching function.

12.1 Event Dispatching Concepts

When an entity notices that a condition has occurred, it generates an event message. The entity posts the event message and the local event dispatcher picks it up. The event dispatcher examines the user-defined event filters for each outbound stream created on the system. The event filter lets you selectively disable or enable the reporting of events based on the entity class and event type, or the specific entity instance and event type. If the event message passes the event filter, the message is given to the corresponding outbound stream.

An outbound stream maintains a queue of event messages waiting to be sent to their destination. After passing through the filter defined for the outbound stream, the event message is sent to an event logging component, called an event sink. An event sink can be on the same system, or a different system, as the outbound streams. When the event source and the event sink are on the same system, the outbound stream forwards the event report directly to the event sink. When the event sink is on a different system, the outbound stream encodes the event report in the form of Digital Network Architecture Common Management Information Protocol (DNA CMIP) calls, and forwards the DNA CMIP message to the corresponding event sink on the designated remote system.

For each outbound stream, there is a single associated event sink. However, a single event sink might process incoming event messages from more than one outbound stream. Systems can have a combination of outbound streams and event sinks (see Figure 12-1). You determine the actual event dispatching configuration established in your network.

Figure 12-1 Relationship of Outbound Streams and Event Sinks

The event sink accepts the incoming connection and creates an inbound stream entity to represent the connection. A sink can have multiple inbound streams, one for every outbound steam associated with the sink. The inbound stream remains for the life of the association between the outbound stream and the event sink. This connection can receive many event messages. Inbound streams are deleted when the connection between the outbound stream and the event sink is deleted.

An event sink maintains a queue of events waiting to be processed by another event logging component called the event sink client. Event sink clients are applications that process the event messages for you. The event dispatcher provides default event sink clients.

You can record events that occur on systems running Phase IV software by defining a relay on a DECnet Phase V system.

Figure 12-2 follows the path of a sample event report from a source, the routing entity on the .admin.finance system, to a sink on the .admin.netmgr1 system. A numbered list follows Figure 12-2 and explains the event dispatching sequence.

Figure 12-2 Sample Event Dispatching Sequence

1. On the .admin.finance system, the routing entity detects a corrupted link state packet (LSP). The routing entity posts a corrupted lsp detected event. The system's event dispatcher picks up the message.
2. The event dispatcher checks the filters associated with the outbound streams to see if the event message should be made available to the outbound streams.
3. Outbound stream obs_1 includes a filter setting that lets the routing corrupted lsp detected event pass onto its event stream. The filters associated with obs_2 and obs_3 block the entry of this event onto their streams. After filtering, the event report is encoded in DNA CMIP because the outbound stream defines a sink on remote system .admin.netmgr1.
4. The event message waits on a queue to be transmitted to system .admin.netmgr1.
5. On system .admin.netmgr1, the event sink, sink_a, creates an inbound stream when the outbound stream from node .admin.finance connects to the sink. The inbound stream remains until the event stream between obs_1 and sink_a is deleted by means of network management commands or connection timer expiration.
6. The inbound stream passes the routing corrupted lsp detected event message to event sink, sink_a. At sink_a the event can be filtered out of the event stream or passed to the sink client.
7. A sink client uses ASCII data to format the event message into the kind of event report that you want.
8. The sink client delivers the event report to the defined output destination.

You can define event filters with outbound streams, event sinks, or both outbound streams and event sinks. This section explains how the filtering process works.

Event filters let you:

• Restrict event records to only those events that you consider important to your network management tasks. Those events that you exclude still occur, but information about them does not appear in the event stream's report.
• Categorize event messages into separate event streams and, consequently, each stream's report. For example, you can use event filters on an outbound stream that only accept routing circuit events and pass it along to its event sink and the stream's report.

You can establish filters:

• At a source node by defining them with each outbound stream entity. (Digital recommends that you establish filters at the outbound stream to avoid unnecessary system overhead and network traffic.)
• At a destination (sink) node by defining the filters with the event sink entity.
• At both source nodes and sink nodes.

Event filters have three settings, which DECnet-Plus searches through in this order: first, specific filter setting; then, global filter setting; and finally, catch-all filter setting. The first filter that applies to an event is used to discard the event or enter it into the dispatching stream.

1. Specific filter setting
   Contains one or more entries, each specifying what action to take if the current event matches a full event string specified in this filter. A full event string consists of a global entity instance, an event name, or all events. For example:
   ((nodenode-id routing circuit circuit-id), corrupted lsp received).
2. Global filter setting
   The global filter is searched when no match is found in the specific filter setting, or if a match is found, but the action specified is ignore. The global filter setting contains one or more entries. Each entry specifies what action to take if the current event matches a defined global entity class, an event name, or all events. For example:
   ((routing, circuit), corrupted lsp received).
3. Catch-all filter setting
   The catch-all filter is searched only when no matches are found in the specific and global filter settings, or if a match is found, but the action specified is ignore. The catch-all filter declares the single action (pass or block) that should be taken for any events that filter down to this category.

The options (from the perspective of the outbound stream entity) are to:

• Prevent an event message from entering the event stream by using the block filter action.
• Forward the event message to the event sink associated with this outbound stream, by using the pass filter action.
• Ignore the event message and pass it to the next filter level, by using the ignore filter action. You can use the ignore filter action only with the filter's top-level specific setting or with the filter's second-level global filter setting.

To see which filters are currently in place, check the following files:

SYS$STARTUP:NET$EVENT_STARTUP.NCL

SYS$MANAGER:NET$EVENT_LOCAL.NCL

You may not need to change the event filters at all, unless you want to handle them differently than the defaults shown in that file.

If an entity is not included in the specific or global filter display, this means that the event action for all events of that entity (instance or class) is ignore.

Figure 12-3 shows the sequence of filtering through the hierarchy of event filters.

Figure 12-3 Sequence of Event Filtering

Note

You cannot use wildcard characters with the entity class name or instance name in the definition of a filter's specific setting.

See Section 12.3.14 for examples of using filtering with outbound stream entities, and Section 12.3.5 for filtering examples for event sink entities.

12.3 Setting Up and Using Event Dispatching

The following sections describe how to set up and use the event dispatcher.

Section F.1 provides a simple example that takes the defaults of setting up the event dispatcher. Figure 12-4 shows the event dispatcher entity and subentities.

Figure 12-4 event dispatcher Entity

By default, the event dispatcher entity is created and enabled on the local system in its script file. Thus, you may not need to start it yourself.

Use the NET$CONFIGURE.COM procedure to configure the event dispatcher. The event dispatcher usually starts as part of the NET$STARTUP procedure. If the NET$EVENT_STARTUP.NCL script file exists, the software creates the event dispatcher, invokes the event dispatcher script file (which creates and enables outbound streams, sinks, and relay), and enables the event dispatcher.

Digital recommends that you do not disable the event dispatcher at startup. If you do not wish to receive events, you can add the following command to SYS$MANAGER:NET$EVENT_LOCAL.NCL:

set event dispatcher outbound stream * catch all filter block   

This NCL script is described in Section 6.2.3.

Note

On an OpenVMS system, before the event dispatcher is enabled, event messages are queued. The messages wait for the event dispatcher to process them. After the event dispatcher is enabled, it can begin processing events.

You can use the following commands to check if the event dispatcher and its associated outbound streams and sinks states are enabled:

ncl> show event dispatcher state   
   
ncl> show event dispatcher outbound stream * state   
   
ncl> show event dispatcher sink * state   

If you attempt to use the event dispatcher, an outbound stream, or a sink that is not available, you will receive an error indicating that the command failed for the following reason:

no such object instance

You can start the event dispatcher after running NET$STARTUP with the following command:

$ @sys$system:startup network evd    

Each event generated on a system is filtered through each outbound stream. The stream delivers the event to a particular event sink that exists on the local system or a remote system. If you set up more than one outbound stream, each outbound stream is affiliated with one sink. An event sink can accept event reports from one or more outbound streams, which can reside on the same or different system as the event sink.

Each outbound stream is represented by an event dispatcher outbound stream entity. Each event sink is represented by an event dispatcher sink entity.

When you establish outbound streams and event sinks, you:

• Indicate in the outbound stream definition which event sink will be associated with this outbound stream.
• Indicate in the outbound stream definition which events you will allow to be forwarded to the event sink.
• Indicate in the event sink definition which events the sink will accept. Usually, the event sink permits all the incoming events because the selection criteria was already established on the source system by the outbound stream(s).

Subsequent sections describe the steps you need to take to set up outbound streams and event sinks.

12.3.3 Identifying the Sink for an Outbound Stream

Before setting up the outbound stream, decide how you want to identify the associated local or remote event sink. The sink's identifying characteristics can be any of the following parameters to the set command:

• The full DECdns object name of the sink object associated with this outbound stream.
• The full DECdns node name of the sink associated with this outbound stream, and the end-user specification of the associated sink.
• The protocol tower of the sink associated with this outbound stream.

Note

The event sink identified in the set command need not exist when you associate the outbound stream with its sink. If the event sink does not exist, the NCL commands used to create and test the outbound streams work; however, no event messages are sent from the outbound stream until the sink exists and a connection is established.

DECdns Object Name

If .ADMIN.EVENT_SINKS.SINK_A is the DECdns object name for the sink associated with the netmgr1_obs outbound stream, the following example shows the set command used to form the affiliation:

ncl> set event dispatcher outbound stream netmgr1_obs -   
_ncl> sink object .admin.event_sinks.sink_a   

You should identify network components by their DECdns object name. If the location of a sink object defined in the DECdns namespace changes, the namespace administrator can easily update information about the change by modifying the object's single entry in the DECdns namespace. For more information, see the DECnet-Plus DECdns Management guide. Also see Section 12.3.9 for related information about the set object name command used with the corresponding event sink.

DECdns Node Name

If you choose not to define a DECdns object entry for a sink, use the sink node name and end-user specification, or use the sink address. For example:

ncl> set event dispatcher outbound stream netmgr1_obs -   
_ncl> sink node 0, sink end user number = 82   

In the previous example, leaving sink node 0 (zero) indicates that the event sink resides on the local system. If the event sink resides on a system that is different from the outbound stream's system, specify the full DECdns node name.

The end-user specification for the sink consists of one of the following:

• number= number (default = 82)
• name= name
• uic= [uic-identifier]username
• fullname= full-name

The end-user specification corresponds to the object number or name, and defaults to the standard event sink supplied on the node.

You must specify a matching end-user specification on the event sink to associate the outbound stream and the event sink. For more information about matching end-user specifications for outbound streams and sinks, see Section 12.3.10.

Session Control Towers

If the event sink resides on a system that is different from the outbound stream's system, you can specify the remote sink by specifying the session control towers (sink address) of the remote node.

To find the towers of the destination sink node, enter the following NCL command on that node:

ncl> show node 0 address   

If the event sink resides on the same (local) node as the outbound stream, set the sink node using either the node's full DECdns node name, or enter 0, which indicates the local node. For example:

ncl> set event dispatcher outbound stream netmgr1_obs sink node 0   

If neither the sink node nor sink address attributes has been set, the events for this outbound stream will be logged to the local node sink by default.

12.3.4 Creating an Event Sink

The following example creates an event sink named netmgr1_sink_a:

ncl> create event dispatcher sink netmgr1_sink_a -   
_ncl> maximum buffer size size (1)   

1. Allows you to assign a maximum buffer size.
   For OpenVMS systems, the default maximum buffer size is 16384 bytes.
   The buffer size must be large enough to hold the event dispatcher sink entity's events lost event. NCL returns an insufficient resources exception if the value is too low.
   If you notice that you receive a high events lost count, this might indicate that the maximum buffer size is too small.
   If over time you notice that the maximum buffer size value seems inadequate, you must delete the event sink and redefine it with a higher value. See Section 12.6.2 for the steps involved in deleting an event sink.

In most cases, the event filters defined on outbound streams sufficiently manage event reports sent to an event sink. By default, the specific and global filters are defined to pass this sink's pseudo-events and the catch-all filter is set to pass. Digital recommends that you define the filters at each source node where the outbound streams reside because, in cases where the source and sink reside on different nodes, setting up filters at the source avoids unnecessary network traffic between the source node and the sink node. Also, a consistent network management policy about where event filtering will occur can avoid confusion, especially when several network managers work throughout the network.

You have the option of defining event filters for an event sink. The filters apply to event messages received from all outbound streams that use this sink. That is, you cannot designate selected filter entries corresponding to incoming events from a specific outbound stream. The definition of event filters for event sinks is similar to the process used with outbound streams. See Section 12.2 and Section 12.3.14 for related information.

In the following example, assume that 10 outbound streams from 10 different systems let the station running event from all hdlc link logical station entities pass into the event stream sent to a sink called netmgr1_sink_b. If you decide this information is not important for the final report, you can filter it out. For example:

ncl> block event dispatcher sink -   
_ncl> netmgr1_sink_b global filter = -   
_ncl> ((hdlc, link, logical station), station running)   

Once you have set up the event filter for an event sink, use the testevent command to check that the filter works according to your plan. The testevent command returns a message specifying the action of the filter used. See the following example:

ncl> testevent event dispatcher sink -   
_ncl> netmgr1_sink_b event = -   
_ncl> ((node usa:.admin.artist hdlc link link-id -   
_ncl> logical station station-id), station running)   

Action = Block   
Filter = Global filter   

Note

You cannot use a wildcard character with the testevent command's event argument.

The testevent command might reveal an error in your logic about event filtering for this event sink. If this occurs, see Section 12.3.7.

12.3.7 Modifying an Event Sink Filter

The specific and global filter trees can only be modified by the pass, block and ignore directives. You can enter a new definition for the event. The new definition supersedes any previous definitions.

To delete the previous filter values you set and reinitialize them to their default values when the event sink was created, use the following command:

ncl> reset event dispatcher sink netmgr1_sink_b   

See Section 12.3.15.1 for related information.

Note

Modifications in the sink filters affect subsequently created inbound streams (connections from remote nodes) and not inbound streams already created.

After a sink receives and filters an event, the event message is queued to the sink client. The sink client delivers the event message as an event report to a specified destination.

The client type characteristic can be set only when the event dispatcher sink entity is disabled (that is, when the sink state is off). Attempts to set the characteristic when the sink state is on result in an error message.

DECnet-Plus provides three types of sink clients or destinations:

1. Console sink client
   Sends ASCII-formatted event reports to the system console, which is a system process that receives input from processes (like EVD) that want to inform a system operator or network manager of a particular status. Console sink client is the default.
   The sink client sends ASCII-formatted event reports to OPCOM. Sometimes, events are split into two OPCOM messages when only one OPCOM message is necessary for the event. All network operator terminals (terminals enabled through specification of the DCL command reply/enable=network) display these events.
   The following example specifies the console sink client. (See Figure 12-4 for the relationship of the sink subentity in the event dispatcher entity hierarchy.)

   ncl> set event dispatcher sink netmgr1_sink_a -   
   _ncl> client type console   
   

2. Device sink client
   Sends ASCII-formatted event reports to devices such as terminals or line printers. The following example specifies the device sink client:

   ncl> set event dispatcher sink netmgr1_sink_a -   
   _ncl> client type device   
   ncl> set event dispatcher sink netmgr1_sink_a -   
   _ncl> device name "full-device-name"   
   

3. Formatted file sink client
   Sends ASCII-formatted event reports to a file. To execute this command, you must be logged in as SYSTEM. The following example renames the default sink client file to a nondefault file name:

   ncl> set event dispatcher sink netmgr1_sink_a -   
   _ncl> client type file   
   ncl> set event dispatcher sink netmgr1_sink_a -   
   _ncl> file name file-specification   
   

   
   You should set the sink client type before the sink is enabled and inbound streams are created.

The DECdns namespace administrator can use option 10 of the decnet_register utility to register each event sink as an object in the namespace. For more information about the registration process, refer to the DECnet-Plus DECdns Management.

Once the event sink is defined as an object in the namespace, you can use the set command so that the DECnet-Plus Session Control layer on the sink node can deliver incoming event messages sent by outbound streams that used the DECdns object name for the sink. For example, if .admin.event_sinks.primary_sink is the object name in the namespace for an event dispatcher sink netmgr1_sink_a entity:

ncl> set event dispatcher sink netmgr1_sink_a -   
_ncl> object name .admin.event_sinks.primary_sink   

For the event sink, you must set an end-user specification, which can be one of the following:

• number= number
• name= name
• uic= [uic-identifier]username
• fullname= full-name

The default is number= 82.

Make sure that the end-user specification for both the sink and outbound stream match.

On an OpenVMS system, if you issue the following command on system .admin.finance, you need to issue an additional command to associate the sink and the outbound stream when setting up the outbound stream.

ncl> set event dispatcher sink netmgr1_sink end user name = accounting   

The following example shows how to issue the additional command. Specify the system where the sink is located and the same end-user name as specified for the sink.

ncl> set event dispatcher outbound stream netmgr1_obs -   
_ncl> sink node .admin.finance, sink end user name = accounting    

You can disable the display of UIDs as part of an event message by setting the displayUIDs attribute to false. For example:

ncl> set event dispatcher sink netmgr displayuids false   

  PROFILE_VMS_018.HTML
  OSSG Documentation
   2-DEC-1996 12:35:15.75

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal