nettl(1M)

NAME

nettl − control network tracing and logging

SYNOPSIS

/etc/nettl -start
/etc/nettl -stop
/etc/nettl -status [info]
/etc/nettl -traceon kind [kind...] -entity subsystem [subsystem...] [-file name] [-card dev_name] [-size limit] [-tracemax maxsize] [-m bytes]
/etc/nettl -traceoff -entity subsystem [subsystem...]
/etc/nettl -log class -entity subsystem [subsystem...]
/etc/nettl -firmlog 0|1|2 -card dev_name

DESCRIPTION

nettl is a tool used to capture network events or packets. Logging is a means of capturing network activities such as state changes, errors, and connection establishment. Tracing is used to capture or take a snapshot of inbound and outbound packets going though the network, as well as loopback or header information. A subsystem is a particular network module that can be acted upon such as NS_LS_DRIVER, or X25L2. nettl is used to control the network tracing and logging facility. The command can be used in seven different forms as indicated above. Command forms are discussed first, then options and parameters. Except for the nettl -status option, nettl can be used only by users who have an effective user ID of 0.

Options

nettl recognizes the following options which can be used only in the combinations indicated above under SYNOPSIS. Options can be specified by spelling out in full or abbreviating as indicated. Argument keywords can be abbreviated as shown. The keywords are case-insensitive.

-start (abbrev: -st) Used alone without other options.

Initializes the tracing and logging facility and starts up default logging. Logging is enabled for all subsystems as determined by the /etc/conf/nettlgen.conf file. Log messages are sent to a log file whose name is determined by adding the suffix .LOG00 to the log file name specified in the /etc/conf/nettlgen.conf configuration file. See nettlconf(1M) and nettlgen.conf(4) for an explanation of the configuration file. If the log file (with suffix) already exists, it is opened in append mode; i.e., new data is added to the file. The name supplied by default is /usr/adm/nettl (thus logging starts to file /usr/adm/nettl.LOG00). See Data File Management below for more information on how the log file is handled.

Note: It is strongly recommended that the tracing and logging facility be started before any other networking. The /etc/nettl -start command should be placed in /etc/netlinkrc before any other networking commands.

-stop (abbrev: -sp) Used alone without other options.

Terminates the trace/log facility. Once this command is issued, the trace/log facility is no longer able to accept the corresponding trace/log calls from the network subsystems.

Note: It is strongly recommended that the tracing and logging facility not be turned off, since information about disasters will be lost. To minimize impact on the system, all subsystems can be set to capture only disaster -class log messages.

-status [info] (abbrev: -ss) Used alone without other options.

Reports tracing and logging facility status. The facility must be operational (i.e. /etc/nettl -start has been completed). The default value is ALL. info defines the type of trace or log information that is to be displayed. info can be one of the following:

log log status information

trace trace status information

all trace & log status information

-traceon kind [kind...]
(abbrev: -tn) Requires -entity option; -card option required for X.25 subsystems only (ignored otherwise); other options recognized but not required.

Starts tracing on the specified subsystem or subsystems. The tracing and logging facility must have been initialized by nettl -start for this command to have any effect. The default trace file is standard output, but can be overridden by the optional -file argument. If standard output is a tty device, then an informative message is displayed and no trace data is produced.

When tracing is enabled, every operation through the subsystems are recorded if the kind mask is matched.

kind defines the trace masks used by the tracing facility before recording a message. kind can be entered as one or several of the following keywords or masks:

keyword	mask	keyword	mask
_	_	_	_
hdrin	0x80000000	state	0x04000000
hdrout	0x40000000	error	0x02000000
pduin	0x20000000	logging	0x01000000
pduout	0x10000000	loopback	0x00800000
proc	0x08000000

For multiple kinds, the masks can be specified separately or combined into a single number. For example, to enable both pduin and pduout (to trace all packets coming into and out of the node) use 0x30000000.

loopback can be enabled by NS subsystems only. An error may be returned if a given subsystem does not support a particular trace kind. If a -traceon is issued on a subsystem already being traced, the tracing mask and optional values are changed to those specified by the new command, but the new -file, -size, -tracemax and -m parameters are ignored and a message is issued.

-entity all

-entity subsystem [subsystem...]
(abbrev: -e) The subsystem parameter limits the action (-status, -traceon, -traceoff, or -log) to the specified (one or more) protocol layers or software modules.

If all is specified, all recognized subsystems are traced except X.25-specific subsystems. To turn on tracing for X.25, use the command

nettl -tn kind -e [x.25_subsys] -c [dev_name]

where the value of [x.25_subsys] is X25L2 or X25L3.

The number and names of subsystems on the system is dependent on the products that have been installed. Use the command nettl -ss all to obtain a full listing of supported subsystems. subsystem examples include:

OSI-examples of subsystems:

    acse_pres       ftam_ftp_gw     ftp_ftam_gw
    asn1            ftam_init       hps
    cm              ftam_resp       mms
    em              ftam_vfs        ula_utils
    ots             network         transport

LAN-examples of subsystems:

    ns_ls_netisr    ns_ls_nfs       ns_ls_nft
    ns_ls_ip        ns_ls_ni        ns_ls_tcp
    ns_ls_ipc       ns_ls_driver    ns_ls_pxp
    ns_ls_udp       ns_ls_loopback ns_ls_x25

Two X.25-specific subsystems are used for tracing only:
X25L2 X25L3

-file name (abbrev: -f) Used with the first -traceon option only.

The first time the -traceon keyword is used, it initializes tracing, creating a file name.TRC0 which receives the binary tracing data. If a trace file of the name name.TRC0 already exists the binary trace data is appended to the end of the file.

To start a fresh trace file, first turn off tracing then turn it back on again using a different name (see Data File Management below for more information on file naming).

If -file is omitted, binary trace output goes to standard output. If standard output is a tty device an error message is issued and no tracing is generated.

-card dev_name (abbrev: -c) This parameter applies to X.25 subsystems only, for setting up tracing. For other subsystems, this option is ignored and a warning message is issued. Only one X.25 card can be traced at a time.

dev_name specifies a device which corresponds to a network interface card that has been installed and configured. If dev_name is not an absolute path name, then /dev/ is attached in front of dev_name. This forms the device file name /dev/dev_name. dev_name must refer to a valid X.25 network device file.

-size limit (abbrev: -s) Used with first -traceon option only.

Sets trace buffer size (in Kbytes) used to hold trace messages until they are written to the file. Default value for this buffer is 32 Kbytes. The possible range for this parameter is 1 through 512 Kbytes. Setting this value too low increases the possibility of dropped trace messages from kernel subsystems.

-tracemax maxsize (abbrev: -tm) Used with first -traceon option only.

Tracing uses a circular file method such that when one file fills up, a second is used. Two trace files can exist on a system at any given time. See Data File Management below for more information on file behavior.

maxsize specifies the maximum size of both trace files combined. Specify maxsize in multiples of 1 Kbyte. If this option is not specified, a default size of 1 Mbytes is used. maxsize can range in value from 100 through 99999 Kbytes.

-m bytes Used with the first -traceon option only. Number of bytes to trace. This option allows the user to specify the number of bytes to be captured in the trace packet. The user may prefer not to capture an entire PDU trace, such as when interested only in the header. bytes is the number of bytes traced. Default: the entire packet is traced. This option is currently recognized for tracing by the following subsystems only:

ns_ls_driver ns_ls_ni
x25l2 x25l3

-traceoff (abbrev: -tf) Requires -entity option.

Disables tracing of subsystems specified by the -entity option. If ALL is specified as an argument to the -entity option, all tracing is disabled. The trace file remains, and can be formatted by using the netfmt command to view the trace messages it contains (see netfmt(1M)).

-log class (abbrev: -l) Requires -entity option.

Controls the class of log messages that are enabled for the subsystems specified by the -entity option.

class specifies the logging class. Available classes are:

Full	Abbrev	Mask
informative	i	1
warning	w	2
error	e	4
disaster	d	8

Classes can be specified as keywords or as a numeric mask depicting which classes to log. If you choose to indicate several classes at once, be sure to separate each log class with a space.

disaster logging is always on. The default logging classes for each subsystem can be configured into a configuration file, /etc/conf/nettlgen.conf. When the tracing/logging facility is started, the information in the configuration file is read and subsystems are enabled for logging with the specified classes. To change the log class, use the nettl -log class -entity subsystem command with a new log class value. The nettl -log class -entity subsystem command can be run for different log classes and different entities if desired.

-firmlog 0|1|2 (abbrev: -fm) Requires -card option. S800, X.25 only.

Sets the X.25/800 interface card logging mask to level 0, 1, or 2. The default level is 0. The X.25/800 interface logs a standard set of messages. A level of 1 specifies cautionary messages as well as the default messages. A level of 2, specifies information messages in addition to cautionary and default messages. This option is recognized only by the NS_LS_X25 subsystem.

Data File Management

Data files created by the tracing and logging facility require special handling by the facility that the user must be aware of. When files are created, they have the suffix .LOG00 or .TRC0 appended to them, depending on whether they are log or trace files, respectively. This facility is used to keep the files distinct for cases where the user specifies the same name in both places. Also, the files implement a type of circular buffer, with new data always going into the file appended with .LOG00 or .TRC0. When the files are full, they are renamed to the next higher number in their sequence; i.e., .LOG01 or .TRC1 and new files with the 0 extension are created. Currently only two generations of files are possible; thus only two log files appear on the system simultaneously (.LOG00 and .LOG01.) The same is true for trace files as well; only two trace files exist with the same file name, not counting the postfix of .TRC0 and .TRC1.

Note: The file name prefix specified by the user must not exceed eight characters so that the file name plus suffix does not exceed fourteen characters. Longer names are truncated silently. To see the actual name of the trace or log file, use the /etc/nettl -status all command.

Console Logging

Console logging is controlled by the configuration information in the /etc/conf/nettlgen.conf and /usr/adm/conslog.opts files by default. All log messages written to the console as a result of this configuration information are in a special short form. If more information is desired on the console, the netfmt formatter can be used to direct output to the console device. This may be most useful in an X windows environment. See examples below on how to do this.

EXTERNAL INFLUENCES

International Code Set Support

Single- and multi-byte character code sets are supported in data; single-byte character code sets are supported in filenames.

EXAMPLES

1. Initialize the tracing/logging facility:

nettl -start

2. Change log class to warning for all the subsystems. disaster logging is always on for all subsystems.

nettl -log w -e all

3. Turn on inbound PDU tracing for the subsystems ula_utils, hps (all trace kinds are enabled by OR ing the masks) and send binary trace messages to file /usr/adm/trace.TRC0.

nettl -traceon pduin -entity ula_utils hps -file /usr/adm/trace

4. Turn on outbound PDU tracing for X.25 level two, and subsystem NI. Trace messages go to the trace file set up in the previous example. This example also uses the abbreviated options. Tracing for X.25 requires a -card parameter to indicate which X.25 card to trace. If you choose not to trace X.25 by omitting X25L2, the card parameter is ignored.

nettl -tn pduout -e X25L2 ns_ls_ni -c x25_0

5. Determine status of tracing from example 3.

nettl -status trace

The resulting information should resemble the following:

Tracing Information:
Trace Filename:           /usr/adm/trace.TRCx
User’s ID:           0    Buffer Size:            32768
Messages Dropped:    0    Messages Queued:        0
Subsystem Name:           Trace Mask:
ULA_UTILS                     20000000
HPS                           20000000
X25L2                         1000000
NS_LS_NI                      1000000

6. Enable pdu tracing for lan subsystems. Binary trace data goes to file /usr/adm/LAN.TRC0.

The -file option of this command is only valid the first time tracing is called. To change the trace output file, stop tracing and start up again. The trace file is not automatically reset with the -file option. This example assumes that the -traceon option is being used for the first time.

nettl -tn pduin pduout -e ns_ls_driver -file /usr/adm/LAN

7. Terminate the tracing and logging facility.

Note: It is strongly recommended that the tracing and logging facility be turned on before any networking is started and remain on as long as networking is being used.

nettl -stop

WARNINGS

Tracing or logging to a file may not be able to keep up with a busy system, especially when extensive tracing information is being gathered. If some data loss is encountered, the trace buffer size can be increased. Be selective about the number of subsystems being traced, as well as the log class messages being captured.

The nettl and netfmt commands read the /etc/conf/nettlgen.conf file each time they are run (see nettl(1M) and netfmt(1M)). If the file becomes corrupted, these commands will no longer be operational.

FILES

/etc/conf/nettlgen.conf tracing and logging subsystem configuration file.

/usr/adm/conslog.opts default console logging options filter file as specified in /etc/conf/nettlgen.conf.

/usr/adm/nettl.LOG00 default Log file as specified in /etc/conf/nettlgen.conf.

/dev/nettrace kernel trace pseudo-device file.

/dev/netlog kernel log pseudo-device file.

AUTHOR

nettl was developed by HP.

Museum

Related Articles