netfmt(1M)
NAME
netfmt − format tracing and logging binary files.
SYNOPSIS
/etc/netfmt [−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 trace and log information can be read from a file or from standard input. (If standard input is a tty device, then an informative message is given and netfmt quits.) Formatted data is written to standard output. Message inclusion and format can be controlled by a configuration file; if no configuration commands are specified, all messages are fully formatted. The formatting options are specified in an optional configuration file. The description of the configuration file input follows the parameter descriptions.
Parameters
−c config_file Specifies the file containing formatter filter configuration commands. Syntax for the commands is given below. If −c is omitted and the file contains LAN or X.25 trace data and a file, $HOME/.nettr, exists then it is read for configuration commands.
−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 expecially 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 DISASTER class log messages are ALWAYS sent to the console as well as the log file.)
−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. There is no default, records must be specified with the −t option.
−f file_name Specifies the file containing the binary log or trace data. If omitted, data is read from standard input.
The following options are for LAN and X.25 trace formatting to allow backward compatibility with the obsolete nettrfmt command.
−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 all links. 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.
CONFIGURATION FILE
Note: Configuration file syntax converges the syntax permitted with the obsolete network trace formatter command, nettrfmt(1m), and the obsolete network log formatter command, netlogfmt(1m), with the new syntax to control options in the formatter. The first section below describes the general use of the configuration file. Specific options for LAN and X.25 Naming and Filtering are listed in the following section.
Global Filtering
The configuration file allows specification of two types of information. First, the user may specify an IEEE802.3/Ethernet-address-to-node-name mapping which 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 the following section. Secondly, filters can be specified in order to tailor precisely which packets are to be discarded and which are to be formatted. There are two types of filters: global, which are described here; and LAN and X.25 filters, which are described in the following section.
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 will pass all packets of the specified protocol layer. By giving !∗ as the filter, the user is saying “NOT ALL”. This enables the user to indicate not all, then 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.
There are six types of filtering available:
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) for subsystems
time specify ranges of time(s)
LAN and X.25 Naming and Filtering
Note: The filtering described above occurs before the filtering performed by LAN and X.25 filtering described below.
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, then 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.
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" is not distiguished from "ERROR."
− A sharp sign (#) at the beginning of a line indicates a comment. The formatter ignores all characters from the "#" to the end of 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," you should not need 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.
The syntax of the entries in the config_file is given below with corresponding value representation.
# comment Optional
FORMATTER filter type [ ! ] value | *
Type can be one of the following:
| class | Process_ID |
| Connection_ID | subsystem |
| kind | time_from |
| log_instance | time_through |
| Path_ID | User_ID |
Value can take on the following forms, depending on the type specified above:
class 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 which were possibly caused by subsystems problems.
ERROR Signals an event or condition which were 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.
kind Value can either be an established trace kind or a mask. A mask is a hexadecimal representation of a (set of) trace kind(s). The trace kinds and their corresponding masks are:
| Name | Mask |
| error | 0x02000000 |
| hdrin | 0x80000000 |
| hdrout | 0x40000000 |
| logging | 0x01000000 |
| loopback | 0x00800000 |
| pduin | 0x20000000 |
| pduout | 0x10000000 |
| proc | 0x08000000 |
| state | 0x04000000 |
Connection_ID, Process_ID, Path_ID, and User_ID
Value specifies the ID number of the messages to format. Note that you can only specify one id_type per configuration file. Also, you cannot specify the "!" operator in the value.
log_instance
Value specifies the log instance number of the messages to filter. By selecting a log instance, the user can see the messages from a single thread of network events. Only one log instance can be specified per configuration file. The log instance may not be negated with the "!" operator.
subsystem
Value specifies the subsystem name. The subsystem names available to format upon may be found in the nettl(1m) man page, or by listing them using the command:
nettl -status all
No more than one subsystem name may be given per line; multiple lines will "OR" the request. The subsystem name can be turned off with the "!" operator, given all subsystems except the one(s) indicated. Also, all subsystems may be specified by the "*" operator (which is the default), or all subsystems turned off with the "!*" operator. By using combinations of these, it is possible to specify only a few subsystems to format out of a file containing many possible subsystems.
time_from and time_through
Time_from indicates the starting time and time_through indicates the ending time, inclusive. Value consists of two fields: time_of_day and day_of_year. Time_of_day specifies the time on the 24-hour clock in hours, minutes, seconds and decimal parts of a second (resolution is down to microseconds). Hours, minutes and seconds are required; fractional seconds are optional. The format is hh:mm:ss.dddddd. 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, will be excluded from the formatted output. Records with times of 10:08:00.000000 and later will be 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, will be excluded from the formatted output. Day_of_year specifies the day of the year in the form month/day/year. Specify month and day numerically by either one or two digits. For example, you may specify January as 1 or 01, and 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 format is MM/DD/YY. Both time_of_day and day_of_year fields are required.
The following are LAN and X.25 filtering configuration commands.
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 | *
Type can be one of the following:
| connection | source |
| dest | ssap |
| dsap | subsystem |
| interface | tcp_dport |
| ip_daddr | tcp_sport |
| ip_saddr | type |
| pxp_dport | udp_dport |
| pxp_sport | udp_sport |
Value can take the following forms, depending on the Type specified above:
dest or source
Hardware address consisting of 6 bytes specified in hexadecimal (without leading "0x"), optionally separated by "−".
interface
Network interface of the form: lan<n> for LAN interface, or lo<n> for loopback interface, where n is the logical unit number; for example, lan0.
ssap, dsap
A hexadecimal integer of the form: 0xdigit; an octal integer of the form: 0digits; or, a base-ten integer, 0 through 255.
type A hexadecimal integer of the form: 0xdigits; an octal integer of the form: 0digits; or, a base-ten integer, 0 through 65535.
ip_saddr or ip_daddr
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.)
tcp_sport, tcp_dport, udp_sport,
udp_dport, pxp_sport, pxp_dport
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).
connection
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).
subsystem
Value takes the form:
subsys_name event event_list
where subsys_name can be one the following:
| bufs | nft | rlbdaemon |
| ip | nftdaemon | sockregd |
| ipc | nsdiag | tcp |
| lan | probe | udp |
| nfs | pxp | x25 |
Event_list takes the form:
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.
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 for formatting X.25 traces: −1 (one), −N, −n, −T, and −L.
CAVEATS
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 may 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.
DIAGNOSTICS
Messages describe illegal use of netfmt command and unexpected EOF encountered.
EXAMPLES
The following examples show use of the command line options.
1. The following command reads the file /usr/adm/trace_file.TRC1 for the binary data and uses conf.file as the filter configuration file.
netfmt -c conf.file /usr/adm/trace_file.TRC1
2. The following command formats the last 50 records in the file /usr/adm/log.file.LOG00 (the default log file).
netfmt -t 50 /usr/adm/log.file.LOG00
3. The following command uses 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/log.file.LOG00 -F > /dev/console
4. The following command displays all log messages in the hpterm window.
hpterm -e /etc/netfmt -F -f /usr/adm/log.file.LOG00
The following examples show the format of entries in the configuration file specified using the −c option.
1. This sample formatting command file instructs netfmt to format only INFORMATIVE class log messages coming from the ip subsystem that occured from 10:31:53 to 10:41:00 on November 23, 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. Hardware address to name mappings:
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 the 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. The following file combines LAN, X.25, and general filtering options into one configuration file. It formats pduin and pduout data for 15 minutes from 3:00 PM on April 2nd 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_throu 15:15:00 04/02/90
FILES
$HOME/.nettr default configuration file for trace data if no configuration file is given on command line with the −c option.
$HOME/.netlog default configuration file for log data if no configuration file is given on command line with the −c option.
SEE ALSO
nettl(1m), nettlconf(1M), nettlgen(1M)
AUTHOR
netfmt was developed by HP.
Hewlett-Packard Company — HP-UX Release 8.05: June 1991