hpux netfmt man page on unix.com

netfmt(1M) netfmt(1M)

NAME
netfmt - format tracing and logging binary files

SYNOPSIS
records] file_name]

config_file]

config_file] records]
| file_name]

DESCRIPTION
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
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.

Global filtering is done by for NetTL's trace/log packets. A description of the filter configuration file follows the option descriptions.

Options
recognizes the following command-line options and arguments:

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.

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 option is not allowed when the input file is a FIFO (pipe).

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.

Parse input: this switch allows the user to perform a syntax check on
the config_file specified by the parameter. All other parameters are ignored. If the syntax is correct, terminates
with no output or warnings.

Specifies the file containing formatter filter configuration commands.
Syntax for the commands is given below. When is omitted the file is read for both logging and tracing filter config-
uration commands if it exists.

Follow the input file.
Instead of closing the input file when end of file is encountered, 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 and see nettlgen.conf(4).) The 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 for-
matting of data from that subsystem. Consult the product documentation of the subsystem for information regarding the support of these
options.

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 option, only a summary of the last records is reported. No summary is produced when this option is
used in conjunction with the option or if formatting is interrupted.

(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 format-
ted trace format at a terminal that supports highlighting.

Shows port numbers and network addresses(such as IP and x121) as
numbers (normally, interprets numbers and attempts to display them symbolically).

Enables "nice" formatting where Ethernet/IEEE802.3,
SLIP, IP, ICMP, IGMP, TCP, UDP, ARP, Probe, and RPC packets are displayed symbolically. All remaining user data is
formatted in hexadecimal and ASCII.

(one) Attempts to tersely format each traced packet on a single line. If and/or options are used, the output lines will be
more than 80 characters long.

Places a time stamp on terse tracing output.
Used with the (minus one) option.

Prefixes local link address information to terse tracing output.
Used with the (minus one) option.

Filter Configuration File
Filter configuration file syntax converges the syntax used with the obsolete network trace formatter and network log formatter commands
with new syntax for controlling formatter options. The first section below describes the general use and syntax of the filter configura-
tion file. Specific options for subsystem Naming and Filtering are listed in the section below.

The filter configuration file allows specification of two types of information:

o 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.

o Specify filters in order to precisely tailor what input data is to be discarded and what is to be formatted. control all subsys-
tems; pertain only to specific subsystems. The global filtering can start with the word which means it is global to all the
NetTL's 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 by using before the filter value in the configuration file. If the input data matches a 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 configura-
tion file. "Wild card" filters pass all values of the input data. Specifying as the filter means

Filter Configuration File Syntax
o 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.

o The formatter is not case sensitive. For example and are treated as equivalent.

o 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.

o An exclamation point in front of an argument indicates This operator is not supported for timestamp, log instance, and ID filter-
ing.

o The asterisk when used as an argument, indicates Since the default for all formatting options is it is unnecessary to use the
asterisk alone. It can be used along with the exclamation point, to indicate This operator is not available for timestamp, log
instance, and ID filtering.
The below explained global filtering options apply only to subystems. global filtering commands start with the word followed by the key-
words or

value should be either of

Enables output of netfmt internal debugging information to standard error.
Same as the option.

No internal debugging information is to be displayed.

value should be one of

Dumps out the messages in hex format.

Enables "nice" formatting.
Same as option.

Attempts to tersely format each traced packet on a single line.
Same as (minus one) option.

Normal formatting.

value should be

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 will print all
redundant data. This is useful when the formatted output is used as input into other commands.

Normally the formatter will highlight certain fields in its trace
output in inverse video. Specifying will turn this feature off. Same as the (minus ell) option.

Six types of filtering are provided:

log classes
trace kinds
connection, process, path, and user
specific thread of events
subsystem names
specify ranges of time(s)

The following combinations are recognized:

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 ORed. The
optional subsystem name sets the class filter only for the specified subsystem. The log classes are:

Describes routine operations and current system values.
Indicates abnormal events possibly caused by subsystem problems.
Signals an event or condition which was
affecting the overall subsystem or network operation, but may have caused an application pro-
gram to fail.
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.

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 allowed in
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). Masks in multiple lines are logically ORed. 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

Inbound Protocol Header.
Outbound Protocol Header.
Inbound Protocol Data Unit (including header and data).
Outbound Protocol Data Unit (including header and data).
Procedure entry and exit.
Protocol or connection states.
Invalid events or condition.
Special kind of trace that contains a log message.
Packets whose source and destination system is the same.

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.

value specifies the subsystem name. Available subsystem names can be listed by using the command:

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.

indicates the inclusive starting time.
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 (reso-
lution is to the nearest microsecond). Hours, minutes and seconds are required; fractional seconds are optional.
time_of_day format is dddddd.

day_of_year specifies the day of the year in the form month/day/year in the format: Specify month and day numeri-
cally, using one or two digits. For example, January can be specified as or the third day of the month as or Spec-
ify the year in four digits or by its last two digits. Only years in the ranges 1970-2037 are accepted. Two digit
years in the range 70-99 are interpreted as being in the 20th century(19xx) and those in the range 00-37 are
interpreted as being in the 21st century(20xx) (all ranges inclusive). day_of_year is an optional field; the cur-
rent date is used as a default.

The specification includes those records starting from the resolution of time given. For example, if the
time_of_day for 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 specification includes up to the resolution of time given. For example, if the time_of_day for is
specified as 10:08:00, all records with times after that, from 10:08:00.000001 onward, are excluded from the for-
matted output.

Subsystem Filtering
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 sys-
tem. 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 conve-
nience and backwards compatibility, several other filter keywords are provided for the group of LAN subsystems: 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
and keywords and the collection of OTS subsystems use the subsystem filters with the 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.

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 substitutes all occurrences of
value with nodename in the formatted output. The mapping is disabled when the 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 particu-
lar 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
ip6_saddr IPv6 source address
ip6_daddr IPv6 destination address

ip6_proto IPv6 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
connection6 a level 4 (TCP, UDP) connection for IPv6
-----------------------------------------------------------------------
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 fil-
ter specified, it must match the filter. Filters at each layer are logically O'ed. Filters between layers are logically ANDed.

LAN trace and log filters use the following format:

is the keyword identifying the filter as a
LAN subsystem filter.

The following filters are available for LAN tracing.

value
takes the form:

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 rep-
resents a port and can be designated by a hexadecimal integer an octal integer or base-10 integers (0 through 65535).

value
takes the form:

where local_IPv6addr and remote_IPv6addr can be a hostname or a 16-byte Internet address specified in colon notation (see
inet6(3N) for more information on IPv6 Internet addresses and colon notations). port can be a service name or an integer.
integer represents a port and can be designated by a hexadecimal integer an octal integer or base-10 integers (0 through
65535).

value
is a hardware address consisting of 6 bytes specified in hexadecimal (without leading optionally separated by

value
is a hexadecimal integer of the form: an octal integer of the form: or a base-ten integer, 0 through 255.

value
identifies a network interface and takes the form: for LAN interface, or for loopback interface, where n is the logical unit
number, as in

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).

value
is a hostname or a 16-byte Internet address specified in colon notation (see inet6(3N) for more information on Internet
addresses and colon notations).

value
is a hexadecimal integer of the form: an octal integer of the form: or a base-ten integer, 0 through 255 (see protocols(4) for
more information on protocol numbers).

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 an octal integer or a base-10 integer (0 through 65535).

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 an octal integer or a base-10 integer (0 through 65535).

value
is an integer RPC procedure number. The integer value can be designated by a hexadecimal integer an octal integer or a base-10
integer (0 through 65535).

value
can be either

value
is a hexadecimal integer of the form: an octal integer of the form: or a base-ten integer (0 through 65535).

LAN log filtering command has the following form:

value takes the form:

where subsys_name is a subsystem name obtained using the command or one of the following abbreviations:

event_list takes the form:

where event_spec takes one of the three forms:

integer is an integer in hexadecimal (leading octal (leading or decimal, which specifies a log event for the subsystem indi-
cated.

range takes the form , 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:

Keywords and arguments are interpreted as follows:

Identifies the filter as an
OTS subsystem filter.

subsystem One of the following group of OTS subsystems:

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 infor-
mation. 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 IDs using the operator, then selectively enable the desired message IDs. Only one message_ID is
allowed on each line. Multiple lines are ORed 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
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 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 as the first two fields, while the LAN filtering options merely have the string 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 and commands read the 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 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 (the default log file):

2. Use the follow option to send all log messages to the console (normally, only log messages are sent to the console in console
form):

3. Monitor all log messages in a window:

4. Read file for binary data and use as the filter configuration file:

The remaining examples show how to specify entries in the filter configuration file used with the option.

1. Tell to format only log messages coming from the subsystem between 10:31:53 and 10:41:00 on 23 November 1993.

2. Map hardware address to name(LAN):

3. Format only packets from either of the above hardware addresses:

4. Format all packets transmitted from the local node, to the remote node, which reference local TCP service ports or or remote UDP
port

5. Format a TCP connection from local node to which uses service port and remote port

6. Format all packets except those that use interface

7. Format all logged events for subsystem No other events are formatted. (By default, all events are formatted):

8. Format only event for subsystem Format all events except for subsystem No other events are formatted.

9. Format only events and for subsystem Format all events except events and for subsystem No other events are formatted:

10. Format only those records containing message IDs and for subsystem and those not containing message ID for subsystem All records
from other subsystems are formatted:

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 interface.

AUTHOR
was developed by HP.

FILES
default subsystem configuration file

default console logging options filter file

default filter configuration file if the
option is not used on the command line.

SEE ALSO
nettl(1M), nettlconf(1M), nettlgen.conf(4), strlog(7).

netfmt(1M)

hpux man page for netfmt