Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > N

netfmt(1M)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

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.

Global filtering is done by netfmt for NetTL's trace/log packets. 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, 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 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. 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 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: For NetTL's Subsystems

The 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:

NameMask NameMask
hdrin0x80000000 state0x04000000
hdrout0x40000000 error0x02000000
pduin0x20000000 logging0x01000000
pduout0x10000000 loopback0x00800000
proc0x08000000   

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]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 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 LayerFilter TypeDescription
Layer 1desthardware destination address
 sourcehardware source address
 interfacesoftware network interface
Layer 2ssapIEEE802.2 source sap
 dsapIEEE802.2 destination sap
 typeEthernet type
Layer 3ip_saddrIP source address
 ip_daddrIP destination address
 ip_protoIP protocol number
 ip6_saddrIPv6 source address
 ip6_daddrIPv6 destination address
 ip6_protoIPv6 protocol number
Layer 4tcp_sportTCP source port
 tcp_dportTCP destination port
 udp_sportUDP source port
 udp_dportUDP destination port
 connectiona level 4 (TCP, UDP) connection
 connection6a level 4 (TCP, UDP) connection for IPv6
Layer 5rpcprogramRPC program
 rpcprocedureRPC procedure
 rpcdirectionRPC 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 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 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 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

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

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

AUTHOR

netfmt 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
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.