1 ADD Adds new items to the ETHERMON utility's internal databases. The command format is ADD item-name [additional parameters] where the item-names are specified below. 2 FILTER Adds a new entry to the message filter database. The filter can be initially enabled or disabled, and can specify protocol type, source address, destination address, or a combination thereof for filtering. The command format is ADD FILTER /qualifier [/qualifier...] 3 Command_Qualifiers /DISABLE Specifies that the filter should initially be disabled; it may be enabled later with the SET FILTER command. The default for a new filter definition is enabled. /ENABLE Specifies that the filter should initially be enabled; it may be enabled later with the SET FILTER command. The default for a new filter definition is enabled. /EXCLUDE=(field=value[,field=value]) Specifies that messages that match the specified fields should be filtered out and not used in the analysis. The fields that can be used are: DESTINATION=address PROTOCOL=aa-bb (where aa-bb is the hexadecimal protocol type) SOURCE=address /ONLY=(field=value[,field=value]) Specifies that messages that do not match the specified fields should be filtered out and not used in the analysis. The fields that can be used are: DESTINATION=address PROTOCOL=aa-bb (where aa-bb is the hexadecimal protocol type) SOURCE=address 1 address 2 assignment_conventions The conventions for Ethernet addresses are that the least significant bit of the first byte is clear for a physical address, and set for a multicast address. The first two to four bytes describe a block of addresses allocated to a particular manufacturer, and the remaining bytes make up an individual ID code for a single node. A short, very incomplete list of known physical address ranges are: Digital Equipment Corp.: AA-00-03-00-xx-yy (hardware default for network adapters) AA-00-04-00-xx-yy (DECnet logical addresses) 08-00-2B-xx-yy-zz (initial hardware addresses for LANCE-based interfaces, used for DECservers and DECbridges) Sun Microsystems: 08-00-20-02-xx-yy (hardware default for 386i workstations; last 2 bytes +1 are host ID) 08-00-20-00-xx-yy (hardware default for Ethernet interfaces on other Sun workstations) Xyplex Corp.: 08-00-87-00-xx-yy (Ethernet CC's, HIU's, etc.; yyxx is unit serial #) Ungermann-Bass: 00-DD-00-xx-yy-zz (old-style NET-ONE terminal network controllers, where xxyy is box #, zz is board #) 00-DD-01-xx-yy-zz (new terminal network boxes, xxyyzz is 24-bit box #) 00-DD-0F-xx-yy-zz (Token Ring terminal network boxes, xxyyzz is box #) CMC: 02-CF-1F-04-xx-yy (UNIBUS Ethernet interfaces) 02-CF-1F-09-xx-yy (UNIBUS Ethernet interfaces) 02-CF-1F-70-xx-yy (MULTIBUS II Ethernet interfaces) 2 formats Addresses on the Ethernet can be specified to ETHERMON in four different formats. The standard Xerox physical address display format is the one always used by ETHERMON on output, and may be used for input wherever an Ethernet address is required. It is of the form aa-bb-cc-dd-ee-ff, where each pair of letters is a one- or two-digit hexadecimal number, and the numbers are separated by hyphens. Alternately, Ethernet addresses can be specified as: a) DECnet node number, i.e. area.node, where area is a decimal number in the range 1 to 63 and node is a decimal number in the range 1 to 1023; b) Internet physical address, i.e. a.b.c.d, where each letter is a decimal number in the range 0 to 255, and the total address must correspond to an entry in the address table; c) DECnet node name, i.e. a 1- to 6-character alphanumeric string (starting with a letter) which must match the DECnet name of an entry in the address table. 1 CLEAR Removes item definitions from the ETHERMON utility's internal databases. The command format is CLEAR item-name [additional parameters] where the item-names are specified below. 2 FILTER Removes entries from the Ethernet message filter database, or clears the entire filter list (/ALL). If only a single filter is to be removed, the number of the desired filter must be specified. The command format is CLEAR FILTER filter-number or CLEAR FILTER/ALL 1 DISPLAY Generates a dynamically updating status display, similar to the VMS MONITOR utility. The display updates continuously at the specified update interval (see SET INTERVAL for more details) until any key is struck on the user terminal; at this time, the display will terminate and control will return to the ETHERMON prompt. The command format is DISPLAY displaytype where displaytype is one of the types specified below. 2 DESTINATIONS Displays the top (up to 15) destination addresses being specified in the Ethernet traffic. For addresses with known meanings, their symbolic names will also be displayed. 2 PROTOCOLS Displays the top (up to 8) protocol types being specified in the Ethernet traffic. For protocol types with known functions, their symbolic names will also be displayed. 2 SIZES Displays the size distribution of messages being transferred on the Ethernet for message size groupings from 1-100 to 1401-1500 bytes. 2 SOURCES Displays the top (up to 15) source addresses being specified in the Ethernet traffic. For addresses with known meanings, their symbolic names will also be displayed. 2 STATISTICS Displays the current counter statistics from the Ethernet port (averages, minimums, and maximums not yet implemented). 1 Ethernet_port When the ETHERMON program is started, it must be informed as to what VAX/VMS device it will use as its interface to the Ethernet. Any DEC standard Ethernet port (DEUNA, DEQNA, DEBNT, etc.) may be specified by its VMS device name as a command line parameter at DCL level; if the name is not specified (or ETHERMON is not invoked as a foreign command), Ethermon will prompt for the device name. The unit number is not required, as it will be discarded anyway. Note that the user must have PHY_IO and NETMBX (or SETPRV) privileges to run this utility. 1 EXIT Terminates the ETHERMON utility and returns control to the command interpreter. Control-Z may also be used for this purpose. 1 HELP The ETHERMON utility provides the ability to dynamically monitor the state of an Ethernet network connected to a VAX system. It can generate dynamic displays of the current state of the cable, or can record events occurring on the cable for analysis by another program. For more information on any command, type HELP command [/qualifiers] [parameters] at the ETHERMON prompt. 1 LOAD Loads files of equivalence name definitions into the address, filter, or protocol name tables. The command format is: LOAD [/tabletype] [loadfilespec] 2 loadfilespec The name of the data file to be loaded into the ETHERMON run-time database. If the file specification is missing or incomplete, the specification SYS$DISK:[]ETHERMON.ETH_tabletype is used to supply missing components. The format of the files is that used by the SAVE command. 2 tabletypes /ADDRESSES Specifies that the file should be merged into the addresses table; this is the default if no table type is specified. /FILTERS Specifies that the file should be appended to the filters table; note that all filters loaded from a file are initially disabled, and must be enabled with the SET FILTER command to be used. /PROTOCOLS Specifies that the file should be merged into the protocols table. 1 MONITOR Generates a dynamically updating status display, similar to the VMS MONITOR utility. The display updates continuously at the specified update interval (see SET INTERVAL for more details) until any key is struck on the user terminal; at this time, the display will terminate and control will return to the ETHERMON prompt. The command format is MONITOR displaytype This command is a synonym for the DISPLAY command; use HELP DISPLAY for more information. 1 SAVE Saves files of equivalence name definitions from the address, filter, or protocol name tables. The command format is: SAVE [/tabletype] [savefilespec] 2 savefilespec The name of the data file to be written from the ETHERMON run-time database. If the file specification is missing or incomplete, the specification SYS$DISK:[]tabletype.ETH is used to supply missing components. The output files are ASCII data, in a format suitable for use by the LOAD command; the files may be edited, but the format should remain the same to ensure that the LOAD command works. 2 tabletypes /ADDRESSES Specifies that the addresses table should be saved; this is the default if no table type is specified. /FILTERS Specifies that the filters table should be saved. /PROTOCOLS Specifies that the protocols table should be saved. 1 SET Modifies the attributes of internal data items in the ETHERMON utility. The command format is SET item-name value or SET item-name /qualifier where the item-names are specified below. 2 ADDRESS_NAME Adds new entries or modifies existing ones in the Ethernet address/ node name table. An Ethernet address (physical or multicast) may be entered with an arbitrary text string (if the string contains blanks, lowercase letters, or punctuation marks, it should be enclosed in double quotes {"}). Note that, when enabled, additional address names may be entered automatically as ETHERMON analyzes received Internet ARP messages and similar node identification messages. The command format is SET ADDRESS_NAME physical_etheraddr name_symbol or SET ADDRESS_NAME physical_etheraddr"quoted string" or SET ADDRESS_NAME /[NO]AUTOMATIC 3 physical_etheraddr A standard 48-bit Ethernet address in Xerox standard display format, i.e., of six 1- or 2-digit hexadecimal numbers, low byte first, with the bytes separated by hyphens. For example: 12-34-56-87-AB-DD. 3 name_symbol A name of up to 23 characters, containing only letters, numbers, dollar sign ($), and/or underscore (_). For example: VAX_10. 3 quoted_string A string of text, begun and ended with double quote marks ("); the quote marks are not included in the string itself, and quote marks may not be used as part of the string. Only the first 23 characters specified will actually be stored. For example: "My MicroVAX on TCP/IP". /AUTOMATIC Specifies that automatic address/name recognition be enabled; /NOAUTOMATIC disables automatic recognition. Initially, automatic recognition is disabled to reduce the quantity of messages being lost due to processing delays (the proportion being lost is displayed in the upper left corner of DISPLAY command screens). To reduce loss-generating overhead, automatic recognition is temporarily disabled (if enabled) while a DISPLAY command is in progress. 2 FILTER Modifies an existing entry in the message filter database. The filter can be enabled or disabled, and can change the protocol type, source address, destination address, or a combination thereof for filtering. The command format is SET FILTER filter_num/qualifier [/qualifier...] or SET FILTER/SIZE=(sizeoption[,sizeoption...]) 3 filter_num The identification number the filter was assigned when it was created with the ADD FILTER command. 3 Command_Qualifiers /DISABLE Specifies that the filter should be disabled; it may be enabled later with the SET FILTER/ENABLE command. The default for a new filter definition is enabled. /ENABLE Specifies that the filter should be enabled; it may be disabled later with the SET FILTER/DISABLE command. The default for a new filter definition is enabled. /EXCLUDE=(field=value[,field=value]) Specifies that messages that match the specified fields should be filtered out and not used in the analysis. Any existing EXCLUDE's that are not specified here will not be changed. The fields that can be used are: DESTINATION=address PROTOCOL=aa-bb (where aa-bb is the hexadecimal protocol type) SOURCE=address /NODESTINATION Clears any previously defined destination address filtering for the filter (whether it was EXCLUDE or ONLY filtering). /NOPROTOCOL Clears any previously defined protocol type filtering for the filter (whether it was EXCLUDE or ONLY filtering). /NOSOURCE Clears any previously defined source address filtering for the filter (whether it was EXCLUDE or ONLY filtering). /ONLY=(field=value[,field=value]) Specifies that messages that do not match the specified fields should be filtered out and not used in the analysis. Any existing ONLY's that are not specified here will not be changed. The fields that can be used are: DESTINATION=address PROTOCOL=aa-bb (where aa-bb is the hexadecimal protocol type) SOURCE=address /SIZE=(sizeoption[,sizeoption...]) Specifies the new characteristics of the message size filter. The message size filter is independent of the set of message address and protocol filters, and its effects are logically AND'ed with the other enabled filters. The size options are: DISABLE disables use of message size filter ENABLE enables use of message size filter MAXIMUM=number sets new maximum message size (must be in the range 46 to 1500) MINIMUM=number sets new minimum message size (must be in the range 46 to 1500) 2 INTERVAL Sets the update rate for the DISPLAY command. The command value is the number of seconds between updates (initially defaulting to 4 seconds). The value must be in the range of 2 to 60 seconds. The command format is SET INTERVAL number-of-seconds 2 PROTOCOL_NAME Adds new entries or modifies existing ones in the Ethernet protocol type/node name table. An Ethernet protocol type may be entered with an arbitrary text string (if the string contains blanks, lowercase letters, or punctuation marks, it should be enclosed in double quotes {"}). The command format is SET PROTOCOL_NAME ethernet_protocol name_symbol or SET PROTOCOL_NAME ethernet_protocol "quoted string" 3 ethernet_protocol A standard 16-bit Ethernet protocol number of two 1- or 2-digit hexadecimal numbers, low byte first, with the bytes separated by hyphens. For example: 80-5B. 3 name_symbol A name of up to 24 characters, containing only letters, numbers, dollar sign ($), and/or underscore (_). For example: STANFORD. 3 quoted_string A string of text, begun and ended with double quote marks ("); the quote marks are not included in the string itself, and quote marks may not be used as part of the string. Only the first 24 characters specified will actually be stored. For example: "Stanford V Kernel experiment". 1 SHOW Displays status of various internal databases used by the ETHERMON utility. The format of the command is SHOW data-item where data-item is one of the names specified below. 2 ADDRESS_NAMES Displays the Ethernet address and name association table. This table is used to find symbolic meanings of source and destination addresses specified in Ethernet messages. 2 FILTERS Displays the currently defined Ethernet message filters; the filter number (used for SET FILTER and CLEAR FILTER), enable/disable status, and the protocol type/source address/destination address (if used) and associated matching state(s) are displayed for each filter. 2 PORT_STATUS Displays the current status of ETHERMON's connection to the Ethernet interface. 3 Command_qualifiers /ZERO Specifies that, after the port counters are read, they should be zeroed. 2 PROTOCOL_NAMES Displays the Ethernet protocol type and name association table. This table is used to find symbolic meanings of protocol types specified in Ethernet messages. Protocol types specified with a preceding '*' are permanently defined and may not be removed. 1 SUMMARIZE Tallies up the total number of messages found on the network for each address, protocol type, or whatever is being sorted for, over the specified sampling interval. Samples are taken for the interval set by the SET INTERVAL command (unless the /INTERVAL qualifier is used here to override), and then a report is generated, displaying the messages counts and associated identifiers sorted in decreasing message count order. The command format is SUMMARIZE group-type [/qualifier] 2 DESTINATIONS Specifies that the summary should be over destination addresses. 2 INTERNET Specifies that the summary should be over 2nd level protocols used in Internet IP (DOD) [06-00] protocol type messages. 2 PROTOCOLS Specifies that the summary should be over protocol types. 2 SOURCES Specifies that the summary should be over source addresses. 2 Command_qualifiers /INTERVAL=delta-time Specifies the period of time the trace will runs before it stops and the collection file is closed. Days may not be specified; only hours, minutes, seconds, and hundredths of seconds may be specified. 1 TRACE Collects messages received from the Ethernet into a file, as restricted by the currently enabled filter set. The TRACE command runs for the period of time specified by the SET INTERVAL command, unless the /INTERVAL qualifier is specified with a different period. The file can be recorded in either binary or printable ASCII format. The command format is TRACE [/qualifier[/qualifier]] 2 Command_Qualifiers /ASCII Specifies that the output file will be in ASCII format. If not specified, the default is binary format. /BINARY Specifies that the output file will be in binary format. If not specified, the default is binary format. /INTERVAL=delta-time Specifies the period of time the trace will runs before it stops and the collection file is closed. Days may not be specified; only hours, minutes, seconds, and hundredths of seconds may be specified. /OUTPUT=filespec Specifies the name of the output file; if not specified, the filename will be ETHERMON.DAT for binary format, and ETHERMON.LIS for ASCII format. 2 File_formats 3 ASCII The ASCII file contains three lines for each received and filter-passed Ethernet message. The first line contains the VMS timestamp when the message was received, the source and destination addresses in standard ASCII-hexadecimal format, the protocol type (also ASCII-hex), and the message body's length in bytes. The second line is a hexadecimal dump of the first 40 bytes of the received message; the third line is the same 40 bytes dumped in ASCII (with a space before each actual character, such that the ASCII characters line up under their hexadecimal bytes; periods are displayed for unprintable characters). Preceding the dump lines is a single line reporting when the dump began. Following the dump lines are three lines reporting when the dump was completed, and the quantity of data bytes and messages processed from the Ethernet before and after filtering. The file has carriage-return carriage control and variable-length records. 3 Binary The binary file contains one variable-length record per received and filter-passed Ethernet message. A set of structure definitions for various languages are listed below. 4 FORTRAN STRUCTURE /BIN_REC/ INTEGER*4 VMS_DATETIME(2) ! quadword system timestamp BYTE DESTADDR(0:5) ! beginning of XEDRIVER P5 buffer: dest addr BYTE SRCADDR(0:5) ! source Ethernet address UNION MAP BYTE PROTOCOL(0:1) ! Ethernet protocol type END MAP MAP BYTE DSAP ! IEEE 802 destination SAP BYTE SSAP ! IEEE 802 source SAP UNION MAP BYTE CTL(0:1) ! IEEE 802 CTL byte(s) END MAP MAP BYTE ECTL ! IEEE extended 802 CTL byte BYTE PID(0:4) ! IEEE extended 802 Protocol IDentification END MAP END UNION END MAP END UNION ! end of XEDRIVER P5 buffer (20 bytes) INTEGER*2 LENGTH ! length of message body BYTE BODY(1500) ! not all of this array may be sent; only ! part actually used is written to file END STRUCTURE ! /BIN_REC/ 4 MACRO $DEFINI REC $EQU REC$Q_TIME 0 ; VAX/VMS binary timestamp $EQU REC$B_DESTADDR 8 ; 6-byte destination address $EQU REC$B_SRCADDR 14 ; 6-byte source address $EQU REC$B_PROTOCOL 20 ; 2-byte Ethernet protocol type $EQU REC$B_DSAP 20 ; 1-byte IEEE 802 DSAP $EQU REC$B_SSAP 21 ; 1-byte IEEE 802 SSAP $EQU REC$B_CTL 22 ; 1- or 2-byte IEEE 802 CTL field $EQU REC$B_ECTL 22 ; 1-byte IEEE extended 802 CTL field $EQU REC$B_PID 23 ; 5-byte IEEE extended 802 protocol ID $EQU REC$W_LENGTH 28 ; word length of message body $EQU REC$T_BODY 30 ; body of message $EQU REC$K_MAXLEN 1530 ; maximum length of file record $DEFEND REC