HPUX nettl[1m]
nettl(1M) 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.
Hewlett-Packard Company - 1 - HP-UX Release 9.0: August 1992
nettl(1M) nettl(1M)
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.
Hewlett-Packard Company - 2 - HP-UX Release 9.0: August 1992
nettl(1M) nettl(1M)
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:
tab(;); cB cB cw(.4i) cB cB lf4p+1
lf4p+1 c lf4p+1 lf4p+1.
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
Hewlett-Packard Company - 3 - HP-UX Release 9.0: August 1992
nettl(1M) nettl(1M)
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.
Hewlett-Packard Company - 4 - HP-UX Release 9.0: August 1992
nettl(1M) nettl(1M)
-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:
tab(;); cB cB cB lf4p+1 cf4p+1 c .
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.
Hewlett-Packard Company - 5 - HP-UX Release 9.0: August 1992
nettl(1M) nettl(1M)
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
Hewlett-Packard Company - 6 - HP-UX Release 9.0: August 1992
nettl(1M) nettl(1M)
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 ORing 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
Hewlett-Packard Company - 7 - HP-UX Release 9.0: August 1992
nettl(1M) nettl(1M)
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.
SEE ALSO
netfmt(1M), nettlconf(1M), nettlgen.conf(4).
Hewlett-Packard Company - 8 - HP-UX Release 9.0: August 1992