 |
» |
|
|
|
NAMEnetfmt — 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] DESCRIPTIONnetfmt
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. Global filtering is done by
netfmt
for
NetTL's
trace/log packets.
A description of the filter configuration file follows the option descriptions. Optionsnetfmt
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, ARP, Probe,
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 FileNote:
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.
The global filtering can start with the word
formatter,
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
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 SyntaxThe 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: For NetTL's SubsystemsThe below explained global filtering options apply only to
NetTL's
subystems.
NetTL's
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
-l
(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 ORed.
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 ORed.
The optional
subsystem
name sets the kind filter only for the specified subsystem.
Trace kinds and their corresponding masks are:
- 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:
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]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 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 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 FilteringNote:
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 FilteringLAN 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: 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 O'ed.
Filters between layers are logically ANDed. 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 connection6 value
value
takes the form:
local_IPv6addr|port remote_IPv6addr|port 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
(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 ip6_daddr value
- filter ip6_saddr value
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). - filter ip_proto value
- filter ip6_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
nsdiag nse probe pxp
rlbdaemon sockregd strlog tcp
timod tirdwr udp nfs 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 FilteringThe 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 FilteringThe
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
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 FilteringThe STREAMS subsystem filter allows filtering on some fields of the messages
logged by STREAMS modules and drivers.
See
strlog(7)
for more information. EXTERNAL INFLUENCESInternational Code Set SupportSingle- and multi-byte character code sets are supported in data.
Single-byte character codesets are supported in filenames. DEPENDENCIESnetfmt
only recognizes subsystems and filters from products which have been
installed and configured. WARNINGSThe 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)). DIAGNOSTICSMessages describe illegal use of
netfmt
command and unexpected
EOF
encountered. EXAMPLESThe first group of examples show how to use command line options.
- 1.
Format the last 50 records in file
/var/adm/nettl.LOG000
(the default log file):
netfmt -t 50 -f /var/adm/nettl.LOG000 - 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.LOG000 -F > /dev/console - 3.
Monitor all log messages in a
hpterm
window:
hpterm -e /usr/sbin/netfmt -F -f /var/adm/nettl.LOG000 - 4.
Read file
/var/adm/trace.TRC000
for binary data and use
conf.file
as the filter configuration file:
netfmt -c conf.file -f /var/adm/trace.TRC000
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:
- 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
IDs
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
AUTHORnetfmt
was developed by HP. 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.
|
Printable version
