netfmt(1M)
NAME
netfmt − format tracing and logging binary files
SYNOPSIS
/usr/sbin/netfmt -s [−t records] [[−f] file_name]
/usr/sbin/netfmt -p [−c config_file]
/usr/sbin/netfmt [−c config_file] [−F] [−t records] [−v] [−l] [−n]
[−N | [−1 [−L] [−T]]] [[−f] file_name]
DESCRIPTION
netfmt is used to format binary trace and log data gathered from the network tracing and logging facility (see nettl(1M)). 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:
−s Display a summary of the input file. The summary includes the total number of messages, the starting and ending timestamps, the types of messages, and information about the system that the data was collected on. The contents of the input file are not formatted; only a summary is reported.
−t records Specifies the number of records from the tail end of the input 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. The -t option is not allowed when the input file is a FIFO (pipe).
−f file_name Specifies the input file containing the binary log or trace data. file_name may not be the name of a tty device. Other options may impose additional restrictions on the type of the input file allowed. If omitted, data is read from standard input.
−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.
−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/.netfmtrc is read for both logging and tracing filter configuration commands if it exists.
-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/nettlgen.conf and /var/adm/conslog.opts; see nettlgen.conf(4).) The -F option is not allowed when the input file is redirected.
The following options are not supported by all subsystems. If a subsystem does not support an option, that option is ignored during formatting of data from that subsystem. Consult the product documentation of the subsystem for information regarding the support of these options.
-v Enables output of verbose information. This includes additional cause and action text with formatted output. This information describes the possible cause of the message and any actions that may be required by the subsystem.
After the contents of the input file have been formatted a summary of the file is displayed. When this option is used with the -t option, only a summary of the last records is reported. No summary is produced when this option is used in conjunction with the -F option or if formatting is interrupted.
-l (ell) Turn off inverse video highlighting of certain traced fields. Use this flag when sending formatted trace data to a line printer. By default, certain fields in the trace file are highlighted in inverse video when viewing the formatted trace format at a terminal that supports highlighting.
-n Shows port numbers and network addresses(such as IP and x121) as numbers (normally, netfmt interprets numbers and attempts to display them symbolically).
-N Enables “nice” formatting where Ethernet/IEEE802.3, SLIP, IP, ICMP, IGMP, TCP, UDP, and RPC packets are displayed symbolically. All remaining user data is formatted in hexadecimal and ASCII.
-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.
-T Places a time stamp on terse tracing output. Used with the -1 (minus one) option.
-L Prefixes local link address information to terse tracing output. Used with the -1 (minus one) option.
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 subsystem Naming and Filtering are listed in the Subsystem Filtering section below.
The filter configuration file allows specification of two types of information:
• Specify options in order to control how the input data is to be formatted. These options determine what the output looks like and allow a user to select the best format to suit their needs.
• Specify filters in order to precisely tailor what input data is to be discarded and what is to be formatted. Global filters control all subsystems; subsystem filters pertain only to specific subsystems.
A filter is compared against values in the input data. If the data matches a filter, the data is formatted; otherwise, the input data is discarded. A filter can also specify NOT by using ! before the filter value in the configuration file. If the input data matches a NOT filter, it 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 values of the input data. Specifying !* as the filter means NOT ALL.
Filter Configuration File Syntax
• The formatter ignores white space, such as spaces or tabs. However, newlines (end of line characters) are important, as they terminate comments and filter 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. There are no inline comments allowed.
• 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:
Global filtering commands start with the word formatter, followed by the keywords verbosity, mode, option, or filter.
• formatter verbosity value, value should be either of
high Enables output of netfmt internal debugging information to standard error. Same as the -v option.
low No internal debugging information is to be displayed.
• formatter mode value, value should be one of
raw Dumps out the messages in hex format.
nice Enables "nice" formatting. Same as -N option.
terse Attempts to tersely format each traced packet on a single line. Same as -1 (minus one) option.
normal
Normal formatting.
• formatter option [!] value, value should be
suppress
Normally repeated lines in hex output are condensed into a single line and a message stating that redundant lines have been skipped is displayed. Specifying !suppress will print all redundant data. This is useful when the formatted output is used as input into other commands.
highlight
Normally the formatter will highlight certain fields in its trace output in inverse video. Specifying !highlight will turn this feature off. Same as the (minus ell) option.
• formatter filter type [!] value | *
Six types of filtering are provided:
class log classes
kind trace kinds
id connection, process, path, and user
log instance specific thread of events
subsystem subsystem names
time specify ranges of time(s)
The following combinations are recognized:
formatter filter class value [subsystem]
value indicates the log class. This option allows the user to select one or more classes to be formatted. Initially all log classes are formatted. Only one class is allowed per line. Classes in multiple lines are logically “OR”ed. The optional subsystem name sets the class filter only for the specified subsystem. The log classes are:
INFORMATIVE Describes routine operations and current system values.
WARNING Indicates abnormal events possibly caused by subsystem 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 Device_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. Last-entered value has precedence over any previous ones. See the record header in the formatted output to determine which ID numbers to filter on. The ! operator is not allowed in value.
formatter filter kind value [subsystem]
value can either be an established trace kind or a mask. A mask is a hexadecimal representation of a (set of) trace kind(s). Masks in multiple lines are logically “OR”ed. The optional subsystem name sets the kind filter only for the specified subsystem. Trace kinds and their corresponding masks are:
| Name | Mask | Name | Mask | |
| hdrin | 0x80000000 | state | 0x04000000 | |
| hdrout | 0x40000000 | error | 0x02000000 | |
| pduin | 0x20000000 | logging | 0x01000000 | |
| pduout | 0x10000000 | loopback | 0x00800000 | |
| proc | 0x08000000 |
hdrin Inbound Protocol Header.
hdrout Outbound Protocol Header.
pduin Inbound Protocol Data Unit (including header and data).
pduout Outbound Protocol Data Unit (including header and data).
proc Procedure entry and exit.
state Protocol or connection states.
error Invalid events or condition.
logging Special kind of trace that contains a log message.
loopback Packets whose source and destination system is the same.
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 filter configuration file. The log instance can not be negated with the ! operator.
formatter filter subsystem value
value specifies the subsystem name. Available subsystem names can be listed by using the command:
nettlconf -status
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 (the default), use the * operator. To eliminate all subsystems, use the !* operator.
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 time_of_day and optionally 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, 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 1993 as 93. day_of_year is an optional field; the current date is used as a default.
The time_from specification includes only those records starting from 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.
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. Their behavior varies among individual subsystems. Subsystem filters are valid only when the corresponding subsystems have been installed and configured on the system. See the subsystem documentation for a description of supported subsystem filters and their behavior.
Subsystem filtering commands start with the name of the subsystem followed by the subsystem filter keywords. However, to provide convenience and backwards compatibility, several other filter keywords are provided for the group of LAN subsystems: NAME and FILTER. Currently, four types of subsystem filters are provided: LAN, X25, STREAMS, and OTS. The collection of LAN subsystems use the subsystem filters identified by the FILTER and NAME keywords and the collection of OTS subsystems use the subsystem filters with the OTS keyword. The collection of X25 subsystems start their filter commands with the X25 subsystem names.
LAN Naming and Filtering
LAN naming can be used to symbolically represent numbers with more recognizable labels.
name nodename value
nodename is a character string to be displayed in place of all occurrences of value. value is a (IEEE802.3/Ethernet) hardware address consisting of 6 bytes specified in hexadecimal (without leading "0x"), optionally separated by -. netfmt substitutes all occurrences of value with nodename in the formatted output. The mapping is disabled when the -n option is used. This option applies to tracing output only.
LAN filtering is used to selectively format packets from the input file. 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 | |
| ip_proto | IP protocol number | |
| Layer 4 | tcp_sport | TCP source port |
| tcp_dport | TCP destination port | |
| udp_sport | UDP source port | |
| udp_dport | UDP destination port | |
| connection | a level 4 (TCP, UDP) connection | |
| Layer 5 | rpcprogram | RPC program |
| rpcprocedure | RPC procedure | |
| rpcdirection | RPC call or reply |
Filtering occurs at each of the five 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 5. 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. Filters at each layer are logically “OR”ed. Filters between layers are logically “AND”ed.
LAN trace and log filters use the following format:
filter type [!] value | *
filter is the keyword identifying the filter as a LAN subsystem filter.
The following filters are available for LAN tracing.
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 ip_proto 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 (see protocols(4) for more information on protocol numbers).
filter tcp_dport value
filter tcp_sport value
filter udp_dport value
filter udp_sport value
value is a port number designated 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 rpcprogram value
value is a RPC program name or an integer RPC program number (see rpc(4) for more information on RPC program names). The integer value can be designated by a hexadecimal integer (0xdigits), an octal integer (0digits), or a base-10 integer (0 through 65535).
filter rpcprocedure value
value is an integer RPC procedure number. The integer value can be designated by a hexadecimal integer (0xdigits), an octal integer (0digits), or a base-10 integer (0 through 65535).
filter rpcdirection value
value can be either call or reply.
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).
LAN log filtering command has the following form:
filter subsystem value
value takes the form:
subsys_name event event_list
where subsys_name is a subsystem name obtained using the nettlconf -status command or one of the following abbreviations:
axin bufs caselib caserouter
ip ipc lan loopback
netisr nfs nft ni
nsdiag nse probe pxp
rlbdaemon sockregd strlog tcp
timod tirdwr udp
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 a log event for the subsystem indicated.
range takes the form integer-integer , and indicates an inclusive set of events.
X25 Naming and Filtering
The X25 product provides capabilities to assign symbolic names to important numbers and to filter log events and trace messages. See x25log(1M) and x25trace(1M) for more information about X25 naming and filtering.
OTS 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. Multiple lines are “OR”ed together.
STREAMS Filtering
The STREAMS subsystem filter allows filtering on some fields of the messages logged by STREAMS modules and drivers. See strlog(7) for more information.
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
netfmt only recognizes subsystems and filters from products which have been installed and configured.
WARNINGS
The syntax that was used for the obsolete LAN 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 filtering options merely have the string filter as the first field. It is expected that the older LAN filtering options may change to become more congruent with the global filtering syntax in future releases.
The nettl and netfmt commands read the /etc/nettlgen.conf file each time they are executed. These commands will not operate if the file becomes corrupted (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. Format the last 50 records in file /var/adm/nettl.LOG00 (the default log file):
netfmt -t 50 -f /var/adm/nettl.LOG00
2. Use the follow option to send all log messages to the console (normally, only DISASTER -class log messages are sent to the console in console form):
netfmt -f /var/adm/nettl.LOG00 -F > /dev/console
3. Monitor all log messages in a hpterm window:
hpterm -e /usr/sbin/netfmt -F -f /var/adm/nettl.LOG00
4. Read file /var/adm/trace.TRC1 for binary data and use conf.file as the filter configuration file:
netfmt -c conf.file -f /var/adm/trace.TRC1
The remaining examples show how to specify entries in the filter 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(LAN):
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, local, to the remote node, 192.6.1.3, which reference local TCP service ports login or shell, or remote UDP port 777:
filter ip_saddr local
filter ip_daddr 192.6.1.3
filter tcp_sport login
filter tcp_sport shell
filter udp_dport 777
5. Format a TCP connection from local node node2 to 192.6.1.3 which uses node2 service port ftp and remote port 1198.
filter connection node2:ftp 192.6.1.3:1198
6. Format all packets except those that use interface lan0:
filter interface ! lan0
7. Format all logged events for subsystem ip. No other events are formatted. (By default, all events are formatted):
filter subsystem ip event *
8. 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
9. 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
10. 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:
ots session msgid !*
ots session msgid 9973
ots session msgid 9974
ots transport msgid !9974
11. Combine LAN and general filtering options into one configuration file. Format 15 minutes of pduin and pduout data starting at 3:00 PM on 2 April 1990 for data from lan0 interface.
formatter filter kind 0x30000000
formatter filter time_from 15:00:00 04/02/90
formatter filter time_through 15:15:00 04/02/90
filter interface !*
filter interface lan0
FILES
/etc/nettlgen.conf
default subsystem configuration file
/var/adm/conslog.opts
default console logging options filter file
$HOME/.netfmtrc default filter configuration file if the −c config_file option is not used on the command line.
SEE ALSO
nettl(1M), nettlconf(1M), nettlgen.conf(4), strlog(7).
AUTHOR
netfmt was developed by HP.
Hewlett-Packard Company — HP-UX Release 10.20: July 1996