NOTE

This HTML document is not the original historical document, but it is a close representation of the manual provided to users of the IBM Research version of XGMON. The "productized" version of XGMON that shipped in the Network Management/6000 LPP for AIX was a butchered, reduced functionality variant. IBM Systems Engineers in-the-know didn't bother to install the "official" version but instead provided their customers with the current NSFNET version obtained from a TOOLSRUN machine in Yorktown. In that way, IBM AWD got paid via the purchase of the Network Management/6000 LPP and the customer got something that worked (by running the actively developed and supported IBM Research version). No customer ever had a feature addded to the "product" version of XGMON, whereas it was typical to have their request implemented and a test version made available the very same day for their use if they submitted a request to the team in IBM Research (either directly or via their local IBM systems engineering staff).

XGMON was designed and developed over an approximately 3 week period in May and June of 1988. The NSFNET backbone was to go live at the beginning of July of 1988 and while the IBM teams had been working to design and fabricate network cards, assemble, ship out and install the hardware at the 13 regional nodes, and develop the needed routing software, by May of 1988 they had not been able to create any network management software. IBM management was aware that failure to deliver this promised piece of infrastructure was unacceptable, so they had embarked on what most large companies with deep pockets would do:  trade money for time and try to find a vendor with a suitable technology and license it. Microsoft's payday with MS-DOS arose from a similar decision. The initial NSFNET technology developed by IBM violated the assumptions made by every available monitoring product.

The IBM solution for the NSFNET T1 backbone was called the Nodal Switching System, which were clusters of PC/RTs deployed at the regional points-of-presence. The cluster of nodes were joined together on a token-ring that was effectively a hidden internal bus. One node would be responsible for being the gateway interface to the regional network and several other nodes would drive their respective point-to-point links to other regional networks. At the time we called these “packet switching processors” and the gateway to the regional was labeled as an “exterior packet switching processor”. Of course, anyone who has had contact with IBM knows they don't use words but are instead addicted to “initialism”, thus these would invariably be referred to as PSPs or E-PSPs. Another node was dedicated to computing routing tables and distributing them to the local packet switching processors. Yet another node served as a dedicated packet sniffer which was used to collect statistics on traffic (the NSFNET contract required network-to-network statistics, so the reporting issues got large as the number of routes went over 30,000). Usually a site had at least 3 links coming into it, so this would mean there were typically between 6 to 9 nodes comprising the cluster. Thus what might appear to be a single node to the outside world was really implemented as many distinct physical hosts, any of which could fail. The original cards fabricated by the IBM hardware team were only capable of handling 1/3 of a T1's approx. 1.5 megabits per second, so we used NET IDNXs to overlay a different logical topology on top of the actual physical topology. For example, a node in Texas might think it had a direct link to California, but it would be realized by two physical links:  one that went to Michigan from Texas and another that went from Michigan to California.

All of the vendor products evaluated were variations on a theme:  they had a single window upon which icons representing hosts were drawn and they colored the nodes red or green based on whether the host was reachable. None of the vendors had products that could model a physical topology that was different from the logical topology, which was a significant problem given that both the logical point-to-point topology of the IP backbone and physical T1 topology provided by MCI were different and the Nodal Switching System itself was a cluster of several machines, not a single machine acting as a router. In short, none were designed to support a large WAN comprised of clusters of nodes and disjoint topologies, so a commitment was made to develop a solution in short order.

The XGMON design was guided by a few beliefs:

• Network bandwidth would be very constrained and the network was not put in place for the benefit of network management traffic, thus it would need to be minimized.  At that moment in time, we had entire regional networks that spanned several states funneled through a link that was slower than 500 kbits per second.  In those days, the closer you got to the end-user, the faster the links were.  For example, a user might be connected on a 10 megabit per second LAN that was shared with a handful of other users.  In contrast, his traffic to another regional would have to compete with many other institutions and be funneled through something 20 times slower. Today, the network core is typically the fastest component, but the need to share with other people remains.
• The monitoring system had to work 24x7x365; an untimely outage could delay discovery of a problem and increase the impact on a large user population—this was the national backbone, after all.
• Programs often have bugs.  As time went on, new applications would be developed.  Deploying new code without taking down the running system would be important.
• Different release levels needed to be able to run in parallel and it needed to be easy for an operator to drop back to a prior release if something bad happened.  You want an operator to be able to handle a situation if something crashes at 3am rather than call for support.
• If a problem in the network was detected, engineers would need to be able to quickly develop tools to make ad hoc inquiries, since time would be of the essence.
• The environment operators would encounter was an unknown, so enforcing much policy upon them would be a mistake.  Indeed, it was the fatal flaw of the other vendor products as they made assumptions that were completely invalid in the NSFNET backbone architecture.

The solution realized by XGMON was to create an environment in which multiple applications ran in parallel, backed by a cache of retrieved data and a graphic user interface of a hierarchical topology map that was driven as a side-effect of information that was received. The programs were written in an application-specific language, which would be compiled on-the-fly when a script was invoked and run inside a virtual machine. Each virtual machine had a dedicated output window in which it could display messages or draw graphics. Topology data was also described using a compiled language; both humans and programs could generate network description and it was easy to add features without breaking prior conventions.

Unlike other vendor products of the time, the network topology was hierarchical: opening a node for Ann Arbor would display in a new window the various physical nodes that resided at that site.  Nodes were colored based on the worst news beneath them (e.g., down, unknown, acknowledged, OK). While colors were used, additional visual indicators (like inverse text) were used so that color-blind operators would be able to distinguish states and this was tested using monochrome displays.

Replacement of a buggy program was as easy as installing the new script into a filesystem directory and running it; the management system itself never had to be stopped. Three versions of the framework could be deployed in parallel: the prior one was named with the suffix of “-” and the most recent was labeled with a suffix of “+”. After approximately 3 weeks of development and nearly 15,000 lines of C later, the initial version was ready for deployment at the NSFNET Network Operations Center in Ann Arbor, MI.

As a result of the design decisions made, the technology got used at many places other than the NSFNET backbone. For certain, other national backbones (e.g., CA*Net) and internal corporate backbones (Boeing, Motorola, etc.) used it for their networks, but the flexibility caused TRW to use it to build a display for satellite tracking and SIA used it in their Milan NOC to monitor their HP-based networks despite not having any SNMP agents deployed. In subsequent years, the NSFNET physical architecture changed and we colored links based on Intermediate System-to-Intermediate System reachability rather than the conventional interface operational status. We also dynamically adjusted the width of drawn links based on traffic volume. To avoid bothering operators with notifications of problems they could not handle, displays could be set to delay notification of an alert for an arbitrary number of seconds (bad news was delayed, good news was in real-time). Thus if a link bounced for 5 seconds, it would be logged for engineers but alarms would not go off in the NOC and shock an operator who would have nothing to do because the problem resolved itself so quickly.

The best design decision made in XGMON was to have the topology display colored as a side-effect of information being received, rather than via an active script. So much came for free as a result of that one decision, including clusters of multi-user operator displays. As a general principle, XGMON provided function, not policy, and this enabled its usage in a wide variety of environments throughout the world, even as the platform for applications that had nothing to do with network management. The worst design decision was to have the gw_var() function return content of different types when the language lacked support for an any type and thus a cast was required on every usage. Subsequent efforts, like OIL in DRAGONS, rectified that oversight. As the result of a 3-week crash design and implementation effort, XGMON proved to be remarkably flexible and useful.

XGMON Guide, IBM Research Version, Release 92-7

XGMON
 
IBM Research Version
 
Release 92-7
 
 
Program Description and Operations Manual

July 10, 1995

Document Number xgm92-7

Geoffrey Carpenter
Bert Wijnen

IBM T. J. Watson Research Center
P.O. Box 218
Yorktown Heights, NY 10598
USA
 
GCC at WATSON
gcc@watson.ibm.com
WIJNEN at UITVM1
wijnen@uitvm1.vnet.ibm.com

Trademarks

The following terms used in this manual are trade marks:

Trademark	Owned by
AIX	IBM Corporation
LANtern	Novell, Inc.
MOTIF	Open Software Foundation Inc.
NetView	IBM Corporation
PS/2	IBM Corporation
RISC System/6000	IBM Corporation
RT	IBM Corporation
UNIX	AT&T Corporation
X-Window System	Massachusetts Institute of Technology
X11	Massachusetts Institute of Technology

Preface

Building on the experience of using the monitor in the day-to-day operation of the NSFNET, the monitor has been improved over time not only to reply to operator requirements, but also to follow new standards in TCP/IP network management.

This guide documents the current version of the xgmon TCP/IP Network Monitor.

To understand xgmon--and to be able to exploit it to its full potential--you should have a working knowledge of UNIX, C programming and general TCP/IP network management protocols.

If you find this guide difficult to use, if you have trouble locating the information you want, or if you discover errors in the book, we would appreciate hearing from you directly. In that case, please inform us via electronic mail.

This guide refers to the Simple Network Management Protocol (SNMP) and the Management Information Base (MIB) which are described in the documents listed below. You may want to have these references at hand.

Note: To familiarize yourself with xgmon we suggest that you read the part titled User's Guide first. It gives you an overview of the functions and capabilities of xgmon.

Related Documentation

Several RFCs (Request For Comments) describe the Internet standards for network management.

The following RFCs are available on the RFC disk managed by ARCNET at ALMVMA (for IBM internal users). They can also be obtained from NIC.DDN.MIL via anonymous FTP.

• RFC 1155, Structure and Identification of Management Information for TCP/IP-based internets (SMI).
• RFC 1156, Management Information Base for Network Management of TCP/IP-based internets (MIB I).
• RFC 1157, Simple Network Management Protocol (SNMP).
• RFC 1158, Management Information Base for Network Management of TCP/IP-based internets (MIB II).

With this shipment of xgmon we also included a paper that we presented at the

Systems and Network Management Symposium 90

IBM internal users can obtain all of the above documentation as SNMPDOC PACKAGE on the XGMON disk, managed by NSFTOOL at YKTVMZ.

Support

Internal to IBM

External to IBM

    xgmon-l-request@CAnet.CA

    xgmon-l@CAnet.CA

    gcc@watson.ibm.com
    wijnen@uitvm1.vnet.ibm.com

Note: please don't violate the acceptable use policies of the NSFNET by sending e-mail directly to the authors from a commercial organization. As a last resort, hardcopy can be FAX'd to us at (914) 945-2141.

At this time, we cannot respond to telephone inquiries--send mail, either directly or have someone from the local IBM branch help you. Our goal remains to support you on a best-effort basis for fixes to reported problems.

Acknowledgements

The SNMP parser used in the xgmon core was constructed using tools from the ISO Development Environment (ISODE), originally developed and made openly available by The Northrop Corporation and later maintained by The Wollongong Group.

Tom Molnar and Paul Kern of the University of Toronto take care of the xgmon-l mailing list and maintain an archive of user-contributed xgmon enhancements. The robustness of the SNMP Query Engine owes much to their extensive use and stress testing of xgmon in a multi-user environment.

Table of Contents

Part 1: User's Guide

Part 2: Installation and Customization Guide

Part 3: Reference Manual

Part 4: Appendixes

Part 1: User's Guide

 Contents:  

This part of the guide describes:

• General xgmon concepts.
• Overview of xgmon functions and features.

The chapters and their contents are arranged in such a form that they are best understood if you read them in sequence.

Introduction

The xgmon system is extendible because new commands can be added in much the same way new commands are added to the UNIX operating system. One simply writes an appropriate program in the G (Gateway) programming language, and it can be made available as a new command.

The xgmon core contains a compiler that translates programs written in G into G-code. G-code is the object code that is interpreted by the virtual G machines. The operation of the virtual G machines is overseen by the xgmon core. Each virtual machine works on its own program and, because xgmon is able to control more than one virtual G machine, more than one program can be executing at the same time.

The xgmon program is able to communicate with SNMP agents and is also able to receive SNMP-based traps. Trap information normally arrive via the conventional SNMP UDP packets. These traps are made available to programs executing within virtual G machines. In addition, ping (ICMP ECHO/ECHO RESPONSE) can be used within xgmon to check the reachability of hosts.

The xgmon client has many features intended to deal with the constraints of a monitoring a production, highly-available TCP/IP network. Some of these are not obvious to the user, but others are quite visible.

The xgmon core provides several features intended for the operator/end-user. These include acknowledgement of network failures, distinctive audio alerts, and a topology display that can lag behind real-time so as to ignore short, transient failures of network components.

Although targetted towards single-user use, multiple copies of xgmon can be used in concert when joined with an SNMP Query Engine. A single copy of xgmon can drive the topology displays of the other instances, as can any other network management system connected to the SNMP Query Engine (in such a case, the xgmon topology display can serve as a graphic interface to the foreign network management system).

User's Overview

This chapter provides an overview of a subset of xgmon features. Users who wish to customize the base xgmon distribution will find the following chapters helpful:

• "G Language"
• "G Topology Description Language"
• "XGMON Core Extension"

System Administration

The xgmon system is intended to be maintained by a system administrator who insulates the end-user from many of the xgmon installation details.

The system administrator is responsible for properly installing new versions of the xgmon system. This may entail aging the existing distribution (see "Version Control"). The system administrator is also responsible for adding user-contributed library commands to the set of globally available commands.

Version Control

A highly-available, production TCP/IP network is monitored continuously. The xgmon client was developed with the understanding that:

1. the system administrator may not always be available, and
2. new releases of xgmon components may contain bugs.

This feature, for example, enables a third-shift operator who detects a problem with the new version of the xgmon system (xgmon+) to quickly back out to the older, production release (xgmon) simply by terminating the program and invoking "xgmon" instead of "xgmon+". The operator doesn't need to be concerned that the two releases may be incompatible in terms of language accepted, library commands used, start-up commands executed, etc.--these details are handled transparently by the xgmon client.

Library Commands

The xgmon core provides a set of general purpose, intrinsic functions which are used by library commands to perform work. All active processing is performed by library commands which are programs external to the xgmon core. Any local customization of algorithms is embedded in library commands--the core is normally not altered.

Note: as shipped, the xgmon distribution also provides for extension of the core by a C programmer.

The xgmon client is extendible because new commands can be added in much the same way new commands are added to the UNIX operating system. One simply writes an appropriate program in the G (Gateway) programming language, and it can be made available as a new command.

Library commands are stored as source code. When a library command is used, the xgmon client compiles the library command source into G-code, which is then executed.

This provides several advantages. New library commands can be added at any time and used without having to terminate the current xgmon program. Similarly, library commands that have bugs can be corrected without having to stop everything. This means that algorithms can be corrected without having to lose global state information that has already been collected and thus a failure of one component (e.g., a library command) does not necessarily incapacitate the rest of the monitoring system. The end-result is to provide a monitoring system that attempts to be as highly-available as the network it is monitoring.

As noted, new library commands can be added at any time. A user can develop and test a library command by storing the command source in a directory belonging to the user and appropriately setting the GLIB environment variable (see "Installation And Customization"). After a command is debugged, it can be submitted to the system administrator for possible inclusion in the global list of library commands, thus making it available to all xgmon users.

XGMON Start-up

When a user invokes the xgmon program, the default behavior is for xgmon to ask the X11 server indicated by the DISPLAY environment variable to create several windows for the output from the Virtual G machines (discussed below). As each window is placed, the xgmon client decrements and displays the count of the number of windows not yet displayed.

After all of the windows are placed, the file .xgmonrc, found in the user's home directory, is read (if it exists). This file name is modified based on the run-time version control, so the actual name would be:

Version	Actual File Name
xgmon-	$HOME/.xgmonrc-
xgmon	$HOME/.xgmonrc
xgmon+	$HOME/.xgmonrc+

Note: it is not considered an error if the file does not exist.

After processing the appropriate .xgmonrc file, the xgmon client prompts the user for commands.

Virtual G Machines

As noted above, the xgmon core is essentially a passive entity. Any required monitoring algorithms are embedded within library commands, which are programs written in the G language. These programs are stored as source code.

The xgmon client contains a compiler that translates programs written in G into G-code. G-code is the object code that is interpreted by the virtual G machines. These are imaginary machines that execute G-code object code output by the compiler. Each machine works on its own program and is essentially independent of all the others (it is possible to implement some inter-machine communication, if needed).

The operation of the virtual G machines is overseen by the xgmon core. Multiple, independent commands may be in progress at the same time because the core is able to control more than one virtual G machine simultaneously.

When running under X11, each virtual G machines has a window associated with it. A program (library command) running in the virtual G machine may write output to this window. It is also possible for graphics to be drawn in this window, thus it is not a text-only "output device".

Each virtual G machine has a standard output device. Normally this is associated with the above mentioned window; however it is possible to redirect the output from a virtual G machine into a file instead of to the window.

Note: glass TTY operation is supported in situations where X11 is not available or needed. In this case, output from a virtual G machine is not sent to a separate window, but instead appears on the standard output. Note also that graphics are only supported when running with X11.

When necessary, a virtual G machine can determine if the graphics function is available (i.e., its standard output is being sent to a window).

XGMON Invocation

Certain default xgmon behavior can be overridden by invoking xgmon with command line arguments.

By default, xgmon will attempt to connect to an X11 server. This can be inhibited by specifying the "-nx" (no X11) option on the command line.

xgmon -nx

When this is done, all output written by a virtual G machine to its standard output device goes to the standard output associated with the xgmon core, not a graphics window.

By default, xgmon will attempt to bind the SNMP trap port. This can be inhibited by specifying the "-nt" (no traps) option on the command line.

xgmon -nt

The xgmon core will normally make available for use half of the virtual G machines it can support. The number of virtual G machines to be used can be reduced or increased by specifying a limit on the command line. This is done by using the "-m" (machine) option and specifying a maximum number of machines to be used. The example below limits the xgmon invocation to using two virtual G machines.

xgmon -m 2

Note: some long-lived G programs survive by "hopping" from one virtual G machine to another. For this to work, there must always be one free machine available.

Normally, xgmon will read an initial set of commands from the startup file .xgmonrc (see "XGMON Start-up"). This can be overridden by using the "-rc" option to specify a different file. The specified file name is not subject to version control.

xgmon -rc filename

Normally, xgmon selects the desired X11 server based on the value of the DISPLAY environment variable; however, this can be overridden on the command line using the "-display" option:

mnementh% xgmon -display gcc2:0

The xgmon core can also be passed an initial library command to be executed as a parameter on the command line when it is invoked. This permits G programs to be written and subsequently used like a normal C program or shell script. When xgmon is invoked with an initial library command, it will automatically terminate when all of the virtual G machines become unloaded. The following example illustrates how this can be exploited:

xgmon -nx -rc /dev/null snmp_get -c public hostname sysDescr > tmp

The above example invokes xgmon and inhibits using X11 (with the "-nx" option). It also overrides any default set of startup commands (.xgmonrc) by indicating that /dev/null is to be used instead (which will return end-of-file immediately). The snmp_get library command is then run by the xgmon core. The shell has already taken care of redirecting the output into the file tmp. When the snmp_get command terminates, xgmon will terminate automatically. The end result will be to have the output from the command stored in the file tmp.

System Commands

The majority of commands available to an xgmon user are classified as library commands. These are actually G programs, stored as source code in the appropriate directory, which are compiled into G-code and executed when required.

There are, however, a small number of commands which are built into the xgmon core. These commands are classified as system commands. In general, system commands are used to control the virtual G machines. Some of the system commands that are available:

Command	Function
start	start a loaded machine
stop	stop an executing machine temporarily
unload	clear and release a machine
stat	display status of loaded virtual machines
compile	compile G program and load object code
quit	terminate xgmon
readdir	re-read library command directory
hostdata	specify auxiliary host name/address file
clearcache	clear internal cache of host names
query	query internal database about a host

The stop command can be used to stop a virtual G machine from executing any more instructions. The start command can be used to allow it to continue execution.

The unload command is used to terminate and unload a program executing in a virtual G machine. All resources associated with the virtual G machine and the program are freed.

The compile command is useful when developing a new library command to check the source for correctness. If the compile is successful, the resultant G-code will be placed into the first available virtual G machine. If the program takes no arguments, it can be started by using the start command. The compile command is also used to compile topology descriptions.

If a new library command is added to the library command directory while the xgmon client is running, the readdir command can be used to force the client to notice the new command; however, if the user references a library command whose name is not recognized, the xgmon core will automatically recheck the directory to determine if the command has been added. The real use for readdir is to remove knowledge of a library command if it has been deleted.

Often a user does not have permission to add new entries to the system's host name/address database, whether it be the file /etc/hosts or a name server. Sometimes it is also not desirable to modify these global resources for the purposes of network management. The xgmon core permits the specification of an auxiliary host name/address mapping file, which is in a format similar to that of /etc/hosts. Information specified in the auxiliary file takes precedence over that maintained by a name server or in /etc/hosts. If the required information cannot be found in the auxiliary file, then the xgmon core falls back to a name server or /etc/hosts.

The xgmon core makes intense use of an internal cache of host name/address mappings. Alterations to the host name/address database maintained by a name server or represented in /etc/hosts can result in the information contained in the xgmon internal cache being incorrect. The clearcache command is used to force the xgmon core to abandon its current set of cached mappings and re-query the host's host name/address database for updated data.

Topology Displays

When running under X11, the xgmon core is able to graphically present a network topology map. The layout of the map is statically described using the G topology description language. The topology display supports a hierarchical organization.

The topology display is automatically updated when status information is received by the xgmon system. Programs running in virtual G machines are not responsible for actively updating the status of displayed network elements.

Note: it is possible, if necessary, for a virtual G machine to control how a given display element is colored.

There are several basic kinds of display elements:

Type	Used to represent
host	a host, interface or user-defined box
node	grouping of display elements
line	a point-to-point link

Each display element has a state associated with it. When running on a color display, these states are represented by different colors. On monochrome (black and white) displays, the state is represented by different shading and labeling styles. The following table summarizes this:

Table 1. Display Element States (nodes/hosts)

State	Color	Monochrome
up/ok	green	white background
down	red	black background
unknown	yellow	shaded, white letters
acknowledged	cyan	shaded, black letters
ignored	violet	shaded, black letters
inactive	blue	shaded, black letters

On a monochrome display, link states are indicated by altering the line style used to draw the line. On color displays, they appear as solid lines of the appropriate color.

Table 2. Display Element States (links)

State	Color	Monochrome
up/ok	green	solid line
down	red	dotted line, large spaces
unknown	yellow	dotted line, finely spaced
acknowledged	cyan	thin dashed line
ignored	violet	thin dashed line
inactive	blue	thin dashed line

A user can view lower layers of the hierarchy by positioning the mouse pointer over a node and pressing the left mouse button. This will result in a new window being created that displays the network elements grouped under that node.

Note: if the window already exists, a duplicate will not be created. Instead, the xgmon client will attempt to raise the window. This may fail, depending on the window manager in use.

A display element whose state is down or unknown generally indicates a problem. A user can acknowledge the problem and thus visually indicate that situation has been noticed by positioning the mouse pointer over the display element and pressing the middle button.

This results in the display element state changing to acknowledged. If the xgmon system determines that the network element associated with the display element is operational, it will automatically change the acknowledged state to up.

Occasionally, a situation may arise in which a network element is undergoing testing and, as a result, its operational state is changing between up and down quite frequently. An operator may want to ignore that network element while this testing is going on. He may do so by positioning the mouse pointer over the acknowledged display element and pressing the middle button one more time. The ignored state can be released by pressing the middle button yet a third time to change the state to unknown.

The user can also use the topology display to communicate information to a virtual G machine. This is done by positioning the mouse pointer over the display element in question and pressing the right mouse button. This sets the name of the display element in the global variable selected_host (See "G Language"), which can then be used by any library command (G program).

If the user double-clicks the right mouse button, then the library command associated with the display element will be executed (the default is right_click). The library command is passed the name of the display element as an argument.

To associate a library command with a display element, you can use the setenv library command as follows:

setenv disp_elem RIGHTCLICK lib_cmd

Note: a G programmer can also use the setenv intrinsic function to associate a G program (library command) with a display element dynamically.

Part 2: Installation and Customization Guide

  Contents:  

This part of the guide describes:

• Hardware and software requirements for xgmon.
• How to install xgmon on your system.
• How to tailor and customize xgmon for your needs.

Installation And Customization

The IBM Research TCP/IP network monitor program, xgmon, is designed so that it can be readily customized by the end-user; however, to do this, the end-user must know where the relevant directories are placed and what features can be altered by appropriately setting environment variables.

That information is detailed in this chapter.

Supported Hardware

• IBM RT/PC, any model
• IBM PS/2, models that support AIX (e.g. 80386 based)
• IBM RISC System/6000
• IBM Megapel display (5081)
• IBM APA Monochrome displays
• IBM PS/2 8514/A attached displays
• IBM PS/2 VGA attached displays
• IBM ASCII terminals (line-mode)

Supported Software

• AIX 2.2.1 and up (for the IBM RT/PC)
• AIX PS/2 1.1 and up.
• AIX/370
• AOS 4.3BSD (for the IBM RT/PC)
• AIX 3.1 for the RISC System/6000

Installation

As shipped, the xgmon distribution resides under the directory /usr/lpp/xgmon. The xgmon binary is found under the bin sub-directory and the library commands are stored under the lib sub-directory. This binary may be copied or moved to a directory already in the user's search path or the directory itself may be added to the search path.

The xgmon program must be run with "root" privileges to support all of its capabilities, so it is normally installed as a set-uid program owned by root.

Version Control

The xgmon system supports run-time version control which permits up to 3 distinct, incompatible releases of the same program to be installed on a host. These releases are distinguished by the name used to execute the xgmon program. The previous, not-current release of xgmon is, by convention, named xgmon- (a minus-sign suffix). The most recent, test version of xgmon is, by convention, named xgmon+ (a plus-sign suffix). Lastly, the current, production version is, by convention, named xgmon (no plus- or minus-sign suffix).

The different suffixes indicate different, distinct versions, but the actual ordering from old to current to test is maintained by the local system administrator. The run-time version control system does not enforce the meanings of the different suffixes--it only provides for supporting distinct versions.

The run-time version control system affects what directories are used to store xgmon library commands as well as the name of the user's start-up script. The directory or filename is modified by adding the same suffix as that of the xgmon program that was executed. Thus, whereas running xgmon would result in the default directory being /usr/lpp/xgmon/lib, running xgmon- would result in the default directory being /usr/lpp/xgmon/lib-. similarly, running xgmon+ results in the directory /usr/lpp/xgmon/lib+ being used.

Note: the xgmon library command directory name can be overridden by the environment variable GLIB. In this case, the appropriate suffix will be added to the name specified by the environment variable. For more information on environment variables used by xgmon, see "Environment Variables".

Additions to /etc/services

The following entries should be added to /etc/services to provide the xgmon program with the information it needs for sending requests to remote agents and receiving traps (alerts).

Note: if these entries are not added, xgmon complains but will still use the values below as defaults.

snmp	161/udp
snmp-trap	162/udp
snmp-trap	162/tcp

MIB Variables

The xgmon client obtains its description of Management Information Base (MIB) variables from the file mib_desc found in the current library command directory. This file has the following format:

Name	Object ID	type	TTL
sysDescr	1.3.6.1.2.1.1.1.	string	900

The fields are separated by spaces or tabs. The name field holds the text description of the object. The object ID field is the object identifier prefix assigned to the object class. It is entered with a trailing dot (".") at the point just prior to where an instance would be specified. The type field denotes the type of the object and can be one of:

• number
• string
• object
• internet
• counter
• gauge
• ticks
• display
• table

Note: the type display is used to denote a MIB variable that contains textual data. The type string is used to denote a MIB variable that will contain binary data. Both types map to the OCTET STRING type defined in the Structure of Management Information (SMI) RFC.

Note: the type table is essentially a comment that indicates that the corresponding object ID denotes the path in the MIB naming tree that references a table. While all other types indicate leaves in the tree, table indicates an intermediate node.

The final field holds the time-to-live value. This is the amount of time, in seconds, that the xgmon core should consider the data as valid. As long as a particular value is considered valid, the xgmon core will not generate a query to obtain it. In some situations, network traffic can be reduced by increasing the time-to-live value for a particular variable class. The time-to-live value should never be less than one second.

The distribution includes a mib_desc file that contains all the variables as specified in RFC 1158 (MIB-II).

Environment Variables

The xgmon program provides some means for overriding default choices that may be inappropriate or undesirable for some users. The following is a list of environment variables that may be set by the user:

Variable	Meaning (default)
GLIB	Library command directory (/usr/lpp/xgmon/lib)
XGMONFONT	X11 font to be used (8x13)

Note: the font specified should be of fixed width for proper operation. The xgmon client deals correctly with variable width fonts in a topology display, but the results will not be as desired when used in a virtual G machine output window.

Start-up Commands

An xgmon user may create a file containing commands to be executed by xgmon whenever it is started by the user. This file is placed in the user's home directory (determined by the value of the HOME environment variable) and is named .xgmonrc. This file name is modified using the run-time version control documented above. Thus, if xgmon+ is run, the initial set of commands will be read from the file $HOME/.xgmonrc+.

.Xdefaults Resources

The xgmon core will use the (standard) .Xdefaults file at initialization to find your preferences for window defaults. The following xgmon specific class identifiers are recognized:

Top	Topology windows
G	Virtual G Machine Windows
Color	Colors associated with states like up, down etc.

The following xgmon-specific name identifiers are recognized:

force_monochrome	specifies (yes/no) if you want to force monochrome mode on a color display.
disable_screensaver	specifies (yes/no) if you want the screensaver to be disabled by xgmon. The default is no.
font	specifies the font to be used for the topology display. This font is also used as the default font for the virtual G machine windows and in such a case, the font specified should be of fixed width for proper operation. If a font is specified for text_font, then this may be of variable width.
text_font	specifies the font to be used for text output in virtual G machine windows. It must be of fixed width for proper operation.
root_name	the name of the top-level topology display window. The default name is "IBM TCP/IP Network Monitor".
backing_store	enables (yes/no) the use of the X11 server's backing store for XGMON windows. This can provide great performance gains by eliminating unnecessary window redrawing operations; however, the backing store option is not implemented correctly in some servers. This defaults to "no".

A topology window can be uniquely identified by its name. If the name contains blanks, these must be replaced by underscores when qualifying a resource specification.

xgmon.Top.IBM_TCP/IP_Network_Monitor.geometry:  400x200+50+50

xgmon.G.2.autoplace:  yes

The following resources for windows created by xgmon are recognized:

autoplace	specifies (yes/no) if automatic placement of windows is wanted. If you specify a location (x and y coordinates) in your geometry specification, that is considered to be an implicit yes for the autoplace resource. If you do not specify a location but do specify autoplace is yes, then xgmon will place windows automatically at an internally defined location.
geometry	specifies the size (width, height) and position (x, y) of the window.
iconic	specifies if the window should be initially created as an icon (if the value is "true" or "yes").
cursor_icon	specifies the name of an icon image to be used as the cursor for the window (topology windows only).

Within the Color class of resources:

down	specifies color for the down status
up	specifies color for the up status
inactive	specifies color for the inactive status
ignore	specifies color for the ignore status
acknowledge	specifies color for the acknowledge status
unknown	specifies color for the unknown status
initial	specifies color for the initial state
background	specifies color for the topology backgrounds
text_foreground	specifies color for the text window foreground
text_background	specifies color for the text window background
icon_mask	specifies the color for the icon masks

The following is an example of xgmon entries in your .Xdefaults file:

!xgmon.Top.IBM_TCP/IP_Network_Monitor.autoplace: no
xgmon.Top*autoplace:    yes
xgmon.G.0.geometry:     =200x300
xgmon.G.1.geometry:     =500x200+500+600
xgmon.G*geometry:  =32x30
xgmon.G*autoplace: yes
!xgmon.force_monochrome:     yes
!xgmon.backing_store:     yes
! The following all have their default values specified...
!xgmon.font:       8x13
!xgmon.Color.down: red
!xgmon.Color.up:   green
!xgmon.Color.inactive:  blue
!xgmon.Color.ignore:    violet
!xgmon.Color.acknowledge:    cyan
!xgmon.Color.unknown:   yellow
!xgmon.Color.initial:   orange
!xgmon.Color.background:     gray
!xgmon.Color.text_background:  black
!xgmon.Color.text_foreground:  red
!xgmon.Color.icon_mask:   gray

XGMON Core Extension

The xgmon core can be extended by a C programmer. This is done by making available new intrinsic functions to G programs. A user-written intrinsic function can override an intrinsic function already in the xgmon core. This is done simply by naming the new intrinsic function the same name as the existing function it is to replace.

As distributed, the xgmon core is broken up into up to three distinct object files.

xgmon.o	the basic xgmon core
user_func.o	user-defined intrinsic functions
de_stubs.o	stubs so that an xgmon.o module compiled to be DRAGONS Data Engine-capable can be linked by the end-user. This file is not present in all distributions.

Adding an new intrinsic function requires choosing a name for it, determining the types the function can return (like int, string or pointer) and the name of the C routine that will implement it. Of course the C routine to implement the function must be written.

These three pieces of information must be added to tables, which are defined in the user_func.o file. The structure of these tables are shown below in the sample user_func.c file. This example implements several intrinsic functions:

cast	allow arbitrary type casting
search_int	search a table of integers for a key
search_string	search a table of strings for a key
listen	listen for TCP connections

Note: the style of including header files in the middle of a source program is not recommended. It is done in this example only to keep the particular sections well-focused.

Figure 1. Sample user_func.c

/*
XGMON user-defined functions
*/



/*
* function types: integer, string, pointer
*/



#define T_INT 256
#define T_STRING 512
#define T_POINTER 1024



typedef void (*Callback) ();



extern void add_user_fd();
extern void delete_user_fd();



/* declare function names here */
static unsigned long cast_proc();
static unsigned long search_int();
static unsigned long search_string();



static unsigned long listen_on_port();



/*
User-defined functions are made available by adding an entry to each
of the following three tables.



user_func_name: add a string corresponding to the function name
user_func_type: add a bitmask corresponding to the types of the
values that can be returned by the function
user_func_rout: add the name of the routine to be called using
prototype:



routine(argc,argv)
int argc; // argument count
unsigned long argv[]; // the arguments
*/



/* user function names */
char *user_func_name[] = {
"cast",
"search_int",
"search_string",
"listen",
"" /* end of table marked by
* null string */
};



/* user function types */
int user_func_type[] = {
T_INT | T_STRING | T_POINTER,
T_INT,
T_INT,
T_INT
};



/* user function routines */
unsigned long (*user_func_rout[]) () = {
cast_proc,
search_int,
search_string,
listen_on_port
};



/* allow cast operation */
static unsigned long cast_proc(argc, argv)
int argc;
unsigned long argv[];



{
return (argv[0]);
}



/* search table of integers for key, return index */
static unsigned long search_int(argc, argv)
int argc;
unsigned long argv[];



{
register int i;
unsigned long len;
unsigned long key;
unsigned long *array;



if (argc != 3)
return (~0); /* not enough arguments */



array = (unsigned long *) argv[0];
len = argv[1];
key = argv[2];



for (i = 0; i < len; i++) {
if (*array == key)
return (i);
array++;
}
return (~0);
}



/* search table of strings for key, return index */
static unsigned long search_string(argc, argv)
int argc;
unsigned long argv[];



{
register int i;
unsigned long len;
char *key;
char **array;



if (argc != 3)
return (~0); /* not enough arguments */



array = (char **) argv[0];
len = argv[1];
key = (char *) argv[2];



for (i = 0; i < len; i++) {
if (strcmp(*array, key) == 0)
return (i);
array++;
}
return (~0);
}



#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>



#define UNUSED 0
#define LISTEN 1
#define ACCEPT 2



static fd_state[32];



static void read_proc(fd)
{
int len;
char buffer[512];
struct sockaddr_in *from;
int fromlen, new_fd;



if (fd_state[fd] == LISTEN) { /* accept the new connection */
fromlen = sizeof(from);
new_fd = accept(fd, &from, &fromlen);
if (new_fd >= 0) {
add_user_fd(new_fd, read_proc);
fd_state[new_fd] = ACCEPT;



}
return;
}
len = read(fd, buffer, sizeof(buffer));
if (len <= 0) {
delete_user_fd(fd);
fd_state[fd] = UNUSED;
close(fd);
return;
}
write(1, buffer, len);
}



static unsigned long listen_on_port(argc, argv)
int argc;
unsigned long argv[];



{
struct sockaddr_in sin; /* socket address */
int fd, ret_code;
unsigned short port;



if (argc != 1)
return (~0);



port = argv[0];
port = htons(port);



/* now set up the port information */
bzero(&sin, sizeof(sin));
sin.sin_family = AF_INET;
sin.sin_port = port;
fd = socket(AF_INET, SOCK_STREAM, 0);
if (fd < 0) {
perror("listen_on_port: socket");
return (~0);
}
ret_code = bind(fd, &sin, sizeof(sin));
if (ret_code != 0) {
perror("listen_on_port: bind");
return (~0);
}
listen(fd, 5); /* listen for connections */
add_user_fd(fd, read_proc);
fd_state[fd] = LISTEN;
return (fd);
}


As noted, there are several intrinsic functions implemented in the example above. They are all defined in the same fashion, so the explanation below focuses on the cast intrinsic function, with no loss of generality.

The name cast was chosen for the name of the intrinsic function. This was added to the user_func_name table. The end of the table is marked by a null string.

This function is intended to return any possible type, so its type is specified as the logical OR of the types T_INT, T_STRING and T_POINTER. This expression is entered in the corresponding point in the user_func_type table.

Finally, the intrinsic function is implemented by the C routine cast_proc. This name is declared as a function at the top of the file, and the procedure name is added in the corresponding position in the user_func_rout table.

Any user-defined intrinsic functions are called similar to a C program. They are provided with two parameters. The first is the count of the number of arguments they are passed. The second is an array, each element of which is the value of the corresponding argument. The value the C routine returns will be the result of the intrinsic function as seen by the G program that is executing.

XGMON Core API

A sophisticated user-defined intrinsic function may desire to interact with another process. This is normally done using a socket or named pipe that is connected to another process. A file descriptor is created (possibly using kernel routines like open, socket or accept) and I/O is performed using it.

The major issue with doing I/O to another process is to avoid blocking while waiting for data to arrive--the xgmon core needs to be able to respond to I/O events such as the arrival of SNMP traps from the network, X11 events, as well as oversee the execution of virtual G machines.

There is an application program interface (API) routine, add_user_fd, which is used to inform the xgmon core that this file descriptor should be watched. It takes two arguments, the first of which is the file descriptor which references the open socket or pipe. The second parameter is a pointer to a void C routine. If data becomes available, the xgmon core will call the indicated routine, passing it the file descriptor in question.

When the file descriptor is closed, the xgmon core should be informed that it is no longer of interest (otherwise problems will result). This is done by calling the delete_user_fd routine and passing it the file descriptor in question.

The use of these two routines is demonstrated in the example above.

Building a new XGMON core

cc -o xgmon+ xgmon.o user_func.o new_code.o

cc -o xgmon+ user_func.o de_stubs.o new_code.o xgmon.o

Part 3: Reference Manual

Contents:  

This part of the guide describes:

• Topology Language.
• G Language.
• System commands (internal xgmon commands).
• Library commands (as delivered with xgmon).

G Topology Description Language

The G topology description language is used by the user to describe the nodes, hosts and links that xgmon should display in the topology window. The system command compile will take the topology description file as input and compile it into a graphical display in the topology window.

Defining a Network Topology

A topology description is introduced with the phrase define window and is terminated by the phrase end window Within such a block, there are up to three sub-blocks which describe different aspects of the network:

nodes	describes the layout and groupings of hosts and the protocols to be used.
interfaces	describes the IP address associated with each host.
links	describes the logical and physical links between network elements.

Each block is introduced with the relevant define statement and closed with the respective end statement.

The blocks must appear in the order shown above.

define window
   define nodes
      ...
   end nodes
   define interfaces
      ...
   end interfaces
   define links
      ...
   end links
end window

The nodes section

The nodes section is introduced with the statement define nodes and terminated with an end nodes statement.

This section is mandatory and describes the layout of the network elements being defined by the topology description. There are three statements relevant to this section:

• display
• use
• group

display

Use the display statement to specify where a node or host is to be displayed within its topology window.

display [node] nodename at x,y [("state")];
 
display hostname [(realname)] at x,y [("state")];
 
display icon(icon_name) hostname at x,y [("state")];

Usage notes:

1. the keyword node is optional and can be omitted.
2. if a host is specified by a name and realname is omitted, the name must be able to be mapped to an IP address that is found in /etc/hosts or known by the local name server. If it cannot, it is assumed that it is the name of a node.
3. if realname is specified, it must map to an IP address to be meaningful.
4. a box will be drawn large enough to include the name of the host or node.
5. a box representing a node will be a drawn a bit larger than a box representing a host.
6. if the icon clause is specified, then the files "iconname.icon" and "iconname.mask" must be present in the icons sub-directory of the current xgmon library directory. An exception to this is described in the usage note below. Both files must describe bitmaps created by the X11 bitmap utility that are of identical size. The icon file describes the foreground of the icon, the mask file describes the background that will be filled in.
7. if iconname begins with a "/", it is treated as an absolute pathname. In this case, the files are found by appending ".icon" and ".mask" suffixes to the indicated pathname.
8. A set of icons is included in the /usr/lpp/xgmon/lib+/icons directory. If you run the /usr/lpp/xgmon/shells/icondemo shell, you will be presented with a display of all the icons that are included in the xgmon distribution.

display "node-a" at 25,25;
display "host1" at 50,50;
display "192.34.222.72" at 75,75;
 
display "yktvmz"("yktvmz.watson.ibm.com") at 50,75;
display icon("my_icon") "host2" at 25,25 ("inactive");

use

Use the use statement to specify which network management protocol is supported by a specific host.

use protocol with host (password)

Usage notes:

1. the use statement cannot precede the display statement of the host it references.
2. as a matter of style, the use statement should immediately follow the display statement of the host for which it is specifying the network management protocol to be used.

display "192.34.222.72" at 75,75;
use snmp with "192.34.222.72" ("secret");

group

Use the group statement to group one or more hosts under a node. It is also possible to group one or more minor nodes under a major node. This permits the creation of a hierarchy of topology windows.

group {host1, ..., hostn} under node;

Usage notes:

1. the group statement must follow all the display statements of the host(s) and the node that are listed in the group statement.
2. multiple group statements can be used to group additional hosts or nodes under a node. Each group statement adds the specified set of display elements to the set that is already grouped under the node.
3. at a top-level window, only the node will be displayed. A click with the left mouse button will pop up the lower level topology window and display the group of hosts and/or nodes listed in the group statement.

display "node-a" at 25,25;
display "host1" at 25,50;
display "host2" at 75,50;
group {"host1","host2"} under "node-a";
display "node-b" at 25,25;
display "host3" at 25,50;
display "129.34.222.72" at 75,50;
group {"host3","129.34.222.72"} under "node-b";

The interfaces section

The interfaces section is introduced with the statement define interfaces and terminated with an end interfaces statement. This section is optional and if it does not appear, this is indicated by the statement no interfaces.

interfaces

Use the interfaces statement to specify the interfaces for each host.

host interfaces are {iface1, ... ,ifacen},
     alternate interfaces are {iface2, ... ,ifacen};

Usage notes:

1. often a host has only one host name but multiple interfaces (the host name then normally represents the primary interface to this host). You can use the host name as iface1, and list the other interfaces in dot notation.
2. some implementations of SNMP agents will only accept SNMP requests if the interface they were sent to is operational; otherwise they will discard the request. This may happen if a request is sent to iface1 while iface1 is down. Since there are multiple interfaces, the request may still arrive at the host via one of the other interfaces. The optional alternate interfaces definition allows G programs to switch to the next alternate interface address in case they find that the primary interface is failing. See also "next_alternate".

"host1" interfaces are {"host1","193.34.222.72"};
"host2" interfaces are {"host2","194.34.222.72","194.34.222.73"},
        alternate interfaces are {"194.34.222.72"};

The links section

link

Use the link statement to specify the link between two hosts.

logical link from iface1 to iface2;
physical link from display1 to display2;

Usage notes:

1. logical links are considered to be point-to-point links.
2. the keyword logical is optional and may be omitted.
3. physical links represent links between display elements. A common use is to represent physical T1 lines. Their status is not driven by the xgmon core, but can be manipulated by a G program..

logical link from "host1" to "host2";
physical link from "idnx1" to "idnx2";

The include directive

Use the include statement to include other topology definition files. This statement is interpreted by the lexical analyzer and thus can appear on any line in a topology description or G program. As an example, this can be used to include a complete sub-network that is maintained in another file.

include "filename"

Because of the sequence of the nodes, links and interfaces sections, one needs to split up such include files into three pieces and include each piece in the appropriate section.

G Language

What is the G Language?

G is a programming language that can be used to write extensions to the xgmon client. It is both a subset and a superset of the C programming language. It is a subset in the sense that it uses syntax similar to C, but it does not support the complete language. It is a superset in the sense that it supports operations (e.g., comparison, addition) on types such as strings.

The xgmon core contains a compiler that translates G language programs into G-code (object code) that is interpreted by virtual G machines. The xgmon application is capable of controlling the concurrent execution of multiple virtual G machines, each running its own program.

There are several commands available to the user at the xgmon command prompt (">"). Commands are broken up into two distinct classes, system and library. System commands, built into the client, generally control virtual G machines. Library commands are programs written in the G programming language that are compiled when referenced. The resulting object code is loaded into and executed by a virtual G machine,

The capabilities of the xgmon system can be extended easily by writing a new program in G and adding it to the directory of library commands.

Virtual G Machines

The xgmon core implements an abstraction of a virtual machine architecture. Most of the details of this abstraction are of little concern to programmers because programmer access to the virtual machine is through G programs. There are, however, a few underlying characteristics of the machine that are important to understand.

Window Control

Each virtual G machine has its own window to which you can:

• write text using the print statement.
• draw graphics using the draw_line intrinsic function.

Both are explained in a separate section.

This section explains escape sequences and control codes that you can use in strings and how they affect the formatting of a window.

Recognized Escape Sequences

The internal xgmon compiler recognizes the following escape sequences inside string constants:

Escape	Name	Decimal Value	Description
\0	NUL	0	Null character, string delimiter
\b	BS	8	Back Space
\t	HT	9	Horizontal Tab (tabs are set every 8 characters)
\n	LF	10	Line Feed, New Line
\f	FF	12	Form Feed, New Page
\r	CR	13	Carriage Return
\'	"	34	Double Quote
\\	\	92	Back-slash

Window Control Codes

The virtual G machine output windows recognize the following control codes:

Code	Action
7	the bell is rung
BS	the cursor retreats one position
HT	cursor is advanced to the next tab stop
LF	cursor is advanced to the next line, column 1
11	graphic mode clear
FF	window is cleared; cursor moved to line 1, column 1
CR	cursor is returned to column 1
27 l c	Positions the cursor to line l, column c

Note: column and row numbering start at 1. The example below demonstrates how to "home" the cursor.

    print "%c%c%c", 27, 1, 1;  // cursor to upper left corner

Note: in addition to clearing the screen, the form-feed (FF) character also has the effect of changing the mode of the screen to text. A virtual G machine window is automatically changed to graphics mode when the draw_line function is called.

Note: the graphic mode clear character clears the screen but there is no change of the screen's mode from graphic to text. If the window is not in graphics mode, then this has the same effect as the normal form-feed control.

Internal Database

The xgmon core makes no requests of SNMP agents on its own--only a program executed by a virtual G machine can make SNMP requests. When a request is made, the server may or may not respond. Whenever the client receives a response from an SNMP agent or an SNMP Query Engine, it stores the response in an internal data base. This makes the data available to all of the virtual G machines.

Variables stored in the internal data base are time-stamped. After a certain period of time they are considered invalid and discarded. As long as a variable in the data base is considered valid, a request for it is satisfied from the internal data base and no query is sent to the remote host. This reduces the traffic generated by the client. Each variable's text name, object ID, type and time-to-live value ² is described in a file (the default is /usr/lpp/xgmon/lib/mib_desc).

Data Types

There are three basic types supported by the underlying virtual G machine architecture:

• integers
• strings
• floating point

The virtual G machines also support arrays that leads to a special variable type:

• pointer

• as a result of an assignment:

  var[i] = expression;
  

• as the only component of an expression on the right hand side of an assignment statement:

  var = var[i];
  

• as a parameter of an intrinsic function call:

  pw = (string) password(argv[1]);
  

Note: no operations are permitted, because the pointer has no type defined.

Virtual G machines have a finite amount of memory available to them. As they work, they continue to use up some of this memory to store intermediate string expressions. The result is that, over time, a virtual G machine will use up all of its available memory. Any long-running G program will have to recognize this and be prepared to detect and respond to an impending lack of free memory ("words_free" explains how). Virtual G machines do no garbage collection by default.

Note: the xgmon core is able to perform garbage collection, but this must be explicitly enabled by a G program (see "reuse_mem").

Run-time Environment

The virtual G machines provide a simple, easily-understood run-time environment. Each machine has an address space comprised of several segments:

• a text segment that holds the object code
• a data segment that holds local variables, string constants, dynamically allocated blocks, and intermediate string expressions generated during the evaluation of a string expression.
• a stack segment that holds parameters during evaluation of expressions.

Variables

Each virtual G machine can have two kinds of variables:

• Local variables, generally read/write, that are local to the specific virtual G machine
• Global variables, that are shared by all virtual G machines on a read-only basis.

Global Variables

In addition to the local variables defined for each virtual G machine, there is a set of predefined global variables that are maintained by the xgmon core. These are used to communicate information that arrives from outside the client: the arrival of trap information or a button press are good examples.

Name	Type	Function
selected_host	string	name of the node last clicked on
selected_window	string	name of the window the pointer was in when the button was pressed
selected_x	int	relative x coordinate of pointer when button was pressed
selected_y	int	relative y coordinate of pointer when button was pressed
absolute_x	int	x coordinate of the pointer (on root window)
absolute_y	int	y coordinate of the pointer (on root window)
element_mask	int	current display element mask
traps_pending	int	number of traps left in queue
trap_enterprise	string	enterprise object ID of agent
trap_host	string	name of host trap arrived from
trap_type	string	type of trap that was received
trap_userdata	string	additional user-defined trap data
ping_hosts	pointer	list of hosts that respond to ping
snmp_hosts	pointer	list of hosts that respond to SNMP
snmp_passwords	pointer	community names associated with snmp_hosts
motif_fd	int	file descriptor of OSF/Motif front-end

Note: global variables must be treated as read-only. If a virtual machine attempts a store operation outside of memory allocated to it, it will be stopped.

Note: when the right mouse button is clicked while the pointer is within a virtual G machine window, selected_window is set to the name of that window (e.g., "G 0", "G 1", etc.). The variables selected_x and selected_y are set to the relative coordinates within the window. When the right mouse button is clicked within a topology display window, the situation is similar, except that the x and y coordinates are scaled so that they correspond to the 100 by 100 reference grid used when describing the topology.

Note: the variables ping_hosts, snmp_hosts and snmp_passwords are lists whose ends are marked by the null string.

Note: the trap_type variable indicates both the class of the trap, as well as its type. The class is indicated by the prefix "snmp:" (indicating an SNMP trap). The remainder of the string indicates the actual trap type. Thus, an SNMP link up trap appears as "snmp:3". The xgmon core also generates "traps" when it changes the coloring of a display element. These traps are indicated by a prefix of "xgmon:". Changes caused by the operator are also made available. These traps are indicated by a prefix of "operator:".

Note: the trap_userdata variable contains additional information about the trap. For enterprise-specific traps, this variable contains the remaining information to distinguish the trap, as well as a comma-separated list of object IDs denoting the elemen t in the trap packet. The two items are separated by a colon. If no variables were provided in the packet, only the specific trap type appears (no colon).

For a defined SNMP trap, it contains information that was provided in the original SNMP trap packet, such as the interface number in a link up or down trap, or the IP address (in "dot" notation) of the EGP peer in an EGP neighbor loss trap. This variable indicates the new state of the display element if the trap indicates an xgmon display element state change (e.g., "up", "down", "unknown").

Special Local Variables

There are several special local variables that may be defined in a G source program. If these variables are defined, the underlying run-time environment will update them appropriately.

Name	Type	Function
argc	int	number of arguments to program
argv	pointer	array of argument strings
send_response	int	indicates response to send command (0=no error)
gw_var_size	int	size of last requested gw_var element (bytes)
gw_var_name	string	name of last variable received in response to a send request

Note: the send_response variable is set to -1 if no response was received from the server or agent; otherwise it is set to the error code sent by remote host (see the relevant RFC's for these values). A value of 0 indicates no error occurred.

Note: the gw_var_name variable is used when making "get next" requests. The object ID of the MIB variable the agent provided as a response to the query is made available in this variable.

The G Programming Language

G is the programming language compiled by the xgmon core to G-code that is used by virtual G machines. Much of G looks like C, so C programmers should not have too much trouble picking it up.

The G language is intended to support writing applications that are used to monitor TCP/IP-based networks.

Structure of G programs

A G source program starts with the phrase start thread and ends with the phrase end thread. The three basic sections that make up a G program must appear in the order indicated below:

1. any variables used by the thread's procedure body
2. any functions used by the thread's procedure body
3. the thread procedure body

The following complete program (equivalent to the ping library command) illustrates a G program:

// ping hostname
start thread
int argc;
pointer argv;
 
int ret_code;
string host;
 
    if (argc != 2) {
         print "usage:  %s hostname\n",argv[0];
         exit;
    }
    host = argv[1];
    ret_code = (int) ping(host);
    if (ret_code != -1) {
         print "%s responded, time=%d ms\n", host, ret_code;
    } else {
         print "no response from %s\n",host;
    }
end thread

Comments

Comments in G are introduced with:

#	as in shell scripts,
//	as in C++,
--	as in another well-known language

A comment extends to the end of the line. Comments can be anywhere in the G source.

Supported Types

G supports three basic types:

int	for integers,
string	for strings,
pointer	for use in implementing arrays.

The basic unit of storage in a virtual G machine is one word (32 bits).

Variable Declarations

Variables must be declared before use. The suggested convention is to declare them at the top of the program. Global variables are defined by the system: user programs do not declare them. Local variables are declared by prefixing a list of variables with the desired type, as demonstrated below:

int i,j;
string s,str2;
pointer ptr,ptr2;

Simple Statements

There are several statements in the G language. As in C, the semicolon is used as a statement terminator, not a statement separator. Several statements may be grouped as one by enclosing them in braces:

{
   statement1;
   statement2;
}

Such a grouping is treated as one logical statement.

Assignment Statement

The most common statement is the assignment statement:

var_name = expression;

Sleep Statement

The sleep statement can be used to pause for a moment:

sleep int_expression;  // pause for specified seconds

Exit Statement

The exit statement terminates the current program and unloads the virtual G machine executing it.

exit;

Send Statement

The send statement is used to send requests to an SNMP agent. The hostname string may either be an IP address in dot notation or the name of the host.

send snmp req_type req_string [; req_string] ... to
        hostname(community_string);
send snmp set req_string,value [; req_string,value] ... to
        hostname(community_string);

Note: the req_string parameter must be an object ID in ASN.1 dot-notation indicating the requested variable (e.g., "1.3.6.1.2.1.1.1.0").

The local variables gw_var_name, gw_var_size and send_response are updated if defined. The gw_var_name and gw_var_size variables reflect information about the last variable received in the packet.

Asend Statement

The asend (asynchronous send) statement is also used to send requests to an SNMP agent and functions in a similar fashion to send. It differs in that a response is not waited for; therefore no status information is made available.

asend snmp req_type req_string [; req_string] ... to
        hostname(community_string);
asend snmp set req_string,value [; req_string,value] ... to
        hostname(community_string);

Print Statement

The print statement is used to display formatted output on the status window associated with the virtual machine. It can also be used to write output to a file that was previously opened with the fopen intrinsic function.

print format_string [,arg1 ]... [to file_descriptor];

Note: the format string can specified as permitted by the printf UNIX man page.

Return statement

return (expression)

Iteration and Conditional Statements

G also has looping and control statements.

If Statement

if (int_expression) statement
[else statement]

While Statement

Some looping may be performed using the while statement. It works like its C counterpart. If the conditional expression is non-zero, the statement is executed.

while (int_expression) statement

For Statement

It is possible to iterate over a list of expressions by using the for statement:

for var_name in {expr1 [, expr2]... } do statement

Note: the for statement has the feature of starting with the last element and proceeding towards the first.

Expressions

The simplest expression is a constant. Integer constants and string constants are easy to understand:

int i;
i = 2;
string s;
s = "hello";

More complicated expressions can be built using operators.

Parentheses may be used to group expressions to obtain the desired evaluation order.

Expressions are not limited to operations on constants. Variables may be referenced, and intrinsic functions may be called.

Pointer variables may be de-referenced using subscripting. A pointer variable points to an array of elements. Each element in the array may be an integer, string or another pointer. Subscripting is indicated with the use of brackets:

var_name[int_expression]

Note: floating-point data is stored as 64-bit quantities. Arrays of floating-point numbers can be represented by multiplying the array index by 2.

Operators

Note: when arithmetic is performed on floating point data, if the other operand is an integer, it is automatically promoted to a float. When floating point data is assigned to an integer variable, it is automatically truncated and converted to an integer.

There are also several logical operators. A logical operator always produces an integer result. The value 0 represents false, any non-zero value is treated as true.

Type	Operator	Result
int	||	logical OR of two operands
int	&1	logical AND of two operands
int	==	true if operands are equal
int	!=	true if operands are not equal
int	<	true if op1 less than op2
int	>	true if op1 greater than op2
int	<=	true if op1 less or equal to than op2
int	>=	true if op1 greater than or equal to op2
string	==	true if operands are equal
string	!=	true if operands are not equal
string	<	true if op1 less than op2
string	>	true if op1 greater than op2
string	<=	true if op1 less than or equal to op2
string	>=	true if op1 greater than or equal to op2

Function Definitions

function return_type func_name(arg_list)

function int factorial(int n)
{
    int j;
 
    if (n <= 2) return (n);
    else {
        j = (int) factorial(n-1);
        return (n * j);
    }
}

Calling Functions

There are several intrinsic functions built into the G language. Some functions are able to return values of different types. The most notable such function is gw_var. A G programmer can also write functions in G.

When an function is referenced, the return value must be cast. Thus, all references to intrinsic functions are proceeded by one of the following casts:

(int)
(string)
(pointer)
(float)

Thus, the call to obtain the time of day would look like:

int i;
i = (int) time(0);

Intrinsic Functions

This section lists and discusses each function built into the xgmon core.

Note: a C programmer may extend the xgmon core and add new intrinsic functions. Thus the list of intrinsic functions described here may not be exhaustive.

Each intrinsic is described using the following notation:

(type) func_name(type param1, type param2,...)

For example:

(int) fopen(string filename, string mode)

Database Operations

These intrinsic functions are used to extract information from the internal database and to set and retrieve environment variables associated with hosts.

gw_var

(int) gw_var(string hostname, string var_name)
(string) gw_var(string hostname, string var_name)
(pointer) gw_var(string hostname, string var_name)

The gw_var function extracts from the internal database the value of the specified (host, variable) pair. The host address is specified either by passing the host name or its IP address in dot-notation.

The desired variable is denoted by its MIB object ID.

gw_var can return variables of any type, so it is up to the programmer to know what format the data is stored in. The base_type function can be used ahead of time to determine what type should be expected.

If there is no valid information in the internal database, a value of -1 is returned for integers and the null string is returned for strings.

Note: there are currently no variables in the SNMP MIB whose representations are returned as pointers.

purge_cache

(int) purge_cache(string hostname)

A value of 0 is returned if the operation is unsuccessful (no data for the host existed).

getenv, setenv

(string) getenv(string host,string var_name)
(int) setenv(string host,string var_name,string value)

These routines are used to implement environment variables associated with hosts for situations that are not covered by the topology description file. The xgmon core recognizes the variable name RIGHTCLICK as being associated with the name of the library command that should be run when the host is double-clicked using the right mouse button.

Note: getenv returns the null string if there is no previously defined value for the indicated variable.

Note: if setenv is called with value being the null string, the variable is effectively deleted.

base_type

(int) base_type(string object_id)

real_type

(int) real_type(string object_id)

snmp_var

(string) snmp_var(string variable_name)

snmp_text

(string) snmp_text(string object_id)

add_filter, delete_filter

(int) add_filter(string object_id, string command,
    int if_changed)
(int) delete_filter(string object_id, string command,
    int if_changed)

The object_id parameter specifies the object ID prefix that must be matched before the library routine indicated by the command parameter can be called. The if_changed parameter is a flag that indicates whether the command should be called each time the filter condition is satisfied or only if the variable's state has changed. If if_changed is zero, the library command is invoked each time the xgmon core receives an update of the variable's state, even if the new information is identical to the old. If the value is non-zero, the library command is invoked only if the new data's value is different than the previously known value.

Host Information

These routines are useful for obtaining information about hosts.

password

(string) password(string hostname)

ipaddr

(int) ipaddr(string hostname)

get_primary

(int) get_primary(string hostname)

This routine returns the current primary address associated with the indicated host. The primary address can be changed by the next_alternate function. These two functions are used to implement adaptive, alternate addresses, permitting xgmon applications to adapt to the failure of an interface on a network element the system is monitoring. The designated host should be fully described by the active topology description. Most applications would want to use this routine instead of ipaddr.

next_alternate

(int) next_alternate(string hostname)

This routine changes the current primary address of the designated host to be the next available alternate address. Alternate addresses are selected in round-robin order.

Note: alternate address are specified in the topology description. The designated host must have alternate addresses specified in the active topology description; otherwise this command has no effect.

This routine returns 0 if the attempt fails, 1 if it was successful.

ping

(int) ping(string hostname)

set_max_rtt

(int) set_max_rtt(string hostname, int seconds [, int maxTimeout])

Note: xgmon normally should adapt and determine this value automatically; however, in some special situations (e.g., round-trip-times on the order of 10 seconds or above), this can be used to prevent xgmon from incorrectly believing the host is down. If the optional parameter maxTimeout is present, it specifies the maximum, total amount of time to wait for a response to be received.

String Manipulation

These functions permit strings to be manipulated in a variety of ways.

left, right, mid

(string) left (string source, int length)
(string) right (string source, int length)
(string) mid(string source, int start, int length)

substr

(int) substr(string source,string target)

strlen

(int) strlen(string str)

val, hexval

(int) val(string num_str)
(int) hex_val(string hex_str)

hex_val assumes the number is to be interpreted as a hexadecimal number. It accepts upper and lowercase representations of hex digits. If a character is specified in the string that is not a valid hex digit, it is ignored.

ascii

(int) ascii(string character)

dotaddr, hostname, dep_name

(string) dotaddr(int ip_addr)
(string) hostname(int ip_addr)
(string) dep_name(int ip_addr)

Note: hostname will try to return the name of the host associated with the IP address based on information made available by the auxiliary host data file. If no such mapping is available, the IP address is then mapped to a host defined by the topology description and the name of that host is returned. If this is impossible, the address in dot notation is returned.

Formatted Output

These functions provide the ability to create formatted text strings.

num

(string) num(int number)

sprintf

(string) sprintf(string format, type arg1, type arg2...)

File I/O

The following functions are used, in conjunction with the print statement, to perform file I/O.

fopen

(int) fopen(string filename, string mode)

"w" for create/truncate
"a" for append
"r" for read

The integer value returned is a file descriptor to be used in the to-clause of a print statement or passed as an argument to the read function. Files are automatically closed when a virtual machine is halted but can be closed by the close function.

If the open is not successful, fopen returns 0.

Note: although xgmon normally runs set-uid root, file opens are validated with the permissions associated with the user running the xgmon client instead of the unlimited permissions associated with root.

read

(string) read(int fd)

This function returns the next line in the open file indicated by fd. Upon end-of-file, this routine returns the null string.

Usage notes:

1. The read function always adds a trailing space to the actual data.
2. an fd argument of 0 results in the read being performed from the virtual G machine's window. The virtual G machine will enter the operator input state and the line entered by the operator will be returned.

close

(int) close (int fd)

Virtual G Machine Control

These functions provide information about the current virtual G machine environment and allow a virtual G machine to start programs in other virtual G machines or start up a UNIX program.

words_free

(int) words_free(0)

Note: if a virtual machine attempts to use more storage than allocated in its data segment, it is stopped.

alloc

(pointer) alloc(int words)

Note: passing an argument of zero is considered invalid. A message will be generated at runtime, but the virtual G machine will not be halted. The pointer returned should not be referenced.

Note: requesting more storage than is available will result in the virtual G machine being halted.

time, ctime

(int) time(0)
(string) ctime(int time_expr)

flush_trap

(int) flush_trap(int flag)

flush_trap is used to flush the current trap that is being processed. It returns the number of traps pending (that is also available in the global variable traps_pending). If 0 is passed, only the current trap is flush (the normal case). If a non-zero value is passed, all of the pending traps are flushed.

exec

(int) exec(string command_line)

unix_exec

(int) unix_exec(string command_line)

This function can be used to execute an arbitrary UNIX program from within a virtual G machine environment. The virtual G machine does not wait for the spawned process to terminate.

This function returns the event ID of the event that will be posted when the spawned process terminates. If an error occurs, -1 is returned.

reuse_mem

(int) reuse_mem(int enable_flag)

The reuse_mem function is used to control garbage collection by a virtual G machine. By default, garbage collection is not enabled. If reuse_mem is called with a non-zero argument, an attempt to enable garbage collection is made. This may not be successful because the operator has the ability to disable garbage collection by using the system command reuse.

This function returns 1 if garbage collection is enabled; otherwise 0.

create_event

(int) create_event(int ev_type, int ev_specific)

Note: event types greater than or equal to 1024 are reserved for use by application programmers; values less than 1024 are reserved for use by the xgmon core. This function returns the event ID of the new event. If an error occurs, -1 is returned.

delete_event

(int) delete_event(int event_ID)

Note: when a virtual G machine terminates, all events associated with the machine are automatically deleted.

post_event

(int) post_event(int ev_type, int ev_specific [, int ev_data])

If the ev_data is not specified, it defaults to 0.

is_posted

(int) is_posted(int event_ID)

event_can_wake

(int) event_can_wake(int event_ID)

event_data

(int) event_data(int event_ID)

event_specific

(int) event_specific(int event_ID)

Graphic Functions

The following functions permit virtual G machines to manipulate display elements on the topology display and to treat the window associated with a virtual G machine as an all-points-addressable display.

highlight_dep

(int) highlight_dep(string element_name)
(int) highlight_dep(string element_name, int timeout)
(int) highlight_dep(string element_name, int timeout, string state)

It is possible for the virtual G machine to force the display element to be colored according to a specific state. The recognized keywords for state are:

• up
• down
• unknown
• highlight
• acknowledge
• ignore
• inactive

Once the period of time has elapsed, the element will return to its normal color. This function returns 0 if the element was defined, otherwise it returns -1.

Note: if the timeout value is specified as 0, then the display element's state is forced to the state specified by the state parameter instead of being temporarily overridden.

Note: the name of a logical point-to-point link is assigned by the xgmon core. This is done by taking the two IP addresses that represent the ends of the link, expanding them into dot-notation, and concatenating them together with "<->" inserted in the middle. The IP address with the lesser numerical value is always the first element:

129.34.222.70<->129.34.222.72

Note: the xgmon core recognizes the MIB variable "1.3.6.1.4.1.2.2.1.5.1" as a string variable that contains three comma-separated arguments. These three arguments are:

• display element name
• desired state
• timeout value

host1,acknowledge,0

set_element_mask

(int) set_element_mask(int new_mask)

The element mask controls several types of objects. The mask starts at bit 0. The display element is drawn if the corresponding bit is set.

Bit	Object	Default
0	reserved	off
1	hosts	on
2	nodes	on
3	logical links	on
5	physical links	off
9	bell	on
10	two-tone alert	off
11	labels on icons	on

Note: set_element_mask always causes the visible topology windows to be redrawn, even if the mask has not been changed.

set_width

(int) set_width(string element_name, int width)

This routine returns -1 if unsuccessful (the display element doesn't exist or is not a link); otherwise 0 is returned.

raise_window

(int) raise_window(0)

This routine takes a dummy parameter. It attempts to raise the graphic window associated with the virtual machine the program is running in. If there is no window associated with the virtual machine, -1 is returned.

window_height, window_width

(int) window_height(0)
(int) window_width(0)

Both of these routines take dummy parameters. They return the height and width in pixels of the graphic window associated with the virtual machine the program is running in. If there is no window associated with the virtual machine, -1 is returned.

font_height, font_width

(int) font_height(0)
(int) font_width(0)

Both of these routines take dummy parameters. They return the height and width in pixels of the font being used in the graphic window associated with the virtual machine the program is running in. If there is no window associated with the virtual machine, -1 is returned.

draw_line

(int) draw_line(int x1,y1,x2,y2,width,color)

This routine draws a line from (x1,y2) to (x2,y2) on the display associated with the virtual G machine. The line is width pixels wide, and is drawn in the color/style indicated by color. On a monochrome display, this can be either 1 or 2, indicating a solid or dotted line respectively. On color displays, the color specification can be 1, 2, 3, 4 or 5 corresponding to the color for up, unknown, down, background and white, respectively.

Note: the draw_line function automatically places the virtual G machine window in graphics mode. Graphics mode is turned off (placing the window into text mode) when the window is cleared by outputting the form feed (FF) control character.

        print "\f";

dep_info

(string) dep_info(string element_name)

The dep_info function allows a G program to obtain information about a display element. If the name passed does not refer to a display element, the null string is returned.

This function returns a different style of string depending on the type of the display element referenced.

state;x,y|n:
state;x,y|h:addr1,addr2,addr3,...
state;x,y|l:from_addr,to_addr

This first example illustrates a node. The interesting information in this case is the coordinates of the display element and the type (a node is indicated by the "n").

The second example illustrates a host. This is similar to the node, but indicates a different type and includes a list of IP addresses associated with the host.

The third example illustrates a link. The x and y coordinates are meaningless in this case, but the format is identical to the previous examples to permit easier parsing. In this case, the type is different ("l") and the IP addresses of both ends of the point-to-point link are indicated.

The value of the state parameter is reported as one of the following strings:

• up
• down
• unknown
• highlight
• acknowledge
• ignore
• inactive

get_deps

(string) get_deps(string element_name)

get_deps makes available to G programs the hierarchy of display elements that make up the current active topology description. This function is passed the name of a node and returns a list of display elements that are grouped underneath it. The pseudo-root element is specified by the null string.

The null string is returned if the display element referenced does not exist or is not a node with display elements grouped under it.

get_dep_parent

(string) get_dep_parent(string element_name)

get_links

(string) get_links(int address)

If no such logical links exist, the null string is returned.

move_dep

(int) move_dep(string element_name, int x, int y)

A display element's relative location within a window can be changed by a virtual G machine with the move_dep intrinsic function. This function returns 0 if the requested operation was successful.

The x and y coordinates are relative to the 100 x 100 reference grid used by the topology description language. This function returns 0 if it was successful.

Note: Links cannot be moved: they are rooted to the nodes they connect.

rename_dep

(int) rename_dep(string element_name, string new_name)

A display element can be renamed using the rename_dep intrinsic function. The new name must map to the same IP address as the original. This function returns 0 if the requested operation was successful.

make_link, make_node, make_display_link

(int) make_node(string element_name [, string real_addr])
(int) make_link(string from_address, string to_address [, int type])
(int) make_display_link(string element_name, int count, pointer x_coords, pointer y_coords)

These intrinsic functions may be used by G programs to dynamically create new display elements. They return 0 if successful.

An element created by make_node or make_display_link must be mapped to the display by calling group_dep for it to appear.

Note: the element should be grouped before another one is create (e.g., via a call to make_node).

The IP address associated with a display element can be specified/overridden by including the real_addr argument in the make_node call.

Physical links can be created by specifying the value of 1 for type in a make_link call. If left off or zero, a logical link is created.

In the make_display_link function, count indicates how many coordinates are specified in the x_coord and y_coord arrays.

group_dep

(int) group_dep(string node, string element_name)

The group_dep intrinsic function is used to map a dynamically created node or host to the display. The normal sequence of events is for a display element to be created by make_node or the xgmon core in learn mode, then positioned using move_dep and finally mapped to the display using group_dep.

The pseudo-root node is indicated by passing the null string as the value of node. This function returns 0 if it was able to successfully group element_name under node.

new_deps

(pointer) new_deps(0)

The new_deps function returns a pointer to an array of strings representing the names of dynamically created display elements. The end of the list is marked by the null string.

The list represents all of the display elements created by the xgmon core since the last call to new_deps. Note that display elements created by the make_node and make_link intrinsic functions will also appear in this list if they were created after the first display element was created by the xgmon core.

delete_dep

(int) delete_dep(string element_name)

The delete_dep function can be used to delete an existing display element. This function returns 0 if the operation was successful.

Note: a node cannot be deleted if it has element grouped under it.

Note: if a host is deleted, all links to it are automatically deleted.

get_icon_name

(string) get_icon_name(string element_name)

This function returns the name of the icon associated with the indicated display element. If there is no icon associated with the display element, the null string is returned.

set_icon

(int) set_icon(string element_name, string icon_name)

This function returns 0 if successful; otherwise -1 if an error is detected.

set_background

(int) set_background(string node_name, string icon_name)

This function returns 0 if successful; otherwise -1 if an error is detected.

Note: if using a bitmap, the bitmap will be tiled across the visible area. In contrast, GIF images are scaled to fit the window.

System Commands

System commands are special commands which have been built into the xgmon core. In general, system commands are used to control the virtual G machines and/or the internals of the xgmon core.

help or ?

Use the help command to get a list of all the commands available. It first lists the system commands, which are internal commands built into the xgmon core. The help command then lists all the library commands, which can be considered to be a directory listing of the current xgmon library directory.

Library commands are actually G source programs. If you issue such a command, it will be compiled by the xgmon internal compiler, then loaded into a virtual G machine, and then executed under control of the xgmon core.

When xgmon is started, it reads the library directory. If commands are added to this directory afterwards, the xgmon core will automatically recheck the library directory for a new command when an attempt is made to reference a library command it does not recognize.

start

Use the start command to start a loaded virtual G machine (it gets loaded by compiling a G program). Also, a running G program may be stopped with the stop command. Execution can be resumed by the start command.

start vgm

where:

vgm	is the number of the virtual G machine to be started.

stop

Use the stop command to suspend execution of a G program in a specific virtual G machine. Execution can later be resumed with the start command.

stop vgm

where:

vgm	is the number of the virtual G machine to be stopped.

unload

Use the unload command to clear and unload a virtual G machine. The machine is then available for a new G program.

unload vgm

where:

vgm	is the number of the virtual G machine to be unloaded.

stat

The stat command displays the time that the xgmon client was started as the first line. Then it displays a header line, followed by one line for each loaded virtual G machine. Example of a stat reply:

start time: Thu Jun  1 14:20:10 1989
mach    instr  data    state        prog
0[0]    433    43      running      ping_all

The meaning of the columns under the headers are as follows:

mach	n[m] representing machine n, at priority m. 0 is the highest priority, 4 is the lowest.
instr	the number of instructions executed.
data	the size of the data segment in words (it will normally grow over time).
state	the state the machine is in. This can be one of: running the virtual G machine is able to execute instructions. sleeping the virtual G machine is sleeping (i.e., a sleep statement has been issued). loaded the program listed under heading prog is in one of these states: compiled and ready to be started. suspended by the stop command, ready to be started. stopping the virtual G machine is in the middle of an instruction, but has been requested to stop. When the instruction completes, it will be in the loaded state. halting the virtual G machine is in the middle of an instruction, but has been requested to halt and unload. When the instruction completes, all of the resources associated with the virtual G machine will be freed. I/O the virtual G machine is performing I/O with a network element. retrying the virtual G machine did not receive a response to a request and it is being retried. op input the virtual G machine is waiting for the operator to input a line of text into the virtual G machine's window.
prog	the name of the command being executed.

compile

Use the compile command to either:

1. compile a topology description file into a new topology display window.
2. compile a G program and load it into the first available virtual G machine.

compile file

where:

file	is the filename of the file to be compiled.

Usage notes:

1. The compile command looks for the first statement in the file (excluding comment statements). If it is a start thread statement, it assumes that the file is a G source file. If it is a define window statement, it assumes that the file is a topology description file.
2. If you issue a library command, it will be compiled, loaded into a virtual G machine and automatically started. You can specify parameters in this case. If you manually compile a G program using the compile system command, the program gets compiled and loaded into a virtual G machine. You can then start that machine, but you can not specify any parameters. In general, the reason you would compile is to have xgmon check for correct syntax after creating or changing a G source file.
3. The compiler tries to continue after it finds errors in a G source file. However, that may result in serious errors, and the result may even be that the xgmon client terminates. It is prudent to compile new G source files on a test xgmon client before using it on the production system.

quit

Use the quit command to terminate xgmon.

This command does not accept any parameters (they are ignored).

readdir

Use the readdir command to re-read the library command directory. This needs to be done if new library commands (G programs) are removed from the library directory after the the client has been started. If a new library command is added, the xgmon core will automatically search the library directory for the command when it is referenced.

This command does not accept any parameters (they are ignored).

hostdata

Use the hostdata command to specify the auxiliary host name/address mapping file.

hostdata file

where:

file	is the filename of the auxiliary host data file.

Usage notes:

1. The auxiliary host data file is in /etc/hosts format. This means that host names are entered in all lowercase characters.
2. Entries in the auxiliary host data file take precedence over those maintained by a name server or in /etc/hosts. If the required information cannot be found in the auxiliary host data file, then the xgmon core falls back to /etc/hosts or a name server.
3. Only one auxiliary file is permitted at a given instant in time.

clearcache

Use the clearcache command to clear the internal cache of host addresses. It should be used whenever the address of a host is changed.

This command does not accept any parameters.

Usage notes:

1. The xgmon core makes extensive use of an internal cache of host name/address mappings. Alterations to the host name/address database maintained by a name server or /etc/hosts can result in the information contained in the xgmon internal cache being incorrect. The clearcache command forces the xgmon core to abandon its current set of cached mappings and re-query the host's host name/address database for updated data.
2. The xgmon core also saves this cache from time-to-time in the file $HOME/.xgmon_cache. At a later invocation of the xgmon client, this cache is used again for the mappings (resulting in much better performance). Thus if a host's address has been changed, the clearcache command must be issued to purge the copy of the cache that is also stored in the file system. Simply restarting xgmon is not sufficient.
3. If you reference an unknown host in your topology description file, this fact is also recorded in the internal cache. If that host is later defined and gets added to the name server database or /etc/hosts file, a clearcache command must be issued to make the client aware of the existence of the new host.

query

Use the query command to query the internal database about a host.

query host

where:

host	is the name of the host you want to query. It may also be specified in "dot" notation.

The query command displays all the interfaces on the specified host. It starts with two header lines and then one line for each interface on the specified host. If more than one link is attached to a given interface, an extra line of output appears for each one of the links. Sample output of a query reply appears below:

known information about host1
    address          state   link name
 1: 129.34.128.254   ?       host1<->host2
 3: 129.34.223.254   ?
 2: 129.34.222.254   ?

The meaning of the columns are as follows:

interface	(no heading) the interface index associated with this IP address entry.
address	the IP address
state	the state of the associated interface as it is known by the xgmon client.
link name	the display element name of the link (line) that connects to this interface.

learn

Use the learn command to enable/disable the dynamic creation of display elements by the xgmon core when it learns of a new SNMP-based host.

learn on | off

If learn mode is enabled, whenever the xgmon core learns of a new SNMP-based host, it will create a display element for it. As it learns about the interfaces on the host, it will add this information to the internal host description.

The names of the dynamically created display elements may be obtained by using the new_deps intrinsic function.

Note: learn mode is off by default.

Note: dynamically created display elements are not mapped to the active topology display. This must be done by a G program that takes responsibility for placing the display element in an appropriate location and window.

reuse

Use the reuse command to enable/disable the generation of G-code that exercises the hybrid garbage collector. By default, the necessary code is generated, but this can be turned off to eliminate the overhead. A virtual G machine must explicitly enable garbage collection by calling reuse_mem. Such a request will fail if the generation of the required code has been disabled.

reuse on | off

delay

The delay command is used to specify the number of seconds the topology display should lag behind in real-time when negative state changes occur.

delay seconds

where:

seconds

is number of seconds display should lag behind real-time.

Note: the display can be reset to track in real-time by entering a delay time of 0. This is also the default.

query_engine

The query_engine command is used to enable/disable use of an SNMP Query Engine.

query_engine [hostname port]

where:

hostname	is the name or IP address of the host running the Query Engine.
port	is the TCP port assigned to the Query Engine.

Note: if invoked without arguments, any current connection to an SNMP Query Engine will be closed and all SNMP and PING requests will revert to their native implementations.

auto_limit

The auto_limit command is used to set the maximum number of simultaneous virtual G machines that can used to execute library commands that are triggered as a result of the xgmon core receiving new data from an SNMP agent.

auto_limit machines

where:

machines

is the maximum number of simultaneous programs that can be started by the xgmon core as a result of new data being received from an SNMP agent.

Note: the default limit is 2.

Note: library commands are invoked as a result of the data satisfying a filter condition previously set by a call of the add_filter intrinsic function.

on

The on command is used to force a library command to run in a specific virtual G machine instead of the first one available.

on command

> on 2 ping localhost
> on 3 compile prog.g

Library Commands

Library commands are actually G source programs. If you issue such a command, it will be compiled by xgmon, then loaded into a virtual G machine and executed under control of the xgmon core.

When xgmon is started, it reads the current xgmon library directory (see "Library Commands"). If commands are added to this directory after xgmon is started up, the directory will automatically be re-examined when the new library command is referenced.

The xgmon distribution includes a set of common G programs that seem to be useful for nearly everybody. This chapter describes these G programs (library commands).

However, xgmon users are strongly encouraged to extend the xgmon system by writing their own library commands in the G language. After testing, these commands can be added to the xgmon library for general use.

Library Command Invocation

Library commands are invoked in a fashion similar to UNIX commands. A library command invocation has the following format:

command [arg1 ... argn] [> filename]
command [arg1 ... argn] [>> filename]

Thus a library command may or may not take arguments. The output from a library command can also be redirected into a file, instead of having it sent to the normal place (under X11, this would be the window associated with the virtual G machine executing the program).

Note: there must be a space between the ">" (or ">>") and the file name when specifying redirection of the output.

Display Control and Manipulation

bell

Use the bell command to control the audible alarm. This is the alarm that normally sounds every five seconds if any of the links or hosts defined by the current topology description are down. The alarm may be either a two-tone beep or a double-beep (the default).

Note: this also controls beeps which might be generated by programs executed by virtual G machines.

bell on | off | two-tone | double

where:

on	turns the audible alarm on.
off	turns the audible alarm off.
two-tone	selects the two-tone alert bell.
double	selects the double-beep alert bell.

Usage Notes:  

1. If entered without arguments, this command will display its usage.
2. The use of the two-tone alarm can exercise an X11 bug observed on the PC/RT (both AIX 2.2.1 and ACIS 4.3BSD) which causes the server to sleep until receiving an external interrupt, such as a mouse event--a possibility that is unacceptable if the display is not actively being used by an operator.

display and dont_display

Use the display and dont_display commands to manipulate the display element mask. The display element mask controls which types of display elements can be drawn on the topology displays.

display elem_type [elem_type ...]
dont_display elem_type [elem_type ...]

where:

elem_type

the type of display elements you want to be displayed or not displayed. The elem_type can be one of: physical lines representing physical links (often T1 lines). t1s same as physical, usage is deprecated. logical lines representing logical point-to-point links. links same as logical, usage is deprecated. hosts boxes/icons representing host systems. nodes boxes/icons representing nodes (groups of nodes and/or hosts). labels icon labels

Usage Notes:  

1. If entered without arguments, this command will display its usage.
2. If an invalid display element type is entered, a message will be displayed and it will be ignored.

acknowledge, ignore, inactive, unknown

These commands are intended for use by the OSF/Motif front-end to xgmon.

acknowledge display element name
ignore display element name
inactive display element name
unknown display element name

where:

display element name

is the name of the display element (may be multiple words).

Usage Notes:  

1. If entered without arguments, these commands will display their usage.
2. If the indicated display element is not defined by the current topology description, an error message will be displayed.
3. If the indicated display element refers to a node (instead of a link or host), an error message will be displayed and no action will be taken.

move

Use the move command to change the relative position of a display element within a topology display window.

move [display_element x y]

where:

display_element	is the name of the display element (may be multiple words).
x	is desired new x coordinate (relative to a 100 x 100 grid).
y	is desired new y coordinate (relative to a 100 x 100 grid).

Usage Notes:  

1. If entered without arguments, this command will prompt the user to select the display element by using the mouse. Once selected, the user will be prompted to indicate the new location by pointing and clicking with the mouse.

save_win

The save_win command can be used to save the current topology information stored in the xgmon core as a G topology description.

save_win filename [root_node]

where:

filename	is the name of the file into which the topology description should be written.
root_node	the node from which the dump should start. If this is not specified, the dump starts from the pseudo-root node which results in a dump of the entire topology database.

Usage Notes:  

1. If entered without arguments, this command will display its usage.

clear, raise

These commands clear or raise the first available virtual G machine window. They are useful for clearing or raising a window just prior to running another library command.

clear
raise

Usage Notes:  

1. These commands take no arguments and if any are present, they are silently ignored.

Formatted Table Dumps

dump_ipaddr

Use the dump_ipaddr command to dump the IP address table of an SNMP agent and some other interesting information.

dump_ipaddr agent [community_name]

where:

agent	is the name or IP address of an SNMP agent
community_name	is the community name to be used to query the SNMP agent. If not specified, then the community name will be extracted from the current topology description.

The dump_ipaddr command produces a report that looks similar to:

ifIndex   ipAdEntAddr   ipAdEntNetMask  ifOperStatus
1:      129.140.67.1    255.255.0.0     down
4:      129.140.67.2    255.255.255.192 up
3:      129.140.67.4    255.255.255.192 down
2:      129.140.67.45   255.255.255.192 up

Usage Notes:  

1. If entered without arguments, this command will display its usage.
2. If no community name is specified and the agent is not defined by the topology description, then an error message will be displayed and the command terminates.

dump_routes

Use the dump_routes command to dump the IP routing table of an SNMP agent.

dump_routes agent [community_name]

where:

agent	is the name or IP address of an SNMP agent
community_name	is the community name to be used to query the SNMP agent. If not specified, then the community name will be extracted from the current topology description.

The dump_routes command produces a report that looks similar to:

Dest       ifIndex NextHop          Type     Proto      Age
0.0.0.0          2 129.34.222.254   remote   local      -1
127.0.0.1        1 127.0.0.1        direct   local      -1
129.34.148.10    2 129.34.222.43    remote   icmp       -1
129.34.222.0     2 129.34.222.72    direct   local      -1
end table

Usage Notes:  

1. If entered without arguments, this command will display its usage.
2. If no community name is specified and the agent is not defined by the topology description, then an error message will be displayed and the command terminates.

dump_icmp

Use the dump_icmp command to dump the table of ICMP counters associated with an SNMP agent.

dump_icmp agent [community_name]

where:

agent	is the name or IP address of an SNMP agent
community_name	is the community name to be used to query the SNMP agent. If not specified, then the community name will be extracted from the current topology description.

The dump_icmp command produces a report that looks similar to:

ICMP data from yktvmz
Number of ICMP messages         Received        Sent
Grand total:                    10000           1554
With errors:                    0               0
Destination unreachable:        574             39
Time Exceeded:                  0               0
Parameter Problem:              0               0
Source Quench:                  0               0
Redirect:                       7917            0
Echo Requests:                  1490            25
Echo Replies:                   19              1490
Timestamp Requests:             0               0
Timestamp Replies:              0               0
Address Mask Requests:          0               0
Address Mask Replies:           0               0

Usage Notes:  

1. If entered without arguments, this command will display its usage.
2. If no community name is specified and the agent is not defined by the topology description, then an error message will be displayed and the command terminates.

dump_ip

Use the dump_ip command to dump the table of IP-related counters and data associated with an SNMP agent.

dump_ip agent [community_name]

where:

agent	is the name or IP address of an SNMP agent
community_name	is the community name to be used to query the SNMP agent. If not specified, then the community name will be extracted from the current topology description.

The dump_ip command produces a report that looks similar to:

IP data from yktvmz
yktvmz is a gateway
Default time-to-live:                                   60
Total number of datagrams received:                     148168
Number discarded because of bad headers:                13
Number discarded because of wrong address:              0
Number of packets forwarded:                            6485
Number discarded because of unsupported protocol:       28
Number of good received packets discarded:              0
Number of good packets delivered:                       149875
Number of output packet requests:                       130102
Number of good output packets discarded:                0
Number output packets discarded because of no route:    0

Usage Notes:  

1. If entered without arguments, this command will display its usage.
2. If no community name is specified and the agent is not defined by the topology description, then an error message will be displayed and the command terminates.

dump_if

Use the dump_if command to dump information associated with the interfaces of a host or router.

dump_if agent [community_name]

where:

agent	is the name or IP address of an SNMP agent
community_name	is the community name to be used to query the SNMP agent. If not specified, then the community name will be extracted from the current topology description.

The dump_if command produces a report that looks similar to:

The total number of interfaces for host yktvmz is nine:
 
Interface 1
        ifIndex = 1
        ifDescr = IBM LCS
        ifType = ethernet-csmacd
        ifMtu = 1500
        ifSpeed = 10000000
        ifPhysAddress = 0:dd:1:2:35:86
        ifAdminStatus = up
        ifOperStatus = up
        ifLastChange = 0
        ifInOctets = 32593650
        ifInUcastPkts = 127476
        ifInNUcastPkts = 7129
        ifInDiscards = 0
        ifInErrors = 0
        ifInUnknownProtos = 2
        ifOutOctets = 28996319
        ifOutUcastPkts = 67494
        ifOutNUcastPkts = 540
        ifOutDiscards = 0
        ifOutErrors = 99
        ifOutQlen = 0
Interface 2
        ifIndex = 2
        ifDescr = IBM LCS
        ifType = ethernet-csmacd
        ifMtu = 1500
        ifSpeed = 10000000
        ifPhysAddress = 0:dd:1:2:9e:2c
        ifAdminStatus = up
        ifOperStatus = up
        ifLastChange = 0
        ifInOctets = 15325634
        ifInUcastPkts = 16853
        ifInNUcastPkts = 7147
        ifInDiscards = 0
        ifInErrors = 0
        ifInUnknownProtos = 0
        ifOutOctets = 34515692
        ifOutUcastPkts = 65996
        ifOutNUcastPkts = 288
        ifOutDiscards = 0
        ifOutErrors = 45
        ifOutQlen = 0

Usage Notes:  

1. If entered without arguments, this command will display its usage.
2. If no community name is specified and the agent is not defined by the topology description, then an error message will be displayed and the command terminates.

dump_at

Use the dump_at command to dump the IP address translation tables (the ARP cache) associated with the interfaces of a host or router.

dump_at agent [community_name]

where:

agent	is the name or IP address of an SNMP agent
community_name	is the community name to be used to query the SNMP agent. If not specified, then the community name will be extracted from the current topology description.

The dump_at command produces a report that looks similar to:

Interface 1
        129.34.128.240 = 0:dd:1:2:9e:2b
        129.34.128.244 = 0:dd:0:c3:fb:0
        129.34.128.245 = 0:dd:1:2:35:86
        129.34.128.247 = 0:dd:1:2:35:82
        129.34.128.248 = 0:dd:1:2:36:9
        129.34.128.252 = 0:dd:1:2:35:66
        129.34.128.254 = 0:dd:1:6:bd:55
Interface 2
        129.34.128.227 = 0:dd:1:2:9e:2c
        129.34.128.247 = 0:dd:1:2:35:82
        129.34.128.248 = 0:dd:1:2:36:9
        129.34.128.254 = 0:dd:1:6:bd:55
Interface 3
Interface 4
Interface 5
Interface 6
Interface 7
Interface 8
Interface 9
end table

Usage Notes:  

1. If entered without arguments, this command will display its usage.
2. If no community name is specified and the agent is not defined by the topology description, then an error message will be displayed and the command terminates.

Environment Variables and Internal Data

setenv and getenv

Use the setenv and getenv commands to set and display user-defined environment variables associated with hosts.

setenv host_disp_elem var value
getenv host_disp_elem var

where:

host_disp_elem	is the name of the display element which denotes a host for which you want to get or set an environment variable.
var	is the name of the variable you want to set or get.
value	is the value you want to set (may be multiple words).

Usage Notes:  

1. If entered without arguments, these commands will display their usage.
2. A special variable name, RIGHTCLICK, is recognized by the xgmon core. The value of this variable is assumed to be the name of a library command (a G program) that will be executed if the mouse pointer is positioned over the display element and the right button is double-clicked.

load_env

Use the load_env command to load a predefined environment that is described in a text file.

load_env filename

where:

filename

is the name of a file containing environment variable data.

This command expects the file to be in the format demonstrated below:

# This is a comment.  Comments must begin in column 1 with a "#".
host1 var1 value1
host1 var2 value2
host2 var1 value1
host3 var1 value1

Usage Notes:  

1. If entered without arguments, this command will display its usage.

clear_traps

Use the clear_traps command to delete all pending traps from the internal queue maintained by the xgmon core.

clear_traps

Usage Notes:  

1. This command takes no arguments and if any are present, they are silently ignored.
2. This command is normally of little interest, as the trap library command is always supposed to be running and it takes care of processing the queued traps.

purge

Use the purge command to force the xgmon core to invalidate all cached MIB data that it has for the indicated host. This will force the remote agent to be queried for new values instead of having requests satisfied from the cache.

purge hostname

where:

hostname

is the name or IP address of the SNMP agent whose cached data is to be invalidated.

Usage Notes:  

1. If entered without arguments, this command will display its usage.
2. This command generates no output: specifying an unknown host is no different than specifying a host for which there is no cached data.

next_alt, reset_addr

These commands are used to alter the xgmon core's notion of the current primary address of the indicated host.

The next_alt command changes the current primary address of the host to the next alternate address. The new primary address is displayed. The reset_addr command resets the current primary address to the default primary address. The default primary address is displayed.

next_alt hostname
reset_addr hostname

where:

hostname

is the name or IP address of the SNMP agent whose current primary address is to be modified.

Usage Notes:  

1. If entered without arguments, these commands will display their usage.
2. The snmp_p_all program automatically adjusts the current primary address in the presence of failures, so manual intervention is normally not needed.
3. If an unknown host name is specified, a message is displayed and the program terminates.

Real-time Performance Monitoring

perfmon

Use the perfmon command to display graphically display counts of incoming and outgoing packets on a specific host. In other words, it is a graphical performance monitor.

perfmon agent [interval [community_name]].

where:

agent	is the name or IP address of the SNMP agent to be monitored.
interval	is the interval (in seconds) between updates.
community_name	is the community name to be used to query the SNMP agent.

Usage Notes:  

1. If entered without arguments, this command will display its usage.
2. If interval is omitted, a default value of 30 seconds is used.
3. If no community name is specified and the agent is not defined by the topology description, then an error message will be displayed and the command terminates.

traffic

Use the traffic command to conveniently set up the necessary environment variables and filters to drive the topology display logical link widths (using the delta_link filter) based on counters such as packets in or out.

traffic var_name

where:

var_name

is the textual name of a counter from the MIB interfaces group. The special word "off" is recognized as meaning delete the existing filter without adding a new one.

Some appropriate variables to use as drivers:

• ifInOctets
• ifInUcastPkts
• ifInNUcastPkts
• ifInDiscards
• ifInErrors
• ifInUnknownProtos
• ifOutOctets
• ifOutUcastPkts
• ifOutNUcastPkts
• ifOutDiscards
• ifOutErrors
• ifOutQLen

The traffic command is the preferred interface to delta_link, as it removes any existing filter prior to setting up a new filter.

Usage Notes:  

1. If entered without arguments, this command will display its usage.
2. This program runs the add_filter and del_filter commands and thus requires an additional free virtual G machine to properly execute.
3. If the variable passed as an argument is unrecognized, an error message will be displayed. Any existing filter will have been removed.
4. This program assumes snmp_p_all is running: as delivered, snmp_p_all will acquire the needed data to drive the delta_link filter without generating additional I/O.

collect_stats

collect_stats [interval] [config_file]

A collect_stats configuration file has the following format:

# comment lines begin with a "#" in column 1
hostName1 communityName1 fileName1
hostName2 communityName2 fileName2
hostName3 communityName3 fileName1

If a configuration file is not specified, all statistics are written to "standard out", which means that the output should be redirected into a file for post-processing:

> collect_stats 5 > log

yktvmv 920107 14:35:24 $Begin 60 5
129.34.128.247 920107 14:35:26 IBM_LCS 1 2927169117 6378290 2023725 0 0 10919 1988509389 7478438 17323 0 3404 0 1 1 0
129.34.138.54 920107 14:35:27 IBM_LCS 2 57710410 986 243695 0 0 8795 16562444 44152 836 0 79 0 1 1 0
129.34.158.26 920107 14:35:28 IBM_IP-over-PVM_link 3 663996 16180 0 0 0 0 41823063 30356 0 0 0 0 1 1 0
129.34.158.27 920107 14:35:30 IBM_IP-over-PVM_link 4 0 0 0 0 0 0 120714 1035 0 0 22 0 1 1 0
129.34.158.28 920107 14:35:31 IBM_IP-over-PVM_link 5 948 6 0 0 0 0 960 6 0 0 0 0 1 1 0

The host header record has six fields:

1. hostname
2. date in YYMMDD format
3. time in HH:MM:SS format
4. literal "$Begin"
5. polling interval specified on command line invocation (seconds)
6. number of interface records to follow (ifNumber)

Each interface record has 20 fields:

1. IP address of interface
2. date in YYMMDD format
3. time in HH:MM:SS format
4. ifDescr (string, spaces changed to underscores)
5. ifIndex
6. ifInOctets
7. ifInOctets
8. ifInUcastPkts
9. ifInNUcastPkts
10. ifInDiscards
11. ifInErrors
12. ifInUnknownProtos
13. ifOutOctets
14. ifOutUcastPkts
15. ifOutUNcastPkts
16. ifOutDiscards
17. ifOutErrors
18. ifOutQLen
19. ifAdminStatus
20. ifOperStatus
21. ifLastChange

Automation Support

add_filter, del_filter

Use the add_filter and del_filter commands to add or delete automation filters.

add_filter obj_id command [always_flag]

where:

obj_id	is the text name of an SNMP variable or a MIB object ID. This defines the MIB variable prefix that will trigger execution of the filter.
command	the name of the library command to execute.
always_flag	an argument that, if non-zero, indicates that the filter should be called every time new data is acquired, instead of only when the variable has changed state.

Usage Notes:  

1. If entered without arguments, these commands will display their usage.
2. If the always_flag is zero or not specified, the filter will be invoked only when the variable has changed state.
3. If obj_id is passed as a textual name, but it cannot be mapped to an actual object ID, an error message will be displayed and the program terminates. No filter will be set or deleted.
4. A wordy message on the success or failure of the operation will be displayed if an attempt to add or delete a filter is made.

display_var

The display_var command is a handy automation procedure which can be used for debugging. When invoked, it obtains the desired data from the internal cache and displays it in a pleasing fashion.

display_var host_address object_id

where:

host_address	is IP address of the host from which the data was obtained.
object_id	is the complete MIB object ID of the variable which was received.

Usage Notes:  

1. If entered without arguments, this command will display its usage.
2. This command is intended to be invoked as an automation procedure, not by an operator.
3. Try: "add_filter 1.3.6 display_var" and make some SNMP requests (e.g., using dump_ipaddr).

delta_link

The delta_link command is an interesting automation procedure which dynamically adjusts the widths of logical links on the topology display. The intention is for the width of each link to reflect some relative indication of how much traffic is going through it or how many errors are occurring in a given interval.

delta_link host_address object_id

where:

host_address	is IP address of the host from which the data was obtained.
object_id	is the complete MIB object ID of the variable which was received.

Usage Notes:  

1. If entered without arguments, this command will display its usage.
2. This command is intended to be invoked as an automation procedure, not by an operator.
3. One should use the traffic library command to do the removal/setup of the filters.
4. This command recognizes a scaling factor which is maintained in the environment variable "delta_link","scale" (e.g., "setenv delta_link scale 10" sets scale to 10). The width of the link is first calculated in units/second and then divided by the scaling factor.
5. By default, the width of the link is driven by information acquired from the host which has the greater IP address. This can be reversed by setting the environment variable "delta_link","towards" to "low") (e.g., "setenv delta_link towards low").
6. When traffic is used to set up the appropriate filter, the snmp_p_all program will acquire the needed data without generating additional I/O.
7. Try: "traffic ifInUcastPkts".

color_interface, note_addr_index

The color_interface and note_addr_index commands are filters which can be used to drive a topology display of the status of connections to a LAN. These programs can serve as good examples as to how to use automation filters to drive the topology display in new ways. Applications programs are encouraged to review the source to the commands after reading the detailed explanation below.

color_interface host_address object_id
note_addr_index host_address object_id

where:

host_address	is IP address of the host from which the data was obtained.
object_id	is the complete MIB object ID of the variable which was received.

The goal of these two programs is to color display elements that represent connections to a LAN (such as an FDDI ring in their case). They rely on an administrative convention to name the display element representing a LAN as "LAN networkAddress" (e.g., "LAN 129.34.128.0") and a physical link between the host and the corresponding display element representing the LAN. This will be illustrated below.

The filter note_addr_index is used to extract the IP address-to-interface information that is acquired as part of an snmp_p_all operation (conventional xgmon operation). This information is used to build an inverse mapping table from interface index to IP address. This table is stored in the environment and has the name "INDEX2IPADDR".

The key of the table is a string composed of the host's IP address as a dotted-decimal, a colon, and the interface index. The value stored in the environment is the IP address (as a dotted-decimal). As an example, suppose interface 2 on the YKTVMV host (129.34.128.247) is 129.34.138.54. Thus the key would be: 129.34.128.247:2 and the value stored would 129.34.138.54.

This same filter also makes an SNMP GET request to obtain the network mask for the IP address and stores this mask information in another table (IPADDR_MASK). The key is the interface's IP address as a dotted decimal, the value is the network mask as a dotted decimal.

This filter is normally set up using the add_filter command so that is only gets called when the mapping of the IP address->interface index changes:

add_filter ipAdEntIfIndex note_addr_index

add_filter ifOperStatus color_interface

    display "yktvmv" at 25,50;
    use snmp with "yktvmv" ("public");
    display "LAN 129.34.138.0" at 75,50;
·
    physical link from "yktvmv" to "LAN 129.34.138.0";

Finally, the name of the physical link is generated by converting the IP address of the host back into its hostname and appending "<->" and the LAN display element to it. Given the example above, this would be "yktvmv<->LAN 129.34.138.0".

The final step is to change the color of the link according to the value of the ifOperStatus variable (up/down/test).

Monitoring Programs

ping_all

Use the ping_all command to ping, on a regular interval, all IP-based hosts defined by the current topology description.

ping_all [interval]

where:

interval

is the interval (in minutes) between PING cycles.

Usage Notes:  

1. ping_all is a command you typically want to start automatically when xgmon is run (see "XGMON Start-up").
2. If interval is not specified, a value of 5 minutes is assumed.
3. If interval is specified as the literal "once", only one pass is made and the program terminates.
4. If all of the hosts defined by the topology description respond to SNMP, then this command is not needed as its function is then duplicated by snmp_p_all.

snmp_p_all

Use the snmp_p_all command to poll all SNMP-based agents for the status of their interfaces. The agents to be polled are defined by the current topology description.

snmp_p_all [interval [s]]

where:

interval	is the time (in minutes) between polls.
s	is the constant character "s", which indicates synchronous polling.

Usage Notes:  

1. The snmp_p_all command is a command you typically want to start automatically when xgmon is run (see "XGMON Start-up").
2. If interval is not specified, a default value of 5 minutes is used.
3. If interval is specified as the literal "once", only one pass is made and the program terminates.
4. By default, requests for operational status are made asynchronously--thus multiple SNMP requests may be outstanding. By specifying the "s" flag, the snmp_p_all program can be forced to run using synchronous requests.

trap

Use the trap command to accept and handle traps received by the xgmon core.

trap [-l trap_log] [-d [state_log]]

where:

trap_log	is the name of the file in which to log SNMP traps that are received.
state_log	is the name of the file in which to log xgmon display element state changes.

Usage Notes:  

1. if not specified, traps are recorded in the file trap.log (in the current directory).
2. The trap command is a command you want started when xgmon is run (see "XGMON Start-up").
3. display element state changes are not normally logged. This is turned on with the "-d" option.
4. if the state log filename is not specified, it defaults to xgmon.log (in the current directory).

Note: the xgmon core generates internal events that must be processed by the trap library command or equivalent. If no such program is run, the internal event queue will grow without bound.

fast_poll

The fast_poll command is an snmp_p_all replacement which can poll a network in 25% of the time required by snmp_p_all in the absolute best case. The fast_poll program can be run in parallel using two virtual G machines, thus reducing the execution time by half. Improved statistics collection techniques can reduce the number of packets generated by a significant amount, thus providing the opportunity for a further decrease. In networks that have hosts with large numbers of interfaces, this program will dramatically reduce the number of generated packets.

fast_poll [interval [odd | even]]

where:

interval	is the time (in minutes) between polls.
odd	implies this thread should poll the odd hosts in the topology description.
even	implies this thread should poll the even hosts in the topology description.

Usage Notes:  

1. The snmp_p_all command is a command you typically want to start automatically when xgmon is run (see "XGMON Start-up").
2. If interval is not specified, a default value of 5 minutes is used.
3. If interval is specified as the literal "once", only one pass is made and the program terminates.
4. If neither "odd" nor "even" is specified, all of the hosts defined by the topology description are polled. Using even and odd permits two virtual machines to poll the network in parallel. Normally, the following would be added to the relevant .xgmonrc:

   fast_poll 300 odd
   fast_poll 300 even
   

Note: at some point in the near future, snmp_p_all will be replaced by this program.

Interactive Utilities

ping

Use the ping command to ping one specific host. If the host responds, the round-trip time in milliseconds is displayed, otherwise a message is displayed announcing that there was no response.

ping host

where:

host	is the name or IP address of the host you want to ping.

Usage Notes:  

1. If entered without arguments, this command will display its usage.

snmp_get, snmp_g_next and snmp_dump

The snmp_get and snmp_g_next commands can be used to query an SNMP agent for information using SNMP get and get-next commands, respectively. The snmp_dump command is used to dump a table--it queries the agent for information as long as the returned MIB variable object IDs have the same prefix as the original variable specified on the command line.

snmp_get [-c community] agent variable
snmp_g_next [-c community] agent variable
snmp_dump [-c community] agent variable

where:

community	is the community name to be used to query the SNMP agent. If not specified, then the community name will be extracted from the current topology description.
agent	is the name or IP address of an SNMP agent to be queried.
variable	is the text name of an SNMP variable (as defined by the "mib_desc" file) or a MIB object ID.

Usage Notes:  

1. If entered without arguments, these commands will display their usage.
2. The variable may be specified either using its text name or actual object ID (e.g., "sysDescr.0" or "1.3.6.2.1.1.1.0").
3. an snmp_get of a variable that is indicated to be a table header in the mib_desc file will be treated as an invocation of snmp_dump (i.e., it does the "right" thing).
4. If no instance is specified on snmp_get, an instance of "0" will be used.
5. If no community name is specified and the agent is not defined by the topology description, then an error message will be displayed and the command terminates.
6. A variable like "1.3.6" is often passed as the value of the variable parameter to the snmp_dump command when a dump of the entire MIB tree is desired.

snmp_set

The snmp_set command can be used to request an SNMP agent to modify the value of a MIB variable.

snmp_set [-c community] agent variable value

where:

community	is the community name to be used to communicate with the SNMP agent. If not specified, then the community name will be extracted from the current topology description.
agent	is the name or IP address of an SNMP agent to be queried.
variable	is the text name of an SNMP variable (as defined by the "mib_desc" file) or a MIB object ID.
value	is the desired value for the variable.

Usage Notes:  

1. If entered without arguments, this command will display its usage.
2. The variable may be specified either using its text name or actual object ID (e.g., "sysDescr.0" or "1.3.6.2.1.1.1.0").
3. If no instance is specified, an instance of "0" will be used.
4. If no community name is specified and the agent is not defined by the topology description, then an error message will be displayed and the command terminates.

trace_path

Use the trace_path command to determine the route between two hosts. This command queries SNMP agents defined by the topology description for routing information and displays the path packets would take as they are forwarded from host to host.

trace_path host1 host2

where:

host1	is the name of the source host.
host2	is the name of the destination host.

Usage Notes:  

1. If entered without arguments, this command will display its usage.
2. All hosts in the path must be running SNMP agents and be defined by the current topology description, unless they accept the default community name "public".

snmp_p_list

Use the snmp_p_list command to acquire the status of one or more hosts that have an SNMP agent running. Each host must be defined by the current topology description.

snmp_p_list host [host ...]

where:

host	is the name or IP address of the host to be polled.

Usage Notes:  

1. If entered without arguments, this command will display its usage.
2. If a host is listed that is not specified in the current topology description, the command will terminate.
3. This command acquires information that is required for updating the topology display: it produces no report of interest.

egp_chk

Use the egp_chk command to check SNMP-based hosts described by the active topology description for inactive or unknown EGP peers.

egp_chk [inclusion_file]

where:

inclusion_file

is the name of the file containing host names or IP addresses (one per line) of EGP peers that should be known.

Usage Notes:  

1. egp_chk always lists any EGP peers it detects that are not up and operating.
2. if an inclusion list is specified, egp_chk also checks to make sure that it received a report about the EGP peer in the list. This can catch a configuration error in which the EGP peer is actually up and functioning, but has not been properly configured as a peer and is thus not being used as intended. If a host is in the inclusion list, but no data is obtained about its state, egp_chk prints an appropriate message.

Note: egp_chk was written by Dave Pokorney, Chris Tengi and Ross Veach as one of their exercises at the second xgmon class.

NSFNET-specific Utilities

chk_isis

The chk_isis command is used to drive an xgmon topology display of the NSFNET backbone. Instead of coloring links based on the status of the interfaces, they are colored based on IS-IS reachability. This is very specific to the NSFNET backbone and relies on knowledge of the naming conventions as well as the currently implemented addressing scheme to pull off the magic without requiring some form of auxiliary data file. For non-NSFNET audiences, this program serves no other purpose than to provide an example of xgmon's flexibility in handling some unconventional situations.

chk_isis [interval]

where:

interval

is the time (in minutes) between polls.

Usage Notes:  

1. If interval is not specified, a default value of 5 minutes is used.

dump_acsu

Use the dump_acsu command to dump the status of the Cylink Advanced Channel Service Units being monitored by the indicated SNMP agent.

dump_acsu agent [community_name]

where:

agent	is the name or IP address of an SNMP agent
community_name	is the community name to be used to query the SNMP agent. If not specified, then the community name will be extracted from the current topology description.

The dump_acsu command produces a report that looks similar to:

ACSU dump from wijnen
ACSU 4422:
        DTE status:  out-of-frame loss-of-signal yellow alarm clock loss
        NET status:  out-of-frame loss-of-signal yellow alarm blue signal
                     red alarm looped QRSS test
        why_looped:  OK
        admin status:  OK
ACSU 4424:
        DTE status:  OK
        NET status:  OK
        why_looped:  in-band
        admin status:  OK
ACSU 4425:
        DTE status:  OK
        NET status:  OK
        why_looped:  OK
        admin status:  OK
end table

Usage Notes:  

1. If entered without arguments, this command will display its usage.
2. If no community name is specified and the agent is not defined by the topology description, then an error message will be displayed and the command terminates.

acsu_poll

Use the acsu_poll command to poll all Cylink Advanced Channel Service Units that are defined by the specified file. This program colors the NSFNET topology display based on the network and DTE status of the ACSUs.

acsu_poll filename [interval]

where:

filename	is the name of the file defining the ACSU to be polled.
interval	is the time (in minutes) between polls.

The ACSUs to be polled are defined in a text file of the format demonstrated below:

# This is a comment line
# keyword=acsu uniqueID agent_responsible
acsu 4422 rcp-3-1
acsu 4424 rcp-3-1
acsu 4425 rcp-3-1

Usage Notes:  

1. If interval is not specified, a default value of 5 minutes is used.

Miscellaneous Samples

right_click

The right_click command is the default command that is run when the operator double-clicks on a display element with the right mouse button. This behavior can be altered by setting the associated RIGHTCLICK environment variable appropriately.

right_click element

where:

element

is the name of the display element which was double-clicked.

Usage Notes:  

1. This sample program only echoes its arguments.
2. When writing a replacement, be aware that even though a display element name may have spaces in it, it is still passed as a single parameter when the program is called by the xgmon core.

cat

Use the cat command to concatenate the contents of a set of text files and write the result to the standard output of the virtual G machine. This normally would be the window associated with the virtual G machine, but because the standard output of a virtual G machine may be redirected, it may end up being placed in a file.

cat filename [ filename ... ]

where:

filename

is the name of a file to be concatenated.

Usage Notes:  

1. If entered without arguments, this command will display its usage.
2. The virtual G machine's standard input can be indicated with a filename of "-".

do_rc

Use the do_rc command to synchronously execute a sequence of xgmon system or library commands that are specified in a file. The next command in the file will not be executed until the current command is complete.

do_rc filename

where:

filename

is the name of a file containing commands to be executed.

Usage Notes:  

1. If entered without arguments, this command will display its usage.

heartbeat, monitorMaster

The heartbeat and monitorMaster commands can be used to implement master-slave relationships among xgmon clients of an SNMP Query Engine.

The heartbeat program announces the presence of an xgmon master to the slaves. The monitorMaster program is used to detect the presence of the master xgmon and take over when the master fails.

monitorMaster poll_commands [initial_delay]
heartbeat

where:

poll_commands	is the name of a file containing commands to be executed under control of do_rc when this xgmon takes over as master.
initial_delay	the number of seconds to delay waiting for the master to be started. If the master does not start within this period of time, this xgmon will take over as master. The default delay is 45 seconds.

Usage Notes:  

1. Normal usage is for all copies of xgmon to run the monitorMaster program out of their .xgmonrc files. The first xgmon started should be the initial master.
2. When failure of the xgmon master is detected, this xgmon will take over as master and execute the commands in the poll_commands file. This file typically contains commands like:

   trap &
   fast_poll 300 even &
   fast_poll 300 odd  &

netview

Use the netview command to issue commands from xgmon to NetView or to send a message to the operator.

netview cmd command [args]
netview msgop message

Usage Notes:  

1. If entered without arguments, this command will display its usage.

LANtern(TM) Related Commands

This section contains commands that allow the display and modification of selected LANtern Network Monitor MIB variables via a graphical user interface.

The information in this section is based on the LANtern Network Monitor Technical Reference (No. 4200169-00). The user should refer to this reference for a complete description of the LANtern Network Monitor MIB variables.

lan_alarm_mod

The lan_alarm_mod command displays and modifies entries ⁴ in the Alarm Table (object: eAlarmTable).

lan_alarm_mod [-c community] agent

Usage notes:  

1. The program interacts with the user through a virtual window
2. User responses are checked for validity
3. The alarm state (object: eAlarmState) has values 1 (disabled), or 2 (enabled). In the enabled state, a trap-PDU is generated whenever the computed gauge value does not fall within specified threshold values.
4. The alarm sample time (object: eAlarmSampleTime) is the value sampling interval (in seconds). The maximum interval is 3600 seconds (1 hour).
5. The alarm minimum traffic (object: eAlarmMinTraffic) is the minimum value the denominator of the alarm equation must achieve during the sample interval before the alarm value is updated. This is used to prevent spurious alarms caused by very low traffic.
6. The values for the following objects are expressed in tenths of a percent. For example, 100% is specified as 1000, 1% as 10, and 0.1% as 1.
   • low threshold (object: eAlarmLowThreshold)
   • high threshold (object: eAlarmHighThreshold)
   • low delta (object: eAlarmLowDelta)
   • high delta (object: eAlarmHighDelta)
   • low water mark (object: eAlarmLowWaterMark)
   • high water mark (object: eAlarmHighWaterMark)

lan_cblchk_mod

The lan_cblchk_mod command displays and modifies the LANtern-specific cable check interval (object: eMediaCheckInterval).

lan_cblchk_mod [-c community] agent

Usage notes:  

1. The program interacts with the user through a virtual window
2. User responses are checked for validity
3. The cable check interval is specified in seconds. The default value 0 indicates the check is disabled.

lan_client_mod

The lan_client_mod command displays and modifies the LANtern-specific Client Table (object: adminClientTable). This table provides data pertaining to all authorized LANtern clients.

lan_client_mod [-c community] agent

Usage notes:  

1. The program interacts with the user through a virtual window
2. User responses are checked for validity
3. The Client Table contains an entry (object: adminClientEntry) for each client. Each client entry contains:
   • Client IP address (object: adminClientIPAddr) that identifies a station authorized to access the LANtern Network Monitor
   • Client IP mask (object: adminClientIPMask), a 32-bit mask that is bitwise 'anded' with the candidate client's IP address before attempting to match against the client IP address. The default mask is 0xFFFFFFFF.
   • Client communities (object: adminClientCommunities), a bit array indicating the permitted use of the community name. A client community may be given one or more of the following rights in addition to the public ⁵ right:

     monitor	conveys the right to public access plus read access to most objects in the LANtern MIB
     logger	conveys monitor access rights plus, electively, the right to receive asynchronous notification of significant events (faults, alarms, etc.)
     administrator	conveys logger access rights plus write access to certain MIB objects.

lan_config

The lan_config command displays the configuration of the device. This includes the Admin info, Client info, Notification info, Down Load info, Modem Control info, Gateway Control, Phone Control info, alarm Control info, Station Control info, Media Control info.

lan_config [-c community] agent

Usage notes:  

1. The output of this program requires a virtual window width of 130 characters. It is best to redirect the display to a file for printing.

lan_err_report

The lan_err_report command displays a history of error statistics for the device. The display shows the number of network events, good packets, and error packets. The error packets are then broken down in their types. CRC errors, Undersized, Oversized, Jabber, local collisions, collision fragments. Utilization percent is also shown.

lan_err_report [-c community] agent [-i Interval]

Usage notes:  

1. The output of this program requires a virtual window width of 130 characters. It is best to redirect the display to a file for printing.

lan_newstn_mod

The lan_newstn_mod command displays and modifies the LANtern-specific new station alarm (object: eStnNewStationAlarm).

lan_newstn_mod [-c community] agent

Usage notes:  

1. The program interacts with the user through a virtual window
2. User responses are checked for validity
3. The new-station alarm can only be 1 (disabled) or 2 (enabled). The default is 1 (disabled).

lan_notify_mod

The lan_notify_mod command displays and modifies the LANtern-specific Notification Table (object: adminNotificationTable) that is usded to correctly direct traps to stations.

lan_notify_mod [-c community] agent

Usage notes:  

1. The program interacts with the user through a virtual window
2. User responses are checked for validity
3. The Notification Table contains an entry (object: adminNotificationEntry) for each station. Each station entry contains:
   • Notification Ip address (object: adminNotificationIPAddr) that identifies a station wishing to receive trap messages
   • Notification status (object: adminNotificationStatus) that has two possible values, 1 (primary contact) or 2 (backup contact)
   • Trap mask (object: adminNotificationTrapMask), a bit array specifying which traps the station wishes to receive. The default is 0, with a range from 0 (none) to 4095 (all).
   • Confirmation mask (object: amdinNotificationConfirmMask), a bit array specifying which traps are expected to be confirmed by the receiving station. The default is 0, with a range of 0 (none) to 4095 (all).
   • Timeout (object: adminNotificationTimeout) that specifies the number of seconds between retries for confirmed delivery. The default value is 10 seconds.
   • Notification retries (object: adminNotificationRetries) that specifies the number of retries for confirmed delivery. The default value is 2.
   • Backup Ip address (object: adminNotificationBackupIPAddr) that specifies the address of a backup station for confirmed deliveries. The default value is 0.0.0.0 (none).
4. No timeout value, number of retries, or backup address may be specified if the confirmation mask is 0.

lan_phone_mod

The lan_phone_modify command displays and modifies the LANtern-specific Phone Table (object: adminPhoneTable) that provides data pertaining to each possible phone connection that can be made over the serial channel.

lan_phone_mod [-c community] agent

Usage notes:  

1. The program interacts with the user through a virtual window
2. User responses are checked for validity
3. The Phone Table contains an entry (object: adminPhoneEntry) for each phone connection. Each phone entry contains:
   • Phone IP address (object: adminPhoneIPAddr) that identifies the IP address of the machine or IP network
   • Phone IP mask (object: adminPhoneIPmask) that specifies the IP subnet mask to be used over this phone connection. The default, 0.0.0.0, indicates no subnetting.
   • Local IP address (object: adminPhoneLocalIPAddr) that specifies the serial port IP address used for this connection
   • Phone Number (object: adminPhoneNumber) that specifies the phone number the modem uses to dial the machine (with adminPhoneIPAddr)
   • Phone Number Protocol (object: adminPhoneConnectionProtocol) specifies the logon sequence ASCII string.

lan_pkt_report

The lan_pkt_report command displays a history of the traffic statistics for the device that shows the number of network events, good packets, error packets, and total bytes. The good packets and total bytes are broken down within their types (broadcast, multicast, unicast, byte64-127, byte128-255, byte256-511, byte512-1023 byte1023-1518). The utilization percent is also displayed.

lan_pkt_report [-c community] agent [-i Interval]

Usage notes:  

1. The output of this program requires a virtual window width of 130 characters. It is best to redirect the display to a file for printing.

lan_serial_mod

The lan_serial_mod command displays and modifies the LANtern-specific serial connection information.

lan_serial_mod [-c community] agent

Usage notes:  

1. The program interacts with the user through a virtual window
2. User responses are checked for validity
3. Serial connection information is comprised of the following objects:
   • Serial data link (object: adminSerialDataLink)⁷ is the type of data link encapsulation to be used on the serial line. At this time, only the SLIP ⁶ type, indicated by the value 1 exists. It is also the default.
   • Serial IP address (object: adminSerialIPAddr)⁷ identifies the serial connection address. The default is 192.68.202.129.
   • Serial subnet mask (object: adminSerialSubnetMask)⁷ is the subnet mask for the serial connection. The default value is 255.255.255.128. For no subnetting use the value 0.0.0.0.
   • Serial baud rate (object: adminSerialBaudRate) is the codification of the baud rate used for the serial connection. The default is 2400(3).
   • Serial timeout (object: adminSerialTimeout) is the time (in seconds) a serial connection is to be disconnected if timeout seconds elapses with no communication. The default is 60 seconds.
   • Serial connection (object: adminSerialConnection)⁷ is the type of connection used by the serial line (1=Modem, 2=direct).
   • Serial flow control (object: adminSerialFlowControl)⁷ is the type of flow control use on the serial line (1=none, 2= rst/cts). The default is 1 (none).

lan_stn_stats

The lan_stn_stats command displays the station table (object: eStnTable) that contains the history of packets-in, packets-out, bytes-in, bytes-out, errors-in, errors-out, and the times of first and last transmissions for each station.

lan_stn_start [-c community] agent

Usage notes:  

1. The output of this program requires a virtual window width of 130 characters. It is best to redirect the display to a file for printing.

lan_stnSD_stats

The lan_stnSD_stats command displays the Station Source Destination Table (object: eStnToStnTableSD) that contains the history of packets, bytes, errors and the times of first and last transmissions between each combination of stations.

lan_stnSD_stats [-c community] agent

Usage notes:  

1. The output of this program requires a virtual window width of 130 characters. It is best to redirect the display to a file for printing.

lan_warm_start

The lan_warm_start command issues a LANtern-specific warm start command.

lan_warm_start [-c community] agent

Usage notes:  

1. The warm start command erases the contents of RAM including all counters and statistics. Non-volatile RAM is not affected.

Part 4: Appendixes

Contents:  

This part of the guide describes:

• xgmon messages.
• xgmon reserved words.
• hints for G programmers.
• using xgmon with an SNMP Query Engine.
• getting started for the first time.
• using xgmon with NetView/SNMP for VM and MVS.

Appendix A. Messages

Explanation: The indicated X11 display could not be opened.

Problem Determination: Either the indicated display name is invalid (e.g., the null string) or permission has not been granted to use the display.

User Response: If the display name is not valid, either set the DISPLAY environment variable appropriately or use the "-display" command line option to explicitly indicate the display to be used. If the display is not permitted, use the xhost command on the remote machine to permit use of the display by the local machine.

warning: cannot bind port for SNMP requests

Explanation: A simple UDP socket cannot be opened. This is a severe problem and would probably indicate resource limits being exceeded on the machine.

User Response: Try again later?

warning: cannot bind port to receive UDP SNMP traps

Explanation: The UDP port 162 cannot be bound. This can be caused by:

• not running with root permissions
• another copy of xgmon is already active
• an SNMP Query Engine is active on the host

User Response: If using the SNMP Query Engine, this is expected. If not running with root permissions, install the xgmon binary correctly.

warning: cannot bind port to receive TCP SNMP traps

Explanation: The TCP port 162 cannot be bound. This can be caused by:

• not running with root permissions
• another copy of xgmon is already active

User Response: If using the SNMP Query Engine, this is expected. If not running with root permissions, install the xgmon binary correctly.

warning: cannot bind raw socket to receive ICMP packets (for ping)

Explanation: A raw, ICMP socket could not be created. This means that xgmon will be unable to issue ping requests natively.

User Response: This indicates that xgmon has not been installed set-uid root. If this is unintentional, install the binary correctly; otherwise, use the SNMP Query Engine to enable ping support.

cannot open MIB description file: filename

Explanation: The indicated MIB description file does not exist or cannot be opened for read. This is either the result of improper installation or setting the GLIB environment variable to point to an improperly configured development directory.

User Response: Check the GLIB environment variable for correctness (normally it is undefined). Install a mib_desc file if needed in the indicated directory.

unknown MIB type: textString

Explanation: The MIB description file is improperly defined. The indicated text string does not correspond to any known type.

User Response: Edit the mib_desc file and fix the offending line.

data segment overflow on machine number

Explanation: The indicated virtual G machine has run out of storage. The G program running in the machine has a bug as it has exhausted all available storage.

Programmer Response: Fix the program: use the garbage collection facilities.

OUT OF BLOCK TABLE ENTRIES, m=number program=programName

Explanation: A bug in the indicated program is creating storage fragments that are not being reclaimed by the garbage collector. The garbage collector has run out of storage that it uses to keep track of the fragments.

Programmer Response: Fix the program. Review "Exploiting Garbage Collection" for a discussion of required programming style for correctly behaved programs.

Appendix B. Reserved Words

The following keywords are reserved by xgmon and cannot be used as variable names in G programs.

alternate	are	asend	at
define	display	do	end
exit	for	from	function
get
group	icon	if	in
int	interfaces	link	links
logical	next	no	node
nodes	physical	pointer	print
send	set	sleep	snmp
start	string	thread	to
under	use	while	window
with

Appendix C. Hints for G Programmers

The G programming language is intended to be an easy-to-use language tailed for writing network management applications. One of the best ways to learn G programming techniques is to study the source to several library commands.

Suggested G Programming Style

The execution of most G programs results in communication with a remote SNMP agent. The possibility for failure always exists and a well-written G program must be prepared to deal with such a situation.

If a response is not received from an SNMP agent, the xgmon core will mark the corresponding display elements as down. Thus the default behavior is for the host to turn red. In practice, agent software may fail although the host or router is still functioning. This may be because of a bug in the agent software or because the router is very busy and subsequently drops the packet containing the request because the router prioritizes its primary function (routing packets) over network management requests.

Regardless of the reason for the failure to respond, it is desirable to differentiate between an agent problem (a soft failure) and an unreachable host (a hard failure). This is done by "pinging" the host in question (actually making an ICMP echo request). If the xgmon core obtains a response from the "ping" request, then the host will be marked as unknown. The following code fragment illustrates this:

        send snmp get obj_id to host(community);
        if (send_response == -1) {  // no response
                rc = (int) ping(host);
                if (rc == -1) print "No response from %s\n", host;
        }

Exploiting Garbage Collection

Normally, a virtual G machine creates and discards intermediate string expressions as it works. The storage space used by these strings is not reclaimed. This is quite acceptable for the normal G program; however, some programs are of such a nature that this is unacceptable. Such programs are either intended to be very long-lived (e.g., standard commands such as snmp_p_all) or perform an exceptional amount of string manipulations.

The xgmon core is able to perform a form of hybrid garbage collection and a G programmer can exploit this. Garbage collection must be explicitly turned on by a G program. This is done by calling the intrinsic function reuse_mem.

        rc = (int) reuse_mem(1);
        if (rc == 0) {
                print "can't enable garbage collection\n";
                exit;
        }

The G compiler will generate the necessary instructions to reclaim storage if garbage collection is enabled by the reuse system command.

Note: the compiler generates the required code by default. The code in question is generated when an assignment statement is executed:

string var;
 
        var = "string expression";

When garbage collection is enabled, the storage space that var references is freed prior to var taking on its new value.

Note: strings are passed by reference, not by value. The value stored in a string variable is a reference to the string data (e.g., a pointer). It is not the actual string data.

The G programmer who uses garbage collection must be careful when making string assignments because the underlying implementation passes references to strings, not the actual value. Thus the following would cause problems if garbage collection is enabled:

        var1 = "string expression";
        var2 = var1; // OK so far, refers to the above string
// now the problem--the space var2 still references will be
// freed:
        var1 = "a new expression"; // var2 is no longer valid.

It is, however, relatively trivial to create a copy of a string by concatenating the null string:

        var1 = "string expression";
        var2 = var1 + ""; // var2 references a separate copy.
        var1 = "a new expression"; // var2 is still valid.

Intermediate string expressions are not reclaimed by the xgmon core. The G programmer must explicitly store such expressions in string variables:

// instead of
        print "address=%s\n", (string) dotaddr(addr);
// do
        address_text = (string) dotaddr(addr);
        print "address=%s\n", address_text;

Appendix D. Using xgmon with the SNMP Query Engine

Overview of the SNMP Query Engine

The xgmon network management system is well-suited for use by a single individual. Realistically, there are many situations in which more than one individual may wish to have a copy of xgmon running; unfortunately this would normally impose a linear increase of network management traffic on the network.

The SNMP Query Engine provides proxy SNMP services for network management systems. Although not specific to xgmon, xgmon is one such network management system that can exploit the Query Engine functionality (indeed, xgmon's ability to handle unsolicited network management data permits it to take full advantage of the SNMP Query Engine).

The SNMP Query Engine performs caching in the same fashion as xgmon (it evens accepts the same mib_desc file). This means that even though there are multiple clients of the SNMP Query Engine, a corresponding linear increase in generated network management traffic is not generated.

The Query Engine can be requested to forward a copy of all received data to a client and xgmon makes this request by default. This means that a given client of the SNMP Query Engine may make requests of an SNMP-based network element and copies of the agent's response will be forwarded to instances of xgmon using the Query Engine. This has the following ramification:

Only one client of the SNMP Query Engine has to perform the logical equivalent of the snmp_p_all and ping_all library commands--the topology displays of the attached copies of xgmon will be driven automatically.

Note: this means that an xgmon topology display will be updated as a result of queries made by a foreign network management system (e.g., NetView) that is a client of the SNMP Query Engine.

The SNMP Query Engine intercepts SNMP set commands on the host whose IP address is 255.255.255.255 and interprets this as a request to install the specified variable/value pair in its cache. After the data is stored, the normal response processing takes place. This includes the generation of response copies to other clients of the Query Engine. It it thus possible for clients of the Query Engine to share information via the Query Engine by performing SNMP sets on the host 255.255.255.255. If the xgmon core is not connected to an SNMP Query Engine, it intercepts any requests to address 255.255.255.255 and returns an error indication. This means that it is possible to write library commands that are expected to run in a clustered environment that still operate when an instantiation of xgmon is partitioned.

The SNMP Query Engine and xgmon

Use of the SNMP Query Engine is enabled by the query_engine system command. This command takes two arguments: the host name or IP address of the host running the Query Engine and the associated TCP port used by it.

Note: the TCP port used is assigned by the local site administrator.

Since the SNMP Query Engine can perform all of the required network I/O to remote network elements, the copies of xgmon do not have to bind the SNMP trap port or open a RAW socket to handle ICMP packets. It is because of these two requirements that xgmon is installed as a set-uid "root" program. A system administrator may thus install an SNMP Query Engine and remove the set-uid flag from the xgmon binary to provide an additional level of security, if desired.

Special Usage Considerations

A copy of xgmon that is acting as essentially a passive slave will exhibit some slightly different behavior than it would if it was performing active polling.

One of the first issues involves the initial startup. If the active copy of xgmon is already running, it will have already acquired the IP address-to-interface index mappings that are needed to adjust link state information. The default cache value for this table is 15 minutes, so it would be sometime before the table is refreshed and thus loaded into the slave copies of xgmon. For this reason, it is recommended that snmp_p_all or its equivalent be run once upon the startup of each slave.

Another issue is the discrimination between unreachability and the failure of the agent software. This situation is noted by the xgmon core when it marks the state of the host that does not respond to SNMP requests but does respond to ICMP echo requests as unknown. In a multi-user configuration, this error information is not propagated to the other copies. This is done to prevent a single operator's mistake from affecting the other displays, as would be the case if an improper community name was used. If such discrimination information must be propagated, a simple addition to snmp_p_all that exploits the "deOverride" variable will suffice.

Appendix E. Getting Started

First experiment

The first thing to do is to start up the freshly installed copy of xgmon. This is normally installed as xgmon+ and this is what will be assumed below:

% /usr/lpp/xgmon/bin/xgmon+
XGMON V0.x compiled at ..... on ...
>

Now, enter the help command:

> help
System commands:
        compile filename -- compile a G program
    ...
Library commands:
bell            cat           purge          display
    ...
>

> ping localhost
machine 0 started.

One should see the output in virtual G machine window 0. If you have an SNMP agent running somewhere in the network, try dumping its IP address table. You have to know a valid community name--the example below assumes it is "public":

> dump_ipaddr hostname public
machine 0 started.

ifIndex   ipAdEntAddr   ipAdEntNetMask  Bcast ifOperStatus
1:      127.0.0.1       255.0.0.0       0     up
2:      129.34.222.72   255.255.255.0   1     up

Defining a network topology

The next chore is to define the network topology to be monitored. A sample description (delivered in machine readable form in directory /usr/lpp/xgmon/win/samplenet) appears in "Sample Topology Description Files". It consists of a master file topology which includes the other files. Assuming these topology files are indeed placed in directory /usr/lpp/xgmon/win/samplenet, then the topology can be compiled into a topology display:

> compile /usr/lpp/xgmon/win/samplenet/topology

The network can now be monitored. This should be done using the three standard library commands trap, snmp_p_all and ping_all.

> trap
machine 0 started.
> snmp_p_all
machine 1 started.
> ping_all
machine 2 started.

Creating an appropriate .xgmonrc file

A normal .xgmonrc file for the samplenet would appear something like:

# physical links are not displayed by default
display physical
# the hostdata command reads a file with similar layout as /etc/hosts
# it can be used to specify additional hosts that are not defined
# otherwise.
hostdata /usr/lpp/xgmon/win/samplenet/hosts
compile /usr/lpp/xgmon/win/samplenet/topology
trap
snmp_p_all
ping_all
# maybe the bell should be turned off so as to not
# disturb the neighbors...
# bell off

The above examples assumed that xgmon+ was being used, so the actual file name would be .xgmonrc+.

You may also consider to write a shell script to startup xgmon. A sample is provided as /usr/lpp/xgmon/shells/samplenet.

Sample Topology Description Files

The following figures show the samplenet topology description. It consists of a master file which includes 3 other files, each of which includes yet another file.

Figure 2. topology, sample topology - master file

// Sample IP network to demonstrate XGMON Topology Language - master file
define window
define nodes
display node "Sample IP Network - XGMON sample."
at 50,5 ("inactive");
include "/usr/lpp/xgmon/win/samplenet/nodes"
end nodes
define interfaces
include "/usr/lpp/xgmon/win/samplenet/ifaces"
end interfaces
define links
include "/usr/lpp/xgmon/win/samplenet/links"
end links
end window


Figure 3. nodes, sample topology - nodes section

// Sample IP network to demonstrate XGMON Topology Language - nodes section



// Following is a sample how you can depict an ethernet with a "display link"
// and a "display node" statement. The remaining "display link" statements
// connect the hosts to the ethernet
// The initial state "ignore" give the ethernet the violet color on the
// topology display and tels XGMON not to monitor that display element.



display node "ethernet 129.34.128.0" at 15,40 ("ignore");
display link "ethernet" from 10,40 to 75,40 to 75,70 to 10,70;



display link "aixmain<->bb" from 50,20 to 50,40;
display link "Production_MVS<->bb" from 65,20 to 65,40;
display link "VM1<->ethernet" from 35,50 to 35,40;
display link "VM2<->ethernet" from 50,50 to 50,40;
display link "VM3<->ethernet" from 85,50 to 75,50;
display link "External_Links<->ethernet" from 15,90 to 15,70;
display link "TokenRing_Network<->ethernet" from 45,90 to 45,70;



// now we display the hosts and use icons to represent them.
// As you can see, aix370 does not run an SNMP agent, so it will be
// monitored with PING only.
// The VM and MVS hosts do have an active SNMP agent, so we specify to use
// the snmp protocol for these hosts with a community name of "monitor".



display icon("aix370") "aixmain" ("aixproj") at 50,20;
display icon("mvsesa") "Production_MVS" ("mvs1") at 65,20;
use snmp with "Production_MVS" ("monitor");
display icon("vm") "VM1" ("vm1") at 35,50;
use snmp with "VM1" ("monitor");
display icon("vm") "VM2" ("vm2") at 50,50;
use snmp with "VM2" ("monitor");
display icon("vm") "VM3" ("vm3") at 85,50;
use snmp with "VM3" ("monitor");



// Now we define 2 nodes which will have other nodes and/or hosts
// underneath it (grouped under it, so they are lower in the hierarchy).



display node "External_Links" at 15,90;
display node "TokenRing_Network" at 45,90;



// Here we define the elements in the TokenRing_Network. At the end
// of the definitions we group all those elements under this node.
// We start of by showing another method to define an ethernet, by
// using just a "display node" statement. The hosts are connected
// via a "physical link" statement in the "links" file.
// By the way, "p1 ethernet..." and "p2 ethernet..." are used to show
// that this is only part of the ethernet.
// The initial state "inactive" colors the ethernet display element cyan
// and also tells XGMON not to monitor that display element.



display node "p1 ethernet-129.34.128.0" at 50,20 ("inactive");
display "router_1" at 10,40;
display "router_2" at 30,40;
display "router_3" at 50,40;
display "router_4" at 70,40;
display "router_5" at 90,40;



display icon("tr10x100") "ring-1" at 05,70;



// For each ring, we even have a third level in the hierarchy.
// Since we a separate administrator for each ring, we include another
// file, in which the appropriate administrator defines the hosts on
// the ring he/she is responsible for.
// In this sample, we have only done that for ring-1.



include "/usr/lpp/xgmon/win/samplenet/ring-1.nodes"
display icon("tr10x100") "ring-2" at 15,70 ("inactive");
display icon("tr10x100") "ring-3" at 25,70 ("inactive");
display icon("tr10x100") "ring-4" at 35,70 ("inactive");
display icon("tr10x100") "ring-5" at 45,70 ("inactive");
display icon("tr10x100") "ring-6" at 55,70 ("inactive");
display icon("tr10x100") "ring-7" at 65,70 ("inactive");
display icon("tr10x100") "ring-8" at 75,70 ("inactive");
display icon("tr10x100") "ring-9" at 85,70 ("inactive");
display icon("tr10x100") "ring-a" at 95,70 ("inactive");



group {
"p1 ethernet-129.34.128.0",
"router_1",
"router_2",
"router_3",
"router_4",
"router_5",
"ring-1",
"ring-2",
"ring-3",
"ring-4",
"ring-5",
"ring-6",
"ring-7",
"ring-8",
"ring-9",
"ring-a"
} under "TokenRing_Network";



// Here we define all the elements which are grouped under the node
// "Eternal_Links. In this case we use the "display node" method again for
// representing our ethernet on the topology display, but we will use
// a "display link" statement instead of a "physical link" statement
// to connect the hosts to the ethernet.



display node "p2 ethernet-129.34.128.0" at 50,20 ("ignore");
display "router_6" at 20,50;
display "router_7" at 30,70;
display "router_8" at 50,50;
display "router_9" at 70,70;
display "router_a" at 80,50;
display link "router_6<->p2_ether" from 20,50 to 50,20;
display link "router_7<->p2_ether" from 30,70 to 50,20;
display link "router_8<->p2_ether" from 50,50 to 50,20;
display link "router_9<->p2_ether" from 70,70 to 50,20;
display link "router_a<->p2_ether" from 80,50 to 50,20;
group {
"p2 ethernet-129.34.128.0",
"router_6",
"router_7",
"router_8",
"router_9",
"router_a",
"router_6<->p2_ether",
"router_7<->p2_ether",
"router_8<->p2_ether",
"router_9<->p2_ether",
"router_a<->p2_ether"
} under "External_Links";


Figure 4. ifaces, sample topology - interfaces section

// Sample IP network demonstrates XGMON Topology Language - interface section



// The mainframe systems
"VM1" interfaces are {"vm1"};
"VM2" interfaces are {"vm2"};
"VM3" interfaces are {"vm3"};
"aixmain" interfaces are {"aixproj"};
"Production_MVS" interfaces are {"mvs1"};



// the routers
"router_1" interfaces are {"yr1","yroute1","yroute2"};
"router_2" interfaces are {"yr2","yroute3","yroute4"};
"router_3" interfaces are {"yr3","yroute5","yroute6"};
"router_4" interfaces are {"yr4","yroute7","yroute8"};
"router_5" interfaces are {"yr5","yroute9","yroutea"};
"router_6" interfaces are {"yr6","129.34.58.2"};
"router_7" interfaces are {"yr7"};
"router_8" interfaces are {"yr8"};
"router_9" interfaces are {"yren","renp"};
"router_a" interfaces are {"yrbb"};



// include a separate file for the ring-1, maintained by separate administrator
include "/usr/lpp/xgmon/win/samplenet/ring-1.ifaces"


Figure 5. links, sample topology - links section

// Sample IP network to demonstrate XGMON Topology Language - links section
// The bottom of this file, shows that we include the link definitions
// for ring-1 from a separate file. They are maintained by a separate
// administrator.



physical link from "router_1" to "p1 ethernet-129.34.128.0";
physical link from "router_2" to "p1 ethernet-129.34.128.0";
physical link from "router_3" to "p1 ethernet-129.34.128.0";
physical link from "router_4" to "p1 ethernet-129.34.128.0";
physical link from "router_5" to "p1 ethernet-129.34.128.0";



// The following are commented out. We have used the "display link" method
// And "display link" goes in nodes section.



// physical link from "router_6" to "p2 ethernet-129.34.128.0";
// physical link from "router_7" to "p2 ethernet-129.34.128.0";
// physical link from "router_8" to "p2 ethernet-129.34.128.0";
// physical link from "router_9" to "p2 ethernet-129.34.128.0";
// physical link from "router_a" to "p2 ethernet-129.34.128.0";



physical link from "router_1" to "ring-1";
physical link from "router_1" to "ring-2";
physical link from "router_2" to "ring-3";
physical link from "router_2" to "ring-4";
physical link from "router_3" to "ring-5";
physical link from "router_3" to "ring-6";
physical link from "router_4" to "ring-7";
physical link from "router_4" to "ring-8";
physical link from "router_5" to "ring-9";
physical link from "router_5" to "ring-a";



include "/usr/lpp/xgmon/win/samplenet/ring-1.links"


Figure 6. ring-1.nodes, sample topology - ring-1 nodes section

// Sample IP network to demonstrate XGMON Topology Language - Ring-1 nodes



display icon("tr200x51") "ring-1 129.34.222.0" at 50,50 ("inactive");
display icon("ibmrt") "yroute2" at 60,20;
display icon("ibmrt") "wijnen" at 10,20;
display icon("ibmrt") "gcc2" at 45,20;
display icon("aixps2") "bw" at 35,20;
display icon("ibmrt") "hien" at 50,20;
display icon("rs6000_530") "whs" at 90,25;
use snmp with "whs" ("monitor");
display icon("rs6000_530") "lilie" at 90,70;
use snmp with "lilie" ("monitor");
display icon("rs6000_530") "mnementh" at 10,70;
use snmp with "mnementh" ("monitor");
display icon("ibmrt") "ykt43" at 30,80;
display icon("ibmrt") "prtserve" at 50,80;
display icon("ibmrt") "flail" at 60,80;
display icon("os2") "whs2" at 70,80;
group {
"ring-1 129.34.222.0",
"yroute2",
"wijnen",
"gcc2",
"bw",
"lilie",
"hien",
"whs",
"mnementh",
"ykt43",
"prtserve",
"flail",
"whs2"
} under "ring-1";


Figure 7. ring-1.ifaces, sample topology - ring-1 interfaces section

// Sample IP network to demonstrate XGMON Topology Language - Ring-1 interfaces



"yroute2" interfaces are {"yroute2"};
"wijnen" interfaces are {"wijnen"};
"gcc2" interfaces are {"gcc2"};
"bw" interfaces are {"bw"};
"lilie" interfaces are {"lilie"};
"hien" interfaces are {"hien"};
"whs" interfaces are {"whs"};
"mnementh" interfaces are {"mnementh"};
"ykt43" interfaces are {"ykt43"};
"prtserve" interfaces are {"prtserve"};
"flail" interfaces are {"flail"};
"whs2" interfaces are {"whs2"};


Figure 8. ring-1.links, sample topology - ring-1 links section

// Sample IP network to demonstrate XGMON Topology Language - Ring-1 links
// These are physical connections to the TokenRing.



physical link from "ring-1 129.34.222.0" to "yroute2";
physical link from "ring-1 129.34.222.0" to "wijnen";
physical link from "ring-1 129.34.222.0" to "gcc2";
physical link from "ring-1 129.34.222.0" to "bw";
physical link from "ring-1 129.34.222.0" to "lilie";
physical link from "ring-1 129.34.222.0" to "hien";
physical link from "ring-1 129.34.222.0" to "whs";
physical link from "ring-1 129.34.222.0" to "mnementh";
physical link from "ring-1 129.34.222.0" to "ykt43";
physical link from "ring-1 129.34.222.0" to "prtserve";
physical link from "ring-1 129.34.222.0" to "flail";
physical link from "ring-1 129.34.222.0" to "whs2";


Additional Sample Topology

A limited set of icons is provided with xgmon. For your convenience, there is a topology description that shows all the included icons with their names. It can be found in the /usr/lpp/xgmon/win/icondemo directory.

A shell script /usr/lpp/xgmon/shells/icondemo is provided to bring up that topology.

Appendix F. XGMON and NetView/SNMP

Note: this section is of interest only to sites that have already installed NetView.

As noted previously, multiple instances of xgmon can work together to comprise a multi-user cluster. The NetView/SNMP support provided with the TCP/IP Version 2 products for VM and MVS can also work xgmon: bidirectional communication between NetView and xgmon is supported.

The following installation scenarios have been envisioned:

1. You have mainly a TCP/IP-based network, and your experience is in UNIX.

   In this case, it makes most sense to select xgmon as the sole TCP/IP network manager.

2. You have mainly a SNA-based network and are now adding small numbers of TCP/IP-based networks. You already use NetView for SNA network management and want to incorporate TCP/IP network management in NetView.

   In this case you may want to use plain SNMP support for NetView as offered with TCP/IP version 2.

3. You have an existing SNA network that is managed with NetView. You also have an existing TCP/IP network that has been managed separately with local tools, and you want SNMP management now. The two networks are operated independently but sometimes it might be handy to share some of the tools.

   Here is a good opportunity for the shared use of NetView and xgmon and exploit the facilities that allow NetView and xgmon to communicate with each other.

4. You have an existing SNA network that is managed with NetView. You also have an large TCP/IP network that and desire to monitor this with the NetView. Unfortunately, all of the normal SNMP polling will take a large number of those expensive mainframe CPU cycles. You would like to off-load normal SNMP polling activity onto a workstation and have NetView process exceptional conditions.

   In such a situation, running xgmon on a workstation is a great choice and the bidirectional communication between xgmon and NetView can be exploited to transfer information about exceptional conditions that are detected by xgmon.

Bidirectional communication between XGMON and NetView

Bidirectional communication between xgmon and NetView can be exploited for several applications. Some possibilities are listed below:

• You may want your NetView operators to keep an eye on the TCP/IP network, but at the same time you may want then to have a graphical display of the TCP/IP network topology.
• You'd like your operators to be able to issue commands to NetView from xgmon.
• You may want to off-load the SNMP polling type of work to a UNIX-based workstation and only bother NetView when something serious happens to the TCP/IP network.
• You may even want to try and monitor/manage your SNA network with an xgmon front-end to NetView.

The following software is required:

• xgmon version 0.9 or up.
• SNMP Support for NetView at TCP/IP Version for VM or MVS level 1410 or up.
• As far as samples are concerned, the G programs come with the XGMONLIB PACKAGE and the NetView CLISTs and sample entries for the message automation table come with SNMP support for NetView in TCP/IP Version 2 for VM or MVS

  Note: in the case of VM, this is an update to the initial GA level of the code.

Figure 9. Overview of the XGMON manager on UNIX. Boxes below the double dashed line (===) are running (sub)processes in UNIX; those above that line are X11 windows. The xgmon core module:

• Performs SNMP requests from virtual G machines.
• As a result, data gets stored in database/cache.
• This data is available to all virtual G machines.
• Topology display is driven as a side effect of the data in the database.

  *--------------------------------*            *---------------------------------*
  |  *--------*        *--------*  |            |__Virtual Machine G0_____________|
  |  | NODE-1 *--------* NODE-2 |  |            | pinging uitvm2 ....             |
  |  *--*-----*        *----*---*  |            | pingin*-------------------------*--------*
  |     |                   |      |            | pingin|__Virtual Machine G1______________|
  |     |    *----------*   |      |            |       |                                  |
  |     *----*  NODE-3  *---*      |            |       |       *--------------------------*------*
  |          *----------*   ^      |            |       |       |__Virtual Machine G2_____________|
  *-------------------------+------*            |       |       |  packet statistics              |
  *----------------------*  |                   |       |       |          *--*                   |
  | > xgmon version 0.x  |  |   *-------------->|       |       |   *--*   |  |                   |
  | > help               |  |   |               |       |       |   |  |   |  |                   |
  | > System Commands    |  |   |               *-------*       |   |  |   |  |    *--*           |
  |     ....             |  |   *---------------------->|       |   |  |   |  |    |  |           |     *--------*
  |   Library Commands   |  |   |                       *-------*   |  |   |  |    |  |           |     |        |
  |     ....             |  |   |                               |   *--*   *--*    *--*           |     |  Gn    |
  | >              ^     |  |   *------------------------------>|   pin    pout   perror          |     |        |
  *----------------+-----*  |   |                               *---------------------------------*     *--------*
=======================================================================================================================
 *------------*  *-+--------+---+-*   *--------------* *--------------* *--------------* *--------------*
 |            |  | |        |   | |   | Virtual G0   | | Virtual G1   | | Virtual G2   | | Virtual Gn   |
 |            |  | |        |   | |   |              | |              | |  print ..    | |              |
 |            |  | |        |   | |   |              | |              | |  snmp_var .. | | send snmp .. |
 |            |  | |        |   | |   |  print ..    | |              | |  draw ..     | | snmp_var ..  |
 |            |  | |        |   | |   |   *          | |  *           | |   *          | |  *           |
 |            |  | |        |   | |   |   |     ^    | |  |      ^    | |   |      ^   | |  |      ^    |
 |            |  | |        |   | |   *---+-----+----*-*--+------+----*-*---+------+---*-*--+------+----*
 |            |  | |        |   | |   |   |     V         |      V          |      V        |      V    |
 |            |  | |        |   *-+---+---*---------------*-----------------*---------------*           *-------------*
 |            |  | |        |     |   |                                                                 |             |
 |            |  | |        *-----+---+-----------------------------------------------------------------+-- Cache     |
 |  Any       |  | *--------------+---+--->                                                             |   DataBase  |
 |  Process   |  |  X11 Server    |   | XGMON core                      ^                               *-------------*
 *------------*  *----------------*   *---------------------------------+-------------------------------*
 *---------------------------------------------------------------------- ---------------------------------------------*
 |                                                                      |                                             |
 |                                                                      V                                             |
 |   UNIX and TCP/IP Layers                                      SNMP PING TRAPS                                      |
 |                                                                      ^                                             |
 *----------------------------------------------------------------------+---------------------------------------------*
                                                                        V
                                                                  to SNMP Agents
      

Figure 10. Overview of shared use of SNMP Query Engine

*-----------* *----------------------------------------* | X11 | | XGMON SQESERV | | Display |<--->| ^ (SNMP Query Engine) | *-----------* | | ^ ^ | Main Operator *-----+---------------+-------+----------* | | | | UNIX with TCP/IP | qehost | *-----------------------------+----------* | *------------------------------------------------V---------------* | IP Network | *-----^------------------------^------------------------^--------* | | | *-----V--------* *-----V--------* *-----V--------* | XGMON | | XGMON | | XGMON | | | | | | | | UNIX + TCP/IP| | UNIX + TCP/IP| | UNIX + TCP/IP| *--------------* *--------------* *--------------* ^ ^ ^ | | | V V V *--------------* *--------------* *--------------* | X11 Display | | X11 Display | | X11 Display | *--------------* *--------------* *--------------* Operator 1 Operator 2 Operator n One host (qehost in this sample) runs SNMP Query Engine (sqeserv) and (optionally) a copy of xgmon connected to the Query Engine. Operators 1 and 2 (and any number of other operators) start up their own copy of xgmon connected to the same SNMP Query Engine. Only one xgmon needs to run the ever-lasting G programs like snmp_p_all, ping_all etc. So this one also needs at least one virtual G machine per long-running G program. Other xgmon instances can probably do with less virtual G machines. When any operator changes the status of a host (via a click with the middle mouse button), these are propagated to the other operators via the shared SNMP Query Engine.

Potential Operating Scenarios

The following operating scenarios can be set up for TCP/IP network management.

XGMON as independent Network Management Facility

This is covered in this manual. For a pictorial overview see Figure 9.

Multiple instances of xgmon can share one SNMP Query Engine as shown in Figure 10. In this case, the setup is as follows:

1. One (preferably dedicated) machine is the core of the xgmon services. This machine runs the SNMP Query Engine (sqeserv) and let us say the master copy of xgmon. It is this xgmon that runs the ever-lasting G programs like snmp_p_all, ping_all, trap, etc. So at this machine (let us name it qehost), the following commands would be issued (either manually or from a script at machine boot time):

      /usr/lpp/xgmon/bin/sqeserv -p 2100 1
      /usr/lpp/xgmon/bin/xgmon+
   

   The .xgmonrc+ file in the home directory would have entries like:

      bell_off
      query_engine qehost 2100
      compile /usr/lpp/xgmon/win/topology
      snmp_p_all
      ping_all
      trap

2. Any operator that wants to have a look at the network starts up his own copy of xgmon with his own profile (e.g., ".xgmonrc+"). He/she makes xgmon contact the SNMP Query Engine, so there is no need to run the ever-lasting programs that do the polling. So at his/her machine he/she issues this command:

      /usr/lpp/xgmon/bin/xgmon+ -m 3
   

   The .xgmonrc+ file in the home directory would have entries like:

      bell_off
      query_engine qehost 2100
      compile /usr/lpp/xgmon/win/topology
      snmp_p_all once
      ping_all once
      trap -l /dev/null

Note:

1. The trap program must be started and kept running in all copies of xgmon. The reason for this is that this command is responsible for propagating the operator actions on the display elements, like acknowledge. It is recommended to always have the trap program running anyway, because it picks up traps out of the xgmon kernel and then the storage occupied by those traps can be released. The -l /dev/null arguments tells trap not to log any traps.
2. The sqeserv program (SNMP Query Engine) reads a MIB description file "/usr/lpp/xgmon/lib/mib_desc" and uses the time-to-live (TTL) values specified in that file to determine how long each SNMP variable stays in the Query Engine cache. Each xgmon+ invocation reads the MIB descriptions from "/usr/lpp/xgmon/lib+/mib_desc" (or from the library you have specified via the GLIB environment variable). Again, that file specifies TTL values for each SNMP variable. As shipped, some of those TTLs are 15 minutes in each file. This means that xgmon on the qehost will initially request the variables from the SNMP Query Engine. From then, for up to 15 minutes, the values will be taken out of xgmon's cache, and no requests are made to the Query Engine during that time. When the other copies of xgmon start, they will not learn about the network status until they get that information from the SNMP Query Engine. However, the SNMP Query Engine will only propagate that information if at least one xgmon requests the relevant SNMP variables (that is what we want xgmon on the qehost to do via the snmp_p_all program). So theoretically we may not see the network status for 15 minutes or so. There are two things you can do to address this:
   1. Reduce the TTL values in the MIB description files read by xgmon (not the file read by the sqeserv program) to 10 or 15 seconds (especially if the sqeserv is on the same physical ring or ethernet). This more or less eliminates the double caching.
   2. Have the slave xgmon run programs like ping_all and snmp_p_all once at start-up. The sample "rc" files above show this option.

NetView as independent Network Management Facility

There is a simple, albeit complete, interface for SNMP support on NetView (as shown in Figure 11) and this has not changed since the initial implementation. This can be used if NetView is to be used as a totally independent TCP/IP network management entity.

Figure 11. Overview NetView SNMP Support.

1. NetView Operator or CLIST issues an SNMP command.
2. SNMP command is validated by SNMP Command Processor.
3. Command Processor passes request to SNMPIUCV task.
4. SNMPIUCV task passes request to SNMP Query Engine.
5. SNMP Query Engine validates and encodes request in ASN.1 and SNMP PDU and sends it to SNMP agent.
6. SNMP Query Engine receives response from SNMP agent.
7. SNMP Query Engine decodes response and sends it to NetView SNMPIUCV task.
8. SNMPIUCV task sends response as a multi-line message to requesting operator or authorized receiver.

   *--------------------*---------------------*-------------------*
   | Userid = NETVIEW   | Userid = SNMPQE     | Userid = TCPIP    |
   |                    |                     |                   |
   |                    |                     |                   |
   |      SNMP CMD PROC |      SQESERV        |                   |
   |            ^       |                     |                   |
   |            |       *---------------------*                   |
   |            V       |                     |                   |
   |      SNMPIUCV-TASK |   SOCKET I-FACE     |                   |
   |                    |                     |                   |
   |            ^       |   ^           ^     |   ^        ^      |
   |            |       |   |           |     |   |        |      |
   *------------+-------+---+-----------+-----+---+--------+------*
   |            |       |   |           |     |   |        |      |
   |  GCS       |       |   | CMS       |     |   | CMS    |      |
   |            |       |   |           |     |   |        |      |
   *------------+-------*---+-----------+-----*---+--------+------*
   |            |           |           |         |        |      |
   |            *-----------*           *---------*        |      |
   | VM or MVS      IUCV                   IUCV            |      |
   *-------------------------------------------------------+------*
                                                           V
 
                                                    LAN/ETHERNET
                                                    to SNMP agents

XGMON and NetView sharing SNMP Query Engine on a Mainframe

Figure 12. NetView and XGMON sharing Query Engine on Mainframe.

1. NetView Operator or CLIST issues an SNMP command or xgmon operator or G program issues an SNMP command.
2. SNMP command gets passed to SNMP Query Engine.
3. SNMP Query Engine validates and encodes request in ASN.1 and SNMP PDU and sends it to SNMP agent.
4. SNMP Query Engine receives response from SNMP agent
5. SNMP Query Engine decodes response and sends it back to requesting client (NetView or xgmon).
6. SNMP Query Engine sends a response-copy to those who have requested them (NetView or xgmon).
7. NetView and/or xgmon can SNMP SET specific SNMP variables (in the enterprise-specific IBM tree of the MIB) for agent 255.255.255.255 to exchange information between each other (this is how xgmon can issue NetView commands and receive the reply).

   *--------------------*---------------------*-------------------*
   | Userid = NETVIEW   | Userid = SNMPQE     | Userid = TCPIP    |
   |                    |                     |                   |
   |      SNMP CMD PROC |      SQESERV        |                   |
   |            ^       |                     |                   |
   |            |       *---------------------*                   |
   |            V       |                     |                   |
   |      SNMPIUCV-TASK |   SOCKET I-FACE     |                   |
   |                    |                     |                   |
   |            ^       |   ^           ^     |   ^        ^      |
   |            |       |   |           |     |   |        |      |
   *------------+-------+---+-----------+-----+---+--------+------*
   |            |       |   |           |     |   |        |      |
   |  GCS       |       |   | CMS       |     |   | CMS    |      |
   |            |       |   |           |     |   |        |      |
   *------------+-------*---+-----------+-----*---+--------+------*
   |            |           |           |         |        |      |
   |            *-----------*           *---------*        |      |
   | VM or MVS      IUCV                   IUCV            |      |
   *-------------------------------------------------------+------*
                                                           V
 
                             SNMP agents <--------->   LAN/ETHERNET
                                                             ^
                                                             |
                                                             |
  *------------*       *---------------*----------------*    |
  |   X11      |       |               |                |    |
  |   Display  |<----->|       XGMON   |                |    |
  |            |       |               |                |    |
  *------------*       |               |                |    |
  Operator             |         ^     |                |    |
                       |         |     |                |    |
                       *---------+-----*----------------*    |
                       |         *----------------------+----*
                       |                                |
                       | UNIX  (with TCP/IP)            |
                       *--------------------------------*
                       RISC System/6000 (or any system with UNIX)

xgmon and NetView can share the network management workload using an SNMP Query Engine running on the mainframe. Figure 12 shows how this is done.

xgmon can connect to the same SNMP Query Engine on the NetView mainframe host (on VM or MVS) and share the TCP/IP network management tasks with NetView. In this case, the xgmon operator issues:

   query_engine hostname portid

All SNMP requests are executed in the Query Engine, and the response packets are available for all clients (xgmon and NetView) of the Query Engine. In principle, only one of the two clients needs to run the polling procedures and the other client can request to receive response copies.

For instance, if NetView runs a set of CLISTs that do the SNMP polling at regular intervals, xgmon will get a copy of response packets from the polled agents. As a result, the topology display at the xgmon operator station will be colored to represent the network status. So effectively xgmon now has become a graphical front-end to NetView as far as the TCP/IP network is concerned.

Another sample would be to off-load the SNMP polling to xgmon and have NetView receive response copies. In order for NetView to receive such response copies, the operator (or a CLIST) needs to issue the SNMP COPYON command at start-up.

In addition, xgmon has a netview library command (a G program) that allows the xgmon operator to issue NetView commands. As an example, the xgmon operator could issue:

   netview cmd d net,majnodes

In order for this to work, the NetView operator (or a CLIST like SNMPINIT) must issue (at start-up) an SNMP COPYON command. If only communication between NetView and xgmon is wanted (and NetView does not want to get other response copies), the NetView operator can issue:

   SNMP COPYON 255.255.255.255 255.255.255.255

XGMON and NetView sharing SNMP Query Engine on a UNIX workstation

Figure 13. NetView and XGMON sharing Query Engine on Workstation.

1. NetView Operator or CLIST issues an SNMP command or xgmon operator or G program issues an SNMP command.
2. SNMP command gets passed to SNMP Query Engine.
3. SQESERF on the main-frame just passes any request from its clients (NetView in this case) on to the real Query Engine (SQESERV) on the workstation and vice-versa.
4. SNMP Query Engine validates and encodes request in ASN.1 and SNMP PDU and sends it to SNMP agent
5. SNMP Query Engine receives response from SNMP agent decodes it and sends it back to requesting client (NetView or xgmon).
6. SNMP Query Engine sends a response-copy to those who have requested them (NetView or xgmon).
7. NetView and/or xgmon can SNMP SET specific SNMP variables (in the enterprise-specific IBM tree of the MIB) for agent 255.255.255.255 to exchange information between each other (this is how xgmon can issue NetView commands and receive the reply).

   *--------------------*---------------------*-------------------*
   | Userid = NETVIEW   | Userid = SNMPQE     | Userid = TCPIP    |
   |                    |                     |                   |
   |      SNMP CMD PROC |      SQESERF        |                   |
   |            ^       |                     |                   |
   |            |       *---------------------*                   |
   |            V       |                     |                   |
   |      SNMPIUCV-TASK |   SOCKET I-FACE     |                   |
   |                    |                     |                   |
   |            ^       |   ^           ^     |   ^        ^      |
   |            |       |   |           |     |   |        |      |
   *------------+-------+---+-----------+-----+---+--------+------*
   |            |       |   |           |     |   |        |      |
   |  GCS       |       |   | CMS       |     |   | CMS    |      |
   |            |       |   |           |     |   |        |      |
   *------------+-------*---+-----------+-----*---+--------+------*
   |            |           |           |         |        |      |
   |            *-----------*           *---------*        |      |
   | VM or MVS      IUCV                   IUCV            |      |
   *-------------------------------------------------------+------*
                                                           V
                             SNMP agents <--------->   LAN/ETHERNET
                                                             ^
  *------------*       *---------------*----------------*    |
  |   X11      |       |               |                |    |
  |   Display  |<----->|       XGMON   |      SQESERV   |    |
  |            |       |               |                |    |
  *------------*       |               |                |    |
  Operator             |            <--+-->             |    |
                       |               |           ^    |    |
                       |               |           |    |    |
                       *---------------*-----------+----*    |
                       |                           |    |    |
                       |                           *----+----*
                       | UNIX  (with TCP/IP)            |
                       *--------------------------------*
                       RISC System/6000 (or any system with UNIX)

xgmon and NetView can share TCP/IP network management tasks using an SNMP Query Engine running on an UNIX workstation. This is shown in Figure 13.

This set-up allows all of resource-consuming work for TCP/IP network management to be off-loaded to the UNIX workstation.

On the workstation, sqeserv is started with

   sqeserv -p portid

   query_engine hostname portid

   sqeserf -rp portid -rh hostname

In this set-up, one can run the same scenario as described in "XGMON and NetView sharing SNMP Query Engine on a Mainframe". However, since the goal was to off-load as much work as we possibly can, consider the following:

xgmon does the actual SNMP polling and other tasks to monitor the TCP/IP network. NetView does not issue a general response-copy request, but only the specific request to obtain response copies from agent 255.255.255.255, thus NetView will not be bother by any TCP/IP network management data by default. When xgmon detects that something serious happens, it can use the netview command to report this situation to NetView. For instance it could massage the information it has in a GENALERT command and send that to NetView. The NetView operator would then be made aware of serious events via the ALERTS DYNAMIC panel and can take actions like:

• Issue additional SNMP commands from his NetView screen to obtain more details.
• Issue additional SNMP commands from xgmon to obtain more details
• Take appropriate action to get somebody working on fixing the problem. Once that happens, he might even execute a CLIST to acknowledge the problem back to xgmon such that the graphical topology display can be updated with the appropriate color to indicate an acknowledged problem.

XGMON as a Front-End for SNA Network Management

No samples are provided yet, but the capabilities exist to configure a topology display for a SNA network being managed by NetView. This way, xgmon could act as an UNIX-based graphical interface to NetView. The two-way communication facilities between NetView and xgmon can then be exploited to inform xgmon when things happen to the SNA network, and G programs in xgmon can be developed to color the topology display of the SNA network appropriately such that it represents the network status. And as described above, the xgmon operator can issue additional netview commands to obtain more detailed information from NetView if a host turns red on the topology display.

Multiple XGMON and NetView instances sharing the SNMP Query Engine

Currently up to 20 clients can share the SNMP Query Engine (this is not an architectural but only an implementation limit) So it is possible to configure a set-up where multiple NetView and multiple xgmon instances share the same SNMP Query Engine.

If xgmon is used a graphical front-end for instance, then each operator could be running an instance of xgmon and all topology displays would be kept up to date with the same status of the network. Also when one operator acknowledges a problem, this will be propagated to the other topology displays, so that all operators can see that a problem has been taken care of.

All together, this forms a pretty powerful and flexible platform for developing a good network management environment. You can decide where you want to put the main workload (mainframe or workstation) and which (combination of) interfaces (xgmon and/or NetView) are best for the operators.

Samples for XGMON <--> NetView Communication

The following samples will allow an xgmon operator to issue a Netview command like:

   netview cmd d net,majnodes

The netview G-program

This program is shipped with xgmon version 0.9 and up.

Figure 14. Sample netview G program for XGMON

start thread int argc; pointer argv; string command, arg, obj_id; string var_name, new_command; int i, len, tmp, delta; int count, replied, max_delay; string obj_prefix, reply; if (argc <= 2) { print "usage: %s command args\n", argv[0]; print "\tcommand can be \'cmd\' or \'msgop\'\n"; exit; } command = argv[2]; i = 3; while (i < argc) { arg = argv[i]; command = command + " " + arg; i = i + 1; } arg = argv[1]; var_name = "NV" + arg; if (arg == "cmd") { // must map to uppercase new_command = ""; len = (int) strlen(command); i = 1; delta = (int) ascii("a") - (int) ascii("A"); while (i <= len) { arg = (string) mid(command, i, 1); if ((arg >= "a") &1(arg <= "z")) { tmp = (int) ascii(arg) - delta; arg = (string) sprintf("%c", tmp); } new_command = new_command + arg; i = i + 1; } command = new_command; } obj_id = (string) snmp_var(var_name); if (obj_id == "") { print "command not supported: %s\n", argv[1]; exit; } i = (int) time(0); obj_id = obj_id + (string) num(i); send snmp set obj_id, command to "255.255.255.255"(""); arg = argv[1]; if (arg != "cmd") exit; // all done // now wait for reply from command obj_prefix = (string) snmp_var("NVreply"); if (obj_prefix == "") { print "can't look up NVreply variable...\n"; exit; } obj_prefix = obj_prefix + (string) num(i) + "."; replied = 1; // assume replied sleep 1; // wait a bit before first attempt i = 1; max_delay = 25; while (replied == 1) { replied = 0; obj_id = obj_prefix + (string) num(i); count = 0; while (count < max_delay) { reply = (string) gw_var("255.255.255.255",obj_id); if (reply != "") { replied = 1; count = max_delay; } if (reply == "") { count = count + 1; if (count == max_delay) { print "no reply\n"; exit; } sleep 1; // wait a bit } } if (replied) { print "%s\n", reply; // check for last message if ((string) left(reply,7) == "XGM002I") replied = 0; } i = i + 1; } end thread

NetView CLISTs and Message Automation Entries

These are shipped with TCP/IP Version 2 for VM (at level 1410) and MVS (at initial shipment). For details on the installation of NetView SNMP support see the TCP/IP Version 2 for VM (or MVS) Installation and Maintenance Manual.

Message Automation.

These entries need to go in the message automation table that is activated on NetView with AUTOMSG command. Normally that table is activated at NetView initialization.

The relevant entries for our discussion are:

• The entry for message SNM102I to trigger SNMPINIT which will issue a SNMP COPYON command to receive copy-responses for IP address 255.255.255.255 (from XGMON).
• The entry for message SNM060I to trigger SNMPCPR which will recognize a request from xgmon to issue a NetView command.

Figure 15. Sample entries for NetView message automation table

*********************************************************************** * * * These are sample statements for the NetView message automation * * table. They allow 2-way communication between NetView and XGMON. * * * * Next statement triggers SNMPCPR clist when an SNMP Copy-Response * * is received. The first form ($OPAUTO$) is executed in an AUTO task, * * which will msgroute Copy-Response packets from agents other than * * 255.255.255.255 to an operator (see SNMPCPR for details). * * The second form ($TOOPER$) is executed in NETOP1 or NETOP2 operator * * task, such that you can see what's happening. The copy-response * * packet is also re-formatted a bit for better legibility. * * This mode is not recommended, but does show what happens. * * The third form ($TOAUTO$) is executed in an AUTO task, but regular * * Copy-Response packets for agents other then 255.255.255.255 will * * just be ignored. You can update the SNMPCPR clist to do other * * things with these copy-responses, like analyze them and take some * * other action if required. * * The clist handles the message different in each case. * * * * The SNMPCPR recognizes special SNMP variables from the special * * (not really existing) agent 255.255.255.255: * * * * NVcmd - containing a NetView cmd to be executed. * * NVmsgop - containing a message for the NetView Operator. * * * * In case of a NVcmd, the SNMPCPR clist calls XGMNVCMD clist to do * * the actual work. * * Other variables from 255.255.255.255 are interpreted as any other * * copy-response packet from any other agent. * * * *********************************************************************** * *IF MSGID='SNM060I' * THEN EXEC(CMD('SNMPCPR $OPAUTO$') ROUTE(ONE AUTO1 AUTO2)) * DISPLAY(N); *IF MSGID='SNM060I' * THEN EXEC(CMD('SNMPCPR $TOOPER$') ROUTE(ONE NETOP1 NETOP2)) * DISPLAY(N); IF MSGID='SNM060I' THEN EXEC(CMD('SNMPCPR $TOAUTO$') ROUTE(ONE AUTO1 AUTO2)) DISPLAY(N); * *********************************************************************** * * * Following entries is a sample to get the TRAPSON and COPYON command * * re-issued if the connection with the Query Engine breaks and comes * * back up again. * * * *********************************************************************** * IF MSGID='SNM102I' THEN EXEC(CMD('SNMPINIT $OPAUTO$') ROUTE(ONE AUTO1 AUTO2)) DISPLAY(N); *IF MSGID='SNM102I' * THEN EXEC(CMD('SNMPINIT $TOOPER$') ROUTE(ONE NETOP1 NETOP2)) * DISPLAY(N); *IF MSGID='SNM102I' * THEN EXEC(CMD('SNMPINIT $TOAUTO$') ROUTE(ONE AUTO1 AUTO2)) * DISPLAY(N); * *********************************************************************** * * * Following entry suppresses msg SNM100I, which gets displayed each * * time that NetView tries to connect to SNMP Query Engine (default is * * every 60 seconds until connect succeeds). * * * *********************************************************************** * IF MSGID='SNM100I' THEN DISPLAY(N);

SNMPINIT CLIST

This CLIST is triggered at NetView startup after NetView connects to the SNMP Query Engine, and every time that connection gets re-established after a restart or failure. For this discussion, the piece that we are interested in is the fact that it issues a COPYON request to receive copy-responses from IP address 255.255.255.255, via which xgmon sends NetView commands.

Figure 16. Sample SNMPINIT CLIST

CLIST &CONTROL ERR *-------------------------------------------------------------* * Member name: * * SNMPINIT * * * * Copyright: * * Licensed Materials - Property of IBM * * This product contains "Restricted Materials of IBM" * * 5735-FAL (C) Copyright IBM Corp. 1990. * * All rights reserved. * * US Government Users Restricted Rights - * * Use, duplication or disclosure restricted by GSA ADP * * Schedule Contract with IBM Corp. * * See IBM Copyright Instructions. * * * * Function: * * Sample CLIST to (re-)issue the TRAPSON and TRAPSOFF * * commands when NetView connection with the SNMP Query * * Engine gets (re-)established. * * * * Library: * * On MVS: Member SNMPINIT in NetView's DSICLD dataset. * * On VM: File SNMPINIT NCCFLST on a NetView minidisk. * * * * Change activity: * * * * PTM DATE DESCRIPTION * * ------- ------- -----------------------------------------* * 14Nov90 Final version * * * *-------------------------------------------------------------* * &IF .&1 EQ .? &THEN &GOTO -EXPLAIN &IF .&1 EQ .HELP &THEN &GOTO -EXPLAIN &GOTO -BEGIN -EXPLAIN CLEAR &BEGWRITE SUB -EXPLAINE Usage: SNMPINIT This clist is normally driven by the message automation table to handle issue initial requests (like COPYON, TRAPSON and such) when the connection with the Query Engine gets (re-)established. See SNMPMSGA for sample entries in the message automation table. -EXPLAINE &EXIT -BEGIN &MODE = &1 ?SNMP TRAPSON &TF = &RETCODE ?SNMP COPYON 255.255.255.255 255.255.255.255 &CF = &RETCODE * * Just checking retcode. Sophisticated checking would capture * messages SNM050I and SNM040I and verify a "no error" response. * &IF &TF LT 1000 &THEN &TM = &CONCAT 'SNMP TRAPSON command error: ' &TF &IF &TF LT 1000 &THEN &CM = &CONCAT 'SNMP COPYON command error: ' &CF &IF &TF GE 1000 &THEN &TM = &CONCAT 'TRAP filter is: ' &TF &IF &CF GE 1000 &THEN &CM = &CONCAT 'COPY-RESPONSE filter is: ' &CF &SMSG = '(Re-)connected to SNMP Query Engine' &IF .&MODE EQ .$TOOPER$ &THEN &GOTO -REFORM &IF .&MODE EQ .$OPAUTO$ &THEN &GOTO -ROUTEOP &IF .&MODE EQ .$TOAUTO$ &THEN &GOTO -SKIP &IF .&MODE EQ .CNME1034 &THEN &GOTO -STARTUP &GOTO -ROUTEOP *-------------------------------------------------------------* * Sample of MSGROUTE solution to send it to a one operator * *-------------------------------------------------------------* -ROUTEOP &MTO = NETOP1 &GOTO -INFORM -STARTUP &SMSG = 'Initialize TRAP and COPY-RESPONSE' &MTO = ALL -INFORM * MSGROUTE NETOP1 DISPLAY(Y) MSG &MTO *************************************** MSG &MTO * &SMSG MSG &MTO * Requesting all traps from anywhere MSG &MTO * &TM MSG &MTO * Requesting copy-response from XGMON MSG &MTO * &CM MSG &MTO *************************************** &EXIT *-------------------------------------------------------------* * Sample of other stuff to do. We just skip it. * *-------------------------------------------------------------* -SKIP &EXIT *-------------------------------------------------------------* * Sample of how the message could be reformatted to be more * * legiable for an operator. * *-------------------------------------------------------------* -REFORM &WRITE *************************************** &WRITE * (Re-)connected to SNMP Query Engine &WRITE * Requesting all traps from anywhere &WRITE * &TM &WRITE * Requesting copy-response from XGMON &WRITE * &CM &WRITE *************************************** &EXIT

SNMPCPR CLIST

This CLIST is triggered at NetView for every copy-response it receives. The interesting part for our discussion here is the piece that recognizes that a copy-response for variable NVcmd comes in and then passes the command to the XGMNVCMD CLIST.

Figure 17. Sample SNMPCPR CLIST

CLIST &CONTROL ERR *-------------------------------------------------------------* * Member name: * * SNMPCPR * * * * Copyright: * * Licensed Materials - Property of IBM * * This product contains "Restricted Materials of IBM" * * 5735-FAL (C) Copyright IBM Corp. 1990. * * All rights reserved. * * US Government Users Restricted Rights - * * Use, duplication or disclosure restricted by GSA ADP * * Schedule Contract with IBM Corp. * * See IBM Copyright Instructions. * * * * Function: * * Sample CLIST to handle all copy-response msgs * * * * Library: * * On MVS: Member SNMPCPR in NetView's DSIPRM dataset. * * On VM: File SNMPCPR NCCFLST on a NetView minidisk. * * * * Change activity: * * * * PTM DATE DESCRIPTION * * ------- ------- -----------------------------------------* * 12Nov90 Final version * * * *-------------------------------------------------------------* * &IF .&1 EQ .? &THEN &GOTO -EXPLAIN &IF .&1 EQ .HELP &THEN &GOTO -EXPLAIN &GOTO -BEGIN -EXPLAIN CLEAR &BEGWRITE SUB -EXPLAINE Usage: SNMPCPR This clist is normally driven by the message automation table to handle copy-response packets from the SNMP Query Engine. Assumptions: 1. NetView has issued a COPYON command to receive copy-response packets from a SNMP Query Engine that it shares with XGMON. 2. A message automation table is active to recognize multiline message SNM060I and then trigger this CLIST. 3. Only one SNMP variable per copy-response to be handled 4. If copy-response packets come from host 255.255.255.255 then they contain special XGMON variables. For instance: NVcmd - A NetView command to be executed NVmsgop - A Message to be send to the NetView operator 5. XGMON sends data by SETing the these special variable via na SNMP SET command. For commands and messages there is a netview G program (netview.g) to set the correct variable. -EXPLAINE &EXIT -BEGIN &MODE = &1 &I = 1 ?GETMSIZE CNT -GMLOOP &L = &CONCAT L &I &M = &CONCAT M &I &B = &CONCAT B &I &D = &CONCAT D &I ?GETMLINE &L &I ?PARSEL2R &L &M &B /: / &D &I = &I + 1 &IF &I LE &CNT &THEN &GOTO -GMLOOP &IF .&M2 NE .SNM061I &THEN &GOTO -INVALID &GOTO -FROMAGT -EXIT &EXIT -INVALID &WRITE Unrecognized 'Copy-Response' packet -INVGO &I = 1 -INVLOOP &WRITE * &L&I &I = &I + 1 &IF &I LE &CNT &THEN &GOTO -INVLOOP &EXIT -FROMAGT &IF &D2 EQ 255.255.255.255 &THEN &GOTO -DOMIBV &IF &MODE NE $TOOPER$ &THEN &GOTO -WRITEIT -DOMIBV &WAIT SUPPRESS CONTWAIT &WAIT 'SNMP MIBVNAME &D3' + SNM040I=-GOT40I, + SNM050I=-GOT50I, + *10=-EWAIT, + *ENDWAIT=-EWAIT &EXIT -EWAIT &WRITE Timed out or canceled by operator, while trying &WRITE to obtain MIB Variable name in textual form. &WRITE Here is the raw data anyway: &GOTO -INVGO -GOT50I &R = &RETCODE &WAIT ENDWAIT &WAIT CONTINUE &EXIT -GOT40I * Should I check for &R to be our retcode ? &J = 1 ?GETMSIZE CNT -G40LOOP &ML = &CONCAT ML &J &MM = &CONCAT MM &J &MB = &CONCAT MB &J &MD = &CONCAT MD &J ?GETMLINE &ML &J ?PARSEL2R &ML &MM &MB /: / &MD &J = &J + 1 &IF &J LE &CNT &THEN &GOTO -G40LOOP &IF &D2 NE 255.255.255.255 &THEN &GOTO -WRITEIT &NV = &SUBSTR &MD4 1 6 &INST = &SUBSTR &MD4 7 &IF .&NV EQ .NVcmd. &THEN &GOTO -XGMCMD &NV = &SUBSTR &MD4 1 8 &INST = &SUBSTR &MD4 9 &IF .&NV EQ .NVmsgop. &THEN &GOTO -XGMMSG -WRITEIT &IF &MODE EQ $TOOPER$ &THEN &GOTO -REFORM &IF &MODE EQ $OPAUTO$ &THEN &GOTO -ROUTEGR &IF &MODE EQ $TOAUTO$ &THEN &GOTO -SKIP *-------------------------------------------------------------* * Here we can do one of several things: * * - MSGROUTE the whole copy response to an operator in a * * special group (+CPYRESP in this sample) ho will then * * get the raw copy-response message as it would have * * shown up as unsolicited message without message * * automation. * * If this routine is run in an AUTO task, it seems that * * this is one way of getting the data to an operator. * * - Reformat the raw data in some more legible form as * * is shown below under heading REFORMAT. * * However, it uses &WRITE statements to write the data, * * and so if run in an AUTO task, nobody sees it. * * - Do other things as you see fit, like analyze the data * * and take appropriate action like maybe adding an ALERT * * to the NPDA database. * *-------------------------------------------------------------* *-------------------------------------------------------------* * Sample of MSGROUTE solution to send it to a group * * Operators issue ASSIGN GROUP=+CPYRESP,OP=(oper1,oper2,..) * * to receive the messages * *-------------------------------------------------------------* -ROUTEGR MSGROUTE +CPYRESP DISPLAY(Y) &EXIT *-------------------------------------------------------------* * Sample of MSGROUTE solution to send it to a one operator * *-------------------------------------------------------------* -ROUTEOP MSGROUTE NETOP1 DISPLAY(Y) &EXIT *-------------------------------------------------------------* * Sample of other stuff to do. We just skip it. * *-------------------------------------------------------------* -SKIP &EXIT *-------------------------------------------------------------* * Sample of how the message could be reformatted to be more * * legible for an operator. * * The multiline SNM060I message will be reformatted to: * * * * Copy-Response from Agent nn.nn.nn.nn * * . Varname = Varvalue * * . More Varvalue if it doesn't fit on one line * * . and so on * *-------------------------------------------------------------* -REFORM * &LL - The line length on the 327x display * &T - The length of: varname = * that is length &MD4 plus = sign plus 2 blanks * &IL - The indentation length for all * &IL2 - The indentation length for continuation lines * &DL - The remaining length for datavalue per line * &I - The number of message lines from above * &J - Counter to loop through message lines * &DL&L - The date lines to be written &LL = 80 &CHL = 13 &T = &LENGTH &MD4 &T = &T + 3 &IL = 2 &IL2 = &IL + &T &DL = &LL - &IL2 - &CHL &DT1 = &SUBSTR '. ' 1 &IL &DT2 = &SUBSTR '. ' 1 &IL2 &J = 1 &L = 1 -WRLOOP &J = &J + 1 &IF &J GE &I &THEN &GOTO -WRREAL &IF &M&J NE SNM064I &THEN &GOTO -WRLOOP &D = &CONCAT &DL&L &D&J &LDX = &LENGTH &D &DP = 1 -WRLOOP2 &DL&L = &SUBSTR &D &DP &DL &LDX = &LDX - &DL &IF &LDX LE 0 &THEN &GOTO -WRLOOP &L = &L + 1 &DP = &DP + &DL &GOTO -WRLOOP2 -WRREAL &WRITE Copy-Response from Agent &D2 &WRITE &DT1 &MD4 = &DL1 &M = 1 -WRREAL1 &M = &M + 1 &IF &M GT &L &THEN &EXIT &WRITE &DT2 &DL&M &GOTO -WRREAL1 -XGMMSG &J = 0 -MSLOOP &J = &J + 1 &IF &J GE &I &THEN &GOTO -MSLOOPE &IF &M&J NE SNM064I &THEN &GOTO -MSLOOP &XGMMSG = &CONCAT &XGMMSG &D&J &GOTO -MSLOOP -MSLOOPE &IF &MODE EQ $TOOPER$ &THEN &GOTO -XGMMSG1 &IF &MODE EQ $OPAUTO$ &THEN &GOTO -XGMMSG2 &IF &MODE EQ $TOAUTO$ &THEN &GOTO -XGMMSG2 -XGMMSG1 &WRITE Msg from XGMON: &XGMMSG &EXIT -XGMMSG2 ?MSG ALL Msg from XGMON: &XGMMSG &EXIT -XGMCMD &J = 0 -CMLOOP &J = &J + 1 &IF &J GE &I &THEN &GOTO -CMLOOPE &IF &M&J NE SNM064I &THEN &GOTO -CMLOOP &CMD = &CONCAT &CMD &D&J &GOTO -CMLOOP -CMLOOPE &WRITE XGMON is executing: &CMD ?XGMNVCMD &INST &CMD &EXIT

XGMNVCMD CLIST

This CLIST is called by SNMPCPR CLIST when it gets a copy response fro variable NVcm from xgmon. It issues the command, captures the reply lines to the command and then sends these reply lines back by setting instances of the variable NVreply. The netview xgmon library command captures those replies and displays them to the operator.

Figure 18. Sample XGMNVCMD CLIST

CLIST &CONTROL ERR *-------------------------------------------------------------* * Member name: * * XGMNVCMD * * * * Copyright: * * Licensed Materials - Property of IBM * * This product contains "Restricted Materials of IBM" * * 5735-FAL (C) Copyright IBM Corp. 1990. * * All rights reserved. * * US Government Users Restricted Rights - * * Use, duplication or disclosure restricted by GSA ADP * * Schedule Contract with IBM Corp. * * See IBM Copyright Instructions. * * * * Function: * * Sample CLIST to accept NetView commands from XGMON * * * * Library: * * On MVS: Member XGMNVCMD in NetView's DSIPRM dataset. * * On VM: File XGMNVCMD NCCFLST on a NetView minidisk. * * * * Change activity: * * * * PTM DATE DESCRIPTION * * ------- ------- -----------------------------------------* * 12Nov90 Final version * * * *-------------------------------------------------------------* * &IF .&1 EQ .? &THEN &GOTO -EXPLAIN &IF .&1 EQ .HELP &THEN &GOTO -EXPLAIN &INST = &1 &IL = &LENGTH &INST &IL = &IL + 1 &XGMCMD = &SUBSTR &PARMSTR &IL &GOTO -BEGIN -EXPLAIN CLEAR &BEGWRITE SUB -EXPLAINE Usage: XGMNVCMD instance netview_command This clist is driven by SNMPCPR when it receives a NetView command from XGMON. SNMPCPR get driven from the message automation table via msg SNM060I (Copy-Response). It checks if the copy-response came from agent 255.255.255.255 (special XGMON address) and which variable is contained in the copy-response. If it is the NVcmd variable, then it contains a NetView command to be executed and so it calls upon this clist. This clist better be driven by the message automation table directly but it seems the IF-THEN logic does not allow to test on data in the the 2nd and subsequent lines of a multi-line message. Assumptions: 1. NetView has issued a COPYON command to receive copy-response packets from a SNMP Query Engine that it shares with XGMON. 2. XGMON sends the command by SETing the NVcmd variable to a value that represents the command to be executed. XGMON has a netview.g program to do that. -EXPLAINE &EXIT -BEGIN &FIRST = YES &NVRINST = &CONCAT NVreply. &INST &NVRINST = &CONCAT &NVRINST '.' &NVREPLY = &CONCAT &NVRINST 1 &NVRVAL = &CONCAT ''XGM001I Response(s) for command: ' &XGMCMD &NVRVAL = &CONCAT &NVRVAL ''' ?SNMP SET 255.255.255.255 CNAME &NVREPLY &NVRVAL &J = 2 &WAIT CONTWAIT &WAIT '&XGMCMD' *=-GOTRESP,*ENDWAIT=-ENDWAIT, + *10=-TIMOUT &WRITE not expected -GOTRESP &I = 1 GETMSIZE CNT &IF &CNT GT 0 &THEN &GOTO -GOTLOOP &WRITE Empty, GETMSIZE returns &CNT &WAIT CONTINUE &WRITE Should never come here &EXIT -GOTLOOP &L = &CONCAT L &I &M = &CONCAT M &I &B = &CONCAT B &I &D = &CONCAT D &I GETMLINE &L &I PARSEL2R &L &M &B /: / &D PARSEL2R &L TMP /XGMNVCMD/ KEY REAL TMP &IF .&KEY EQ .END &THEN &GOTO -ENDCMD &IF &FIRST EQ YES &THEN &WRITE The XGMNVCMD END TRIGGER &FIRST = NO &MID = &SUBSTR &M&I 1,3 &IF &MID EQ SNM &THEN &GOTO -SKIPSNM &NVREPLY = &CONCAT &NVRINST &J &NVRVAL = &CONCAT ''' &L&I &NVRVAL = &CONCAT &NVRVAL ''' ?SNMP SET 255.255.255.255 CNAME &NVREPLY &NVRVAL &J = &J + 1 -SKIPSNM &I = &I + 1 &IF &I LE &CNT &THEN &GOTO -GOTLOOP &WAIT CONTINUE &EXIT -ENDCMD &IF .&REAL NE .TRIGGER &THEN &GOTO -ENDCMDE &WRITE The XGMNVCMD END for real &NVREPLY = &CONCAT &NVRINST &J &NVRVAL = &CONCAT ''XGM002I End of response'' ?SNMP SET 255.255.255.255 CNAME &NVREPLY &NVRVAL &WAIT ENDWAIT &WAIT CONTINUE -ENDCMDE &NVREPLY = &CONCAT &NVRINST &J &NVRVAL = &CONCAT ''XGM002I End of response'' ?SNMP SET 255.255.255.255 CNAME &NVREPLY &NVRVAL &EXIT -ENDWAIT &WRITE Endwait, not really expected, but may happen &EXIT -TIMOUT &WRITE Timeout, not really expected, but may happen &EXIT

Appendix G. XGMON to OSF/DME Migration

Considerably more time was spent in the design of DRAGONS and we are happy to have been selected by the Open Software Foundation to provide a few key enabling technologies for their Distributed Management Environment. Our selected technologies provide for a very open distributed object-oriented environment well-suited for network management-related applications. As part of the technologies we are providing OSF, we include the ability to make SNMP requests from within the environment. ⁹

During this process, the needs of the xgmon user community have been in the forefront of our plans: it would be cruel to leave everyone out in the cold as we move to the next generation of technology. Fortunately, the design of xgmon has made it possible for us to lay out a straightforward migration strategy: this is the result of the use of a compiled language as the API.

We have connected xgmon to the new environment and demoed this in April of 1991. This form of usage is in the same spirit as using the SNMP Query Engine. This was phase 1 of the migration and is in use at selected sites.

The next phase is to model the network topology within the DRAGONS Data Engine and use this to drive xgmon topology screens. This is phase 2 of the migration and is in progress. Current xgmon distributions include the top2objs library command which can be used to convert a compiled xgmon topology into the necessary DRAGONS Data Engine object creation records. ¹⁰

The sample implementation of the snmp_p_all equivalent in the Data Engine uses a JobController object to handle the distribution of work. This means that an arbitrary number of threads can be working in parallel to collect status information from the network (contrast this to xgmon's fixed limit on the number of virtual G machines). If polling times need to be decreased, the number of active threads permitted can be increased by changing a single configuration parameter. If the network management station is running at 100% utilization, then changing another configuration parameter (how many Data Engines may be used in the job) causes the polling workload to be automatically and transparently distributed across multiple CPUs: all without a single change to a line of application code. ¹¹

Phase 3 is to re-target the G compiler to output source code suitable for compilation and subsequent linking into the new environment (dynamic linking is already supported by the DRAGONS Data Engine). ¹²

The final phase is to provide a new topology display that includes all of the features requested over the years and a constraint solver to handle layout issues.

This all boils down to one simple statement: the G programs you write today will be able to be ported to the OSF DME with minimal effort. Today (not tomorrow) we have the technology available to handle networks of thousands of hosts: one doesn't have to outgrow xgmon, one can grow into DRAGONS and the OSF DME.

Definition of Terms

The following terms are often used when talking about xgmon:

A
agent	an SNMP agent implements the server side of an SNMP-based network management system. It is normally passive, waiting for requests from a network management station; however, it can generate asynchronous notifications, called traps.
AIX*	IBM's flavor of UNIX.
ASN.1	Abtract Syntax Notation 1
C
C Language	a popular programming language. ;-)
D
display element	a display element is a graphic symbol that can be drawn by xgmon on a topology display. The xgmon core can draw lines and labeled boxes. The notation dep comes from the phrase display element pointer.
Dot Notation	a textual form of an IP address in which each byte is represented in base 256, with dots (periods) placed between the numbers (e.g., 129.34.222.70).
E
EGP	Exterior Gateway Protocol -- a popular protocol used to exchange routing information between domains.
G
G-code	object code that is interpreted by virtual G machines.
G language	a high-level language targetted towards SNMP network management.
G machine	(see Virtual G machine).
G program	a program written in the G language. This is the language that the xgmon core is able to compile. G is a high-level language targeted towards network management applications.
I
Intrinsic function	a function built into the xgmon core.
IP address	Internet Protocol address -- a 32-bit value that can be broken down into a network/host pair.
M
management station	implements the client side of an SNMP-based network management system.
MIB	the Management Information Base defines a core set of management variables which are available. The values of these variables are obtained or manipulated in the process of monitoring or managing SNMP-based network elements.
MIB description file	a file containing the description of Management Information Base variables that xgmon should recognize. This file permits xgmon to map text names for variables to their object IDs, and provides the needed type information when performing an SNMP set operation.
P
ping	a utility (or operation) that uses ICMP ECHO_REQUEST packets to test reachability and round-trip delay between two hosts.
R
RFC	Request For Comments -- the mechanism by which TCP/IP protocols are documented.
S
SNMP	the Simple Network Management Protocol is a protocol that can be used to obtain network management information from a remote host. The protocol permits the remote acquisition and manipulation of management information variables.
SNMP agent	a server that responds to SNMP get, get-next and set requests. It also generates SNMP traps.
SNMP Query Engine	an IBM server that provides proxy SNMP services. This server is the mechanism by which NetView makes SNMP requests, but xgmon can also utilize the server. The server can run under VM/CMS, MVS or any flavor of AIX.
T
T1, T3 lines	point-to-point communication lines of approx. 1.5 Mbs/sec and 45 Mbs/sec respectively.
TCP	Transmission Control Protocol -- a major protocol of the TCP/IP suite. TCP provides reliable, flow-controlled, two-way tranmission of data and provides the abstraction of a full duplex byte-stream.
TCP/IP	Transmission Control Protocol/Internet Protocol -- generally used to refer to a suite of protocols, including IP, ICMP, UDP and TCP.
topology description	an English-like description of the network topology, which describes the desired graphical layout to be used for display, as well as other interesting information (such as the community name, protocol to use for queries, IP addresses assigned to the host, etc.).
trap	an unsolicited notification of a significant event. SNMP traps are best treated as hints, not as authoritative statements. Delivery of SNMP traps is also not guaranteed--this has a significant impact on the network management station implementation.
TTY	teletype terminal -- basically, a simple I/O terminal that has no graphics capability, much less an addressable cursor.
U
UDP	User Datagram Protocol -- a datagram service on top of IP.
UNIX*	a popular operating system. ;-)
V
virtual G machine	an abstract, imaginary machine architecture that is able to run compiled G programs. The xgmon core implements this architecture.
X
X11	denotes the X11 Window System, a network transparent window system developed at MIT which runs on a wide range of computing and graphics machines.
X11R3	references the 3rd release of X11. In general, subsequent releases are upwardly compatible and either add new function or fix bugs. Compatibility can be affected if an application depended on behavior caused by a bug.

Summary of Changes

Changes for xgmon Release 0.1

The following changes were made for xgmon Release 0.1:

Standardize distribution:	Improved documentation (this manual). Distribute via TOOLSRUN.
Fixes to reported problems:	highlight_dep race condition removed. global variables that obtain information from a topology description are initialized appropriately when there is no active topology description.
Improved/new functions:	allow specification in topology description file of the initial state of a display element. added new state, inactive, for use in describing network elements that are normally powered off. readdir done automatically if an unknown command is referenced. support for specifying many options through .Xdefaults much better interaction with the window manager. automatic placement of windows now possible. more colors available in the draw_line intrinsic. the snmp set statement is now fully implemented. added new states stopping and halting. halt command now works even if machine is performing I/O. new intrinsic functions font_height and font_width. special labeled icons for xgmon windows.

Changes for xgmon Release 0.2

The following changes were made for xgmon Release 0.2:

Improved/new functions:

graphics in virtual G machine windows now saved. improved I/O to virtual G machine windows by buffering and doing block writes instead processing each character individually. new intrinsic function real_type. the send statement now compiles into code which avoids loss of data because of contention for CPU time among virtual G machines and the subsequent expiration of the data from the internal database. extensive editing of the manual to improve its appearance, as well as document more features.

Changes for xgmon Release 0.3

The following changes were made for xgmon Release 0.3:

Fixes to reported problems:

display element state cache now cleared when a new topology description is compiled.

Improved/new functions:

all network I/O is now asynchronous! This is the most significant change. network elements with multiple IP addresses assigned to the same physical interfaces are now handled correctly. Thanks to Ross Veach of UIUC for making available a suitably configured router for testing. new intrinsic function raise_window. the asend snmp statement is now supported. the xgmon core now generates "traps" when it changes the coloring of a display element. The trap library command was extended to permit the logging of these state changes, thus making them available to programs external to xgmon. can override the startup file with a command line option (-rc). can specify initial library command to be executed on the command line. This permits G programs to be used in a fashion similar to C programs or shell scripts. new system command, hostdata, to support an auxiliary host name/address file. more editing of the manual to improve its appearance, as well as document more features.

Changes for xgmon Release 0.4

The following changes were made for xgmon Release 0.4:

Fixes to reported problems:

maximum length of display element names was doubled. bug in SNMP parser detected by Lou Steinberg was fixed. Get-response packets with an error status of genErr were not parsed.

Improved/new functions:

new intrinsic function ascii. interface status and address data is propagated to all references, even if the linkage is not explicit. the query system command now accepts any IP address and does the work required to figure out which host it belongs to; previously one had to specify the primary address of the host. the exec intrinsic function was extended to permit the invocation of system commands as well as library commands. dynamic addition of display elements now supported. new system command learn. xgmon core can now automatically create display elements as it learns about SNMP-based hosts. new intrinsic function move_dep. new intrinsic function rename_dep. new intrinsic function group_dep. new intrinsic function get_deps. new intrinsic function dep_info. new intrinsic function new_deps. new intrinsic function make_node. new intrinsic function make_link. hybrid garbage collection now supported. new system command reuse. new intrinsic function reuse_mem. new global variable selected_x. new global variable selected_y. new global variable selected_window. topology display can now lag behind in real-time, thus hiding transient failures. new system command delay.

Changes for xgmon Release 0.5

The following changes were made for xgmon Release 0.5:

Fixes to reported problems:

fixed bug in calculation of time when next virtual G machine would wake up. The xgmon core did not handle the case when the machine woke up and went to sleep immediately, as is frequently the case.

Improved/new functions:

get-next relationships are now stored in the internal database. This results in a reduction in generated network traffic by 50% in most cases (e.g., snmp_p_all). better buffering of X11 requests. virtual G machine graphic windows have been redone. They now have dual modes (text vs. graphic). This restores the performance that was lost in release 0.2 for text-only windows. The only functional difference between text and graphics mode is that a graphics mode window is no longer permitted to scroll. added double-beep mode for alert bell (this is now the default). This avoids exercising server bugs as a result of invoking XChangeKeyboardControl. New options added to the bell library command. comment lines are now permitted in the .xgmonrc file. They are prefaced with the "#" character. comment lines are now permitted in mib_desc. They are prefaced either with the "#" character or a "*" (a gesture for System/370 users). miscellaneous optimizations.