netfmt(1M)
NAME
netfmt − format tracing and logging binary files.
SYNOPSIS
/etc/netfmt [-I subsys_file] [-c config_file [-p]] [-F] [-t records] [-v] [-l] [-n] [-N | [-1 [LT]]] [[-f] file_name]
DESCRIPTION
netfmt is used to format binary trace and log data gathered from the tracing and logging facility. The binary trace and log information can be read from a file or from standard input (if standard input is a tty device, an informative message is given and netfmt quits). Formatted data is written to standard output. Formatting options are specified in an optional filter configuration file. Message inclusion and format can be controlled by the filter configuration file. If no configuration commands are specified, all messages are fully formatted. A description of the filter configuration file follows the option descriptions.
Options
netfmt recognizes the following command-line options and arguments:
-I subsys_file Specifies the file containing a description of all subsystems; the option processing and formatting functions to call and the library that contains them. This option may be used to specify an alternate subsystem file configuration file during development of new subsystems and subsystem formatters. If omitted, the default file /etc/conf/nettlgen.conf is read to provide this information.
-c config_file Specifies the file containing formatter filter configuration commands. Syntax for the commands is given below. When -c is omitted the file $HOME/.nettrc (for trace files) or $HOME/.netlogrc (for log files) is read for filter configuration commands if it exists.
-p Parse input: this switch allows the user to perform a syntax check on the config_file specified by the -c parameter. All other parameters are ignored. If the syntax is correct, netfmt terminates with no output or warnings.
-F Follow the input file. Instead of closing the input file when end of file is encountered, netfmt keeps it open and continues to read from it as new data arrives. This is especially useful for watching events occur in real time while troubleshooting a problem. Another use would be for recording events to a console or hard-copy device for auditing. (Note that console logging is controlled by the configuration files /etc/conf/nettlgen.conf and /usr/adm/conslog.opts; see nettlgen.conf(4).)
-t records Specifies the number of records from the tail end of the file to format. This allows the user to bypass extraneous information at the beginning of the file, and get to the most recent information quickly. The maximum number of records that can be specified is 1000. If omitted, all records are formatted.
-f file_name Specifies the file containing the binary log or trace data. If omitted, data is read from standard input.
-v Enables output of netfmt internal debugging information to standard error.
The following options are for LAN and X.25 trace formatting to allow backward compatibility with the obsolete nettrfmt command. These options are ignored for all other subsystems.
-l (ell) Turn off inverse video highlighting of certain traced fields. Use this flag when sending formatted trace data to a line printer. This option is valid for both LAN and X.25 traces. Default: Certain fields in the trace file are highlighted in inverse video when viewing the formatted trace format at a terminal that supports highlighting.
-1 (one) Attempts to tersely format each traced packet on a single line. If -L and/or -T options are used, the output lines will be more than 80 characters long. This option is ignored when formatting X.25 trace data.
-N Enables “nice” formatting where Ethernet/IEEE802.3, SLIP, IP, ICMP, TCP, UDP, PXP, ARP, and Probe packets are displayed symbolically. All remaining user data is formatted in hexadecimal and ASCII. This option is ignored when formatting X.25 trace data.
-n Shows network addresses and ports as numbers (normally, netfmt interprets addresses and attempts to display them symbolically). This option is ignored when formatting X.25 trace data.
-T Places a time stamp on tersely formatted packets. Used with the -1 (minus one) option. This option is ignored when formatting X.25 trace data.
-L Prefixes local link address information to terse tracing output. Used with the -1 (minus one) option. This option is ignored when formatting X.25 trace data.
Filter Configuration File
Note: Filter configuration file syntax converges the syntax used with the obsolete nettrfmt network trace formatter and netlogfmt network log formatter commands with new netfmt syntax for controlling formatter options. The first section below describes the general use and syntax of the filter configuration file. Specific options for LAN and X.25 Naming and Filtering are listed in the Subsystem Filtering section.
The configuration file allows specification of two types of information:
• IEEE802.3 /Ethernet-address to node-name mapping causes netfmt to substitute the specified node name for its address in the output; this is only available on the LAN tracing output as described in later sections.
• Specify filters in order to precisely tailor which packets are to be discarded and which are to be formatted. Global filters control all subsystems; subsystem filters pertain only to specific subsystems.
A filter is compared against values in input packets. If a packet matches a filter, the packet is formatted; otherwise, the packet is discarded. A filter can also specify NOT by using ! before the filter value in the configuration file. If a packet matches a NOT filter, the packet is discarded. A filter can also be a “wild-card” (matching any value) by specifying an asterisk * before the filter value in the configuration file. “Wild card” filters pass all packets of the specified protocol layer. Specifying !* as the filter means NOT ALL. This indicates not all, and is usually followed by specifications to turn on filters for specific messages. This must be used in conjunction with other filters of the same type to actually include something in the formatted output.
Configuration File Syntax
• The host formatter ignores white space, such as spaces or tabs. However, newlines (end of line characters) are important, as they terminate comments and specifications.
• The formatter is not case sensitive. For example error and ERROR are treated as equivalent.
• To place comments in the file, begin each comment line with a # character. The formatter ignores all remaining characters on that line.
• An exclamation point (!) in front of an argument indicates NOT. This operator is not supported for timestamp, log instance, and ID filtering.
• The asterisk (*), when used as an argument, indicates ALL. Since the default for all formatting options is ALL, it is unnecessary to use the asterisk alone. It can be used along with the exclamation point, (!*) to indicate NOT ALL. This operator is not available for timestamp, log instance, and ID filtering.
Global Filtering:
Six types of global filtering are provided:
class log class: Disaster, Error, Warning, Informative
kind trace kind
id connection, process, path, and user
log instance specific thread of events
subsystem see nettl(1M) or use nettl -status all command for a list of subsystems
time specify ranges of time(s)
config_file entry syntax: Global filtering specifications are indicated by the words formatter filter followed by type and value information in the form:
formatter filter type [!] value | *
The following combinations are recognized:
formatter filter class value
value indicates the log class. Initially all log classes are permitted. However, by turning off all log classes with the !* operator then giving a single class, a specific log class can be formatted.
INFORMATIVE Describes routine operations and current system values.
WARNING Indicates abnormal events possibly caused by subsystems problems.
ERROR Signals an event or condition which was not affecting the overall subsystem or network operation, but may have caused an application program to fail.
DISASTER Signals an event or condition which did affect the overall subsystem or network operation, caused several programs to fail or the entire node to shut down.
formatter filter Connection_ID value
formatter filter Path_ID value
formatter filter Process_ID value
formatter filter User_ID value
value specifies the ID number of the messages to format. Only one id_type is allowed per configuration file. The ! operator is not allowed in value.
formatter filter kind value
value can either be an established trace kind or a mask. A mask is a hexadecimal representation of a (set of) trace kind(s). Trace kinds and their corresponding masks are:
| Name | Mask | Name | Mask | |
| error | 0x02000000 | pduin | 0x20000000 | |
| hdrin | 0x80000000 | pduout | 0x10000000 | |
| hdrout | 0x40000000 | proc | 0x08000000 | |
| logging | 0x01000000 | state | 0x04000000 | |
| loopback | 0x00800000 |
formatter filter log_instance value
value specifies the log instance number of the messages to filter. Selecting a log instance allows the user to see the messages from a single thread of network events. Only one log instance is allowed per configuration file. The log instance cannot be negated with the ! operator.
formatter filter subsystem value
value specifies the subsystem name. Available subsystem names are listed in the nettl(1M) manual entry; they can also be listed by using the command:
nettl -status all
Only one subsystem name is allowed per line; multiple lines OR the request. To eliminate a given subsystem name, use the ! operator, which formats all subsystems except those excluded by the list of negated subsystems. To include all subsystems, use the * operator (the default). To eliminate all subsystems, use the !* operator. Initially all subsystems are enabled for formatting. To format only specific subsystems, turn off all subsystems by using the !* operator, then selectively enable the desired subsystems.
formatter filter time_from value
formatter filter time_through value
time_from indicates the inclusive starting time; time_through indicates the inclusive ending time. value consists of two fields: time_of_day and day_of_year, (usually separated by one or more blanks for readability).
time_of_day specifies the time on the 24-hour clock in hours, minutes, seconds and decimal parts of a second (resolution is to the nearest microsecond). Hours, minutes and seconds are required; fractional seconds are optional. time_of_day format is hh:mm:ss. dddddd.
day_of_year specifies the day of the year in the form month/day/year in the format: mm/dd/yy. Specify month and day numerically numerically, using one or two digits. For example, January can be specified as 1 or 01; the third day of the month as 3 or 03. Specify the year by its last two digits. For example, specify 1985 as 85.
The time_from specification includes only those records after the resolution of time given. For example, if the time_of_day for time_from is specified as 10:08:00, all times before that, from 10:07:59.999999 and earlier, are excluded from the formatted output. Records with times of 10:08:00.000000 and later are included in the formatted output. Similarly, the time_through specification includes only up to the resolution of time given. For example, if the time_of_day for time_through is specified as 10:08:00, all records with times after that, from 10:08:00.000001 onward, are excluded from the formatted output.
The time_of_day and day_of_year fields are both required.
Subsystem Filtering
Note: Global filtering described above takes precedence over individual subsystem tracing and logging filtering described below.
Subsystem filters are provided to allow filtering of data for individual subsystems or groups of subsystems. Currently, two subsystem filters are provided: LAN/X.25 and OTS. The collection of LAN and X.25 subsystems use the subsystem filters identified by the FILTER keyword and the collection of OTS subsystems use the subsystem filters with the OTS keyword.
It is possible for each subsystem configured on the system to have an individual subsystem filter. Such a subsystem filter would have the subsystem name as the keyword and would be configured by the nettlconf command (see nettlconf(1M)). A group of subsystems can share a subsystem filter if the same options processing function and the same subformatter library are configured in the nettlgen.conf file for every subsystem in that group (see nettlgen.conf(4)). This enables groups of subsystems, such as the LAN/X.25 and OTS subsystems, to use the same subsystem filer.
Subsystem filters are valid only when the corresponding subsystems have been installed and configured on the system. The syntax for individual subsystem formatters is given below. LAN and X.25 Naming and Filtering
There are numerous filter types, each associated with a particular protocol layer:
| Filter Layer | Filter Type | Description |
| Layer 1 | dest | hardware destination address |
| source | hardware source address | |
| interface | software network interface | |
| Layer 2 | ssap | IEEE802.2 source sap |
| dsap | IEEE802.2 destination sap | |
| type | Ethernet type | |
| Layer 3 | ip_saddr | IP source address |
| ip_daddr | IP destination address | |
| Layer 4 | tcp_sport | TCP source port |
| tcp_dport | TCP destination port | |
| pxp_sport | PXP source port | |
| pxp_dport | PXP destination port | |
| udp_sport | UDP source port | |
| udp_dport | UDP destination port | |
| connection | a level 4 (TCP, UDP, PXP) connection |
Filtering occurs at each of the four layers. If a packet matches any filter within a layer, it is passed up to the next layer. The packet must pass every layer to pass through the entire filter. Filtering starts with Layer 1 and ends with Layer 4. If no filter is specified for a particular layer, that layer is "open" and all packets pass through. For a packet to make it through a filter layer which has a filter specified, it must match the filter.
config_file entry syntax: LAN and X.25 filtering specifications take two forms:
name nodename value
nodename is a character string. value is a hardware address consisting of 6 bytes specified in hexadecimal (without leading "0x"), optionally separated by -.
filter type [!] value | *
filter is the keyword identifying the filter as a LAN/X.25 subsystem filter. The following combinations are recognized:
filter connection value
value takes the form:
local_addr:port remote_addr:port
where local_addr and remote_addr can be a hostname or a 4-byte Internet address specified in decimal dot notation (see inet(3N) for more information on Internet addresses and decimal dot notations). port can be a service name or an integer. integer represents a port and can be designated by a hexadecimal integer (0xdigits), an octal integer (0digits), or base-10 integers (0 through 65535).
filter dest value
filter source value
value is a hardware address consisting of 6 bytes specified in hexadecimal (without leading 0x), optionally separated by -.
filter dsap value
filter ssap value
value is a hexadecimal integer of the form: 0xdigit; an octal integer of the form: 0digits; or a base-ten integer, 0 through 255.
filter interface value
value identifies a network interface and takes the form: lann for LAN interface, or lon for loopback interface, where n is the logical unit number, as in lan0.
filter ip_daddr value
filter ip_saddr value
value is a hostname or a 4-byte Internet address specified in decimal dot notation (see inet(3N) for more information on Internet addresses and decimal dot notations).
filter pxp_dport value
filter pxp_sport value
filter tpc_dport value
filter tpc_sport value
filter udp_dport value
filter udp_sport value
value is a port number as a 2-byte integer value or a service name. The integer value can be designated by a hexadecimal integer (0xdigits), an octal integer (0digits), or a base-10 integer (0 through 65535).
filter subsystem value
value takes the form:
subsys_name event event_list
where subsys_name can be one of the following:
bufs lan nftdaemon pxp tcp
ip nfs nsdiag rlbdaemon udp
ipc nft probe sockregd x25
event_list takes the form:
event_spec [, event_spec...]
where event_spec takes one of the three forms:
[!] integer [!] range [!] *
integer is an integer in hexadecimal (leading 0x), octal (leading 0), or decimal, which specifies an event for the subsystem indicated.
range takes the form integer-integer , and indicates an inclusive set of events.
filter type value
value is a hexadecimal integer of the form: 0xdigits; an octal integer of the form: 0digits; or a base-ten integer, 0 through 65535.
OTS Naming and Filtering
The OTS subsystem filter allows filtering of the message ID numbers that are typically found in the data portion of an OTS subsystem’s log or trace record. The OTS subsystem filter is effective for any subsystem that is a member of the OTS subsystem group.
OTS trace filtering configuration commands have the following form in config_file:
OTS [subsystem] msgid [!] message_ID | *
Keywords and arguments are interpreted as follows:
OTS Identifies the filter as an OTS subsystem filter.
subsystem One of the following group of OTS subsystems:
OTS ACSE_PRES NETWORK
TRANSPORT SESSION
Note: The absence of subsystem implies that the filter applies to all OTS subsystems.
message_ID is the value of the message ID to filter. A message ID is used by OTS subsystems to identify similar types of information. It can be recognized as a 4 digit number contained in brackets ([ ]) at the beginning of an OTS subsystem’s trace or log record. Initially all Message_IDs are enabled for formatting. To format records with specific Message_IDs, turn off all message ID s using the !* operator, then selectively enable the desired message ID s. Only one Message_ID is allowed on each line.
EXTERNAL INFLUENCES
International Code Set Support
Single- and multi-byte character code sets are supported in data. Single-byte character codesets are supported in filenames.
DEPENDENCIES
X.25
The following options are not recognized when formatting X.25 traces: -1 (one), -N, -n, -T, and -L.
WARNINGS
The syntax that was used for the obsolete LAN and X.25 trace and log options has been mixed with the syntax for the netfmt command such that any old options files can be used without any changes. The combination of syntax introduces some redundancy and possible confusion. The global filtering options have the string formatter filter as the first two fields, while the LAN and X.25 filtering options merely have the string filter as the first field. It is expected that the older LAN and X.25 filtering options may change to become more congruent with the global filtering syntax in future releases.
The nettl and netfmt commands read the /etc/conf/nettlgen.conf file each time they are executed. If the file becomes corrupted, these commands become no longer operational (see nettl(1M) and netfmt(1M)).
DIAGNOSTICS
Messages describe illegal use of netfmt command and unexpected EOF encountered.
EXAMPLES
The first group of examples show how to use command line options.
1. Read file /usr/adm/trace.TRC1 for binary data and use conf.file as the filter configuration file:
netfmt -c conf.file -f /usr/adm/trace.TRC1
2. Format the last 50 records in file /usr/adm/nettl.LOG00 (the default log file):
netfmt -t 50 -f /usr/adm/nettl.LOG00
3. Use the follow option to send all log messages to the console (normally, DISASTER -class log messages are sent to the console in terse form):
netfmt -f /usr/adm/nettl.LOG00 -F > /dev/console
4. Display all log messages in the hpterm window:
hpterm -e /etc/netfmt -F -f /usr/adm/nettl.LOG00
The remaining examples show how to format entries in the configuration file used with the -c option.
1. Tell netfmt to format only INFORMATIVE -class log messages coming from the NS_LS_IP subsystem between 10:31:53 and 10:41:00 on 23 November 1993.
formatter filter time_from 10:31:53 11/23/93
formatter filter time_through 10:41:00 11/23/93
formatter filter class !*
formatter filter class INFORMATIVE
formatter filter subsystem !*
formatter filter subsystem NS_LS_IP
2. Map hardware address to name:
name node1 08-00-09-00-0e-ca
name node3 02-60-8c-01-33-58
3. Format only packets from either of the above hardware addresses:
filter source 08-00-09-00-0e-ca
filter source 02-60-8c-01-33-58
4. Format all packets transmitted from the local node to node1 which reference local TCP service ports login or shell, or remote UDP port 777. The local hostname is local:
filter ip_saddr local
filter ip_daddr node1
filter tcp_sport login
filter tcp_sport shell
filter udp_dport 777
5. Format a TCP connection from local node node2 to node1 which uses node2 service port ftp and remote port 1198.
filter connection node2:ftp node1:1198
6. Format all packets except those that use interface lan0:
filter interface ! lan0
7. Format all events for subsystem ip. No other events are formatted. By default, all events are formatted:
filter subsystem ip event *
8. Format all events for subsystem X25. No other events are formatted:
filter subsystem X25 event *
9. Format only event 5003 for subsystem ip. Format all events except 3000 for subsystem tcp. No other events are formatted.
filter subsystem ip event 5003
filter subsystem tcp event *,!3000
10. Format only events 5003, 5004, 5005, and 5006 for subsystem ip. Format all events except events 3000, 3002, and 3003 for subsystem tcp. No other events are formatted:
filter subsystem ip event 5003-5006
filter subsystem tcp event *,!3000,!3002-3003
11. Format only those records containing message ID s 9973 and 9974 for subsystem session and those not containing message ID 9974 for subsystem transport. All records from other subsystems are formatted:
#-----------------------------------------------------------
# SUBSYSTEM REQUEST_TYPE ARGUMENT1 ARGUMENT2 ...
#-----------------------------------------------------------
ots session msgid !*
ots session msgid 9973
ots session msgid 9974
ots transport msgid !9974
12. Combine LAN, X.25, and general filtering options into one configuration file. Format pduin and pduout data for 15 minutes starting at 3:00 PM on 2 April 1990 for data from the lan0 interface only.
formatter filter kind 0x30000000
filter interface ! *
filter interface lan0
formatter filter time_from 15:00:00 04/02/90
formatter filter time_through 15:15:00 04/02/90
FILES
/etc/conf/nettlgen
default subsystem configuration file
/usr/adm/conslog.opts
default console logging options filter file
$HOME/.nettrc default configuration file for trace data if the -cconfig_file option is not used on the command line.
$HOME/.netlogrc default configuration file for log data if the -cconfig_file option is not used on the command line.
SEE ALSO
nettl(1M), nettlconf(1M), nettlgen.conf(4).
AUTHOR
netfmt was developed by HP.
Hewlett-Packard Company — HP-UX Release 9.0: August 1992