1 ETHMON

The ETHMON utility monitors an Ethernet network, offering a number of
screen displays of various aspects of Ethernet performance.

Format:

	$ ETHMON


The command ETHMON should be defined first as a foreign command:

	$ ETHMON == "<device><directory>ETHMON"
2 /DUMP

ETHMON/DUMP invokes the data log formatter, rather then the
Ethernet monitor, to format previously-collected data.

Format:

	$ ETHMON/DUMP  file-spec [,file-spec...]
!/dump
3 Parameters
  File-spec

A file containing Ethernet data, produced by ETHMON/DATA_LOG=...

The default file specification is the translation of the logical
name ETHMON_DEFAULT_DATA_LOG (in table LNM$FILE_DEV),
or if that doesn't exist then ETHERNET_SOURCE.DAT.

Wild-cards are allowed.
!/dump
3 Qualifiers
3 /NODES
  /NODES=(option, option...)

Selects various options to do with which Ethernet nodes are
displayed.

The syntax is the same as for ETHMON/NODES.
!end of /dump
2 Qualifiers
2 /BEGINNING
   /BEGINNING=time

Specifies when ETHMON is to begin - it waits till the time arrives.

If playing back recorded data, this specifies that events earlier
than the time be skipped.

E.g.

	/BEGINNING=10:10	wait till fixed time of day
	/BEGINNING="+0:5"	wait 5 minutes
2 /BRIEF
  /BRIEF
  /NOBRIEF  (default)

Specifies whether a brief form of the error and data-source displays
is used.

The brief errors display omits the transmit & receive error descriptions.
The brief data-sources display omits inactive sources.

PF3 toggles between brief and full displays.
2 /BUFFER
  /BUFFER=(option:nn, option:nn...)

Determines various buffer numbers.

E.g.

  /BUFFER=ETHERNET:3
  /BUFFER=(INT:30,READ:4)
3 Ethernet
  /BUFFER=ETHERNET:n

Specifies how many Ethernet read buffers are allocated.
See the "I/O User's Guide", Ethernet section, parameter NMA$C_PCLI_BFN.

In general, never specify more than about 5-10. These buffers come
from a system-wide pool of fixed size (according to the VMS V4.5
driver design) so allocating too many may cause other Ethernet
software to fail.

The default is 3.

For promiscuous mode (/PROMISCUOUS), the maximum is 30,
otherwise the maximum is 10.
3 Internal
  /BUFFER=INTERNAL:n

Specifies how many internal buffers to allocate for holding
Ethernet data pending analysis and/or logging.

The default is 30.

More are allocated if this number is used up.
3 Read
  /BUFFER=READ:n

Specifies how many simultaneous (overlapping) Ethernet reads
($QIOs) there should be.

The default is 5.
2 /CLOGGED
  /CLOGGED=n

Specifies what consitutes clogging of the promiscuous circuit.
If the average number of missed packets per scan interval goes above
this number, the promsicuous circuit is shut down.
This check is not made until the third scan to avoid start-up problems.

The default is 200.
2 /DATA_LOGGING
  /DATA_LOGGING=(name, name, ...)
  /DATA_LOGGING=ALL
  /DATA_LOGGING=*

Specifies that Ethernet data is to be logged to a file.

Each name is in the format node::protocol.
The node name and protocol name can include wildcards ("*" and "%").

The default file specification is the translation of the logical
name ETHMON_DEFAULT_DATA_LOG (in table LNM$FILE_DEV),
or if that doesn't exist then ETHERNET_SOURCE.DAT.

E.g.
	    /DATA_LOG=VAXA::MOP

    logs node VAXA MOP protocol data to a file called VAXA_MOP.DAT,
    or the logical name VAXA_MOP could specify some other file.

	    /DATA_LOG=VAXA::*

    logs all VAXA protocols (into a set of files).

Use /DATA_LOG=ALL or /DATA_LOG=* to log all incoming data.

If ETHMON is installed with PHY_IO privilege, use of data logging
requires BYPASS privilege for security.
2 /DISPLAY
  /DISPLAY
  /NODISPLAY

Determines whether ETHMON produces any displays.

As currently implemented, displays are only available interactively,
so if SYS$INPUT is not a terminal then no displays are produced.

F10 or Ctrl/Z (end-of-file on SYS$INPUT) always terminates ETHMON.

Also available in /NODISPLAY mode if SYS$INPUT is a terminal:

	Ctrl/L (toggle logging, see /DATA_LOGGING)

	Ctrl/N (reset local controller counters)
2 /ENDING
   /ENDING=time

Specifies when ETHMON is to finish.

If playing back recorded data, this specifies that events later
than the time be skipped.

E.g.

	/ENDING=10:10	stop at fixed time of day
	/ENDING="+0:5"	run for 5 minutes
2 /INPUT
  /INPUT=file-spec
  /NOINPUT (default)

Specifies the data recording file to be used for playback input.

The default file-spec is ETHMON_DEFAULT_RECORD_FILE (in logical name
table LNM$FILE_DEV), or if that doesn't exist then ETHERNET_RECORD.DAT.
2 /INTERVAL
  /INTERVAL=n

The number of seconds between statistics & screen update scans.

The default is 4 seconds.

In playback mode, if /PLAYBACK=COMPRESSED is given, this determines
how rapidly the recorded data is scanned.

E.g. if the data was recorded with /INTERVAL=60 and then
played back with /INTERVAL=4, every 4 seconds of real, display time
will show 60 seconds of recorded time.
2 /NODES
  /NODES=(option, option...)

Selects various options to do with which Ethernet nodes are displayed.
3 Cluster
  /NODES=CLUSTER
  /NODES=NOCLUSTER

Specifies whether only local cluster nodes should be displayed
or whether only nodes NOT in the local cluster should be displayed.
3 DECnet
  /NODES=DECNET
  /NODES=NODECNET

Specifies whether only DECnet nodes should be displayed
or whether only non-DECnet nodes should be displayed.

A DECnet node has an Ethernet address which is derived from
its DECnet address.
[See the "VMS Networking Manual" section 3.3.4.2, VMS V5.0.]
3 File
  /NODES=FILE=(file-spec, file-spec, ....)

Specifies one or more files containing lists of nodes & their
Ethernet addresses.

The default file specification is NODES.DAT.

Wild-cards are allowed.

If omitted, ETHMON checks for the logical name ETHMON_NODES (in table
LNM$FILE_DEV) which can point to a site-supplied standard node list.

For further details, see the Node_files subtopic.
3 Known
  /NODES=KNOWN
  /NODES=NOKNOWN

Specifies whether only nodes known to the local DECnet database
(or in /NODES=FILE=... files) be displayed, or whether only
unknown nodes are displayed.
2 /OPTIONS
  /OPTIONS=(option, option, ...)

3 Local_sources
Specifies whether local protocols appear as data sources in the
relevant displays.

The default is to include them.

This is only intended to be used for debugging purposes.
3 MOP_polling
Specifies that nodes should be polled for MOP counters
(i.e. node statistics).

This is the default.

This is only intended to be used for debugging purposes.
3 MOP_multicast
Specifies that a MOP multicast message be sent to try to detect
all nodes capable of sending MOP statistics.

This is the default.

This is only intended to be used for debugging purposes.
3 MOP_restart_fatal
Specifies that if promiscuous mode is shut down upon becoming
clogged, any failure to start a MOP circuit is fatal.

If neither a promiscuous nor a MOP circuit is running then
no information is available about remote nodes but information
about the local node may still be available to ETHMON.
3 Protocols
Specifies whether the local node's protocols should be scanned
for information.

If omitted, the only local protocol known to ETHMON will be its own.
The default is to do the scanning.

This is only intended to be used for debugging purposes.
3 Rx_data
Specifies that ETHMON should collect data on packets received as
well as packets transmitted.

This is only relevant if promiscuous mode is in use.

The default is not to collect these stats.

This is only intended to be used for debugging purposes.
3 Stop_on_fatal
Specifies that ETHMON should stop immediately if the Ethernet
device driver reports a "fatal error".

Such errors are often not literally fatal to the various 
protocols on an Ethernet contrller as they typically restart
after an error.
3 Vm_debug
Specifies that virtual memory debugging activities should occur.

As currently implemented, this invokes LIB$VERIFY_VM_ZONE periodically.

This is only intended to be used for debugging purposes.
2 /OUTPUT
  /OUTPUT=file-spec	(default=ETHMON_SUMMARY.LIS)

Specifies the file to be used for the summary listing (see /SUMMARY).
2 /PLAYBACK
  /PLAYBACK=REALTIME  (default)
  /PLAYBACK=COMPRESSED

Specifies whether ETHMON should play back previously-recorded data.

The recording file is specified with /INPUT.

The default playback mode is to run at the same speed as during
recording (matching second for second).

If /PLAYBACK=COMPRESSED is specified and if playback and recording
have different values of /INTERVAL, then the original rate is adjusted
to match the playback /INTERVAL. See /INTERVAL for more details.
2 /PROMISCUOUS
Specifies whether promiscuous mode is used, so that all traffic
on the Ethernet can be monitored.

Without this mode, ETHMON tries to show as much as it can find out,
which essentially amounts to all the Ethernet controllers' activity
but no information at the protocol level within a node.

It will start a MOP circuit to poll remote nodes for information.
Note that for this to provide useful information it's best to supply
a list of nodes via the /NODES=(FILE=name) qualifier.

Promiscuous mode requires PHY_IO privilege.
2 /RECORD
  /RECORD[=file-spec]
  /NORECORD  (default)

Specifies whether ETHMON should record all activity for later playback.

The default file-spec is ETHMON_DEFAULT_RECORD_FILE (in logical name
table LNM$FILE_DEV), or if that doesn't exist then ETHERNET_RECORD.DAT.

If ETHMON is installed with PHY_IO privilege, Ethernet packet recording
requires BYPASS privilege for security. Without it, only local
protocol and controller counters are recorded.
2 /RELATIVE
  /RELATIVE
  /NORELATIVE  (default)

Specifies whether relative or absolute counters are shown in the
nodes & errors displays.

Absolute counters are the "raw" values as measured from the time
a node's counters were last zeroed. They are often very large numbers
which makes it difficult to see the current activity pattern.

Relative counters are the changes in the raw values between ETHMON
samplings and are much easier to read.

Gold-PF3 toggles between relative & absolute counters.
2 /SUMMARY
  /SUMMARY=(option [,option...])    (default=DATA,ERRORS)
  /NOSUMMARY  (default)

Specifies that a summary report be generated when ETHMON finishes.

Options implemented so far:

	DATA     --  summary of node (controller) data traffic
	ERRORS   --  summary of node (controller) errors
	ALL      --  all reports
2 Node_files
The format of node files.

Each line can include a trailing comment starting with "!".
The text is case-insensitive (it is upper-cased internally).

Note that ETHMON doesn't "understand" (yet) the capabilities
of devices such as DELNIs and DEMPRs - it just accepts
whatever's in the file. For instance it doesn't check that
a DELNI has at most 8 connections.
!node_files
3 Nodes
To define the address of a node:

   NODE  name  address  [alternate-address]

The alternate address can be used for the hardware address of
a node which runs DECnet but this is not used by ETHMON at
the moment.

E.g.

   NODE  VAXA AA-00-04-00-2B-04

   NODE  VAXB AA-00-04-00-2C-04  08-00-08-0E-1C-05
!node_files
3 DELNIs
As DELNIs are effectively (topologically) both repeaters and
segments, declare them thus, using both a REPEATER and a
SEGMENT statement:

   SEGMENT bldg_5 TYPE thick_wire
   ...  (bldg_5 nodes/repeaters)
   REPEATER room_505 TYPE delni
   ...  (more bldg_5 nodes/repeaters)

   SEGMENT room_505 TYPE delni
   NODE r505a ...
   NODE r505b ...
   ...  (other room_505 DELNI nodes)

However if the DELNI is not connected to any thick wire then
there's no need to declare it as a repeater.
!node_files
3 Repeaters
A repeater can be defined thus:

   REPEATER name  [TYPE repeater-type]

Possible repeater types: DELNI, DEREP, DEMPR, DESPR.

E.g.

   SEGMENT  central  TYPE thick_wire
   NODE  cent1  ...
   REPEATER central_derep TYPE derep
   NODE  cent2  ...
   ...
   SEGMENT remote  REPEATER central_derep
   NODE  rem1   ...
   NODE  rem2   ...
   ...
!node_files
3 Segments
Nodes can be grouped into their Ethernet segments.
Define a segment thus:

   SEGMENT name  [TYPE seg-type]  [REPEATER name]

All NODEs following this line up to the next SEGMENT are on
the Ethernet segment.

Possible types: THICK_WIRE, THIN_WIRE.

E.g.

  SEGMENT computer_room TYPE THICK_WIRE

See the Repeaters section for the use of the REPEATER clause.
2 Quotas
ETHMON requires the following resources:

    for each local protocol:		1 ASTLM, 1 TQELM

    for each read buffer (/BUFFER=READ=n): 1 BIOLM, BYTLM

    for its Ethernet circuit:		BYTLM

Various options require extra TQELM and ASTLM.
(E.g. 1 TQELM for /ENDING.)

