nettl(1M) nettl(1M)
NAME [Toc] [Back]
nettl - control network tracing and logging
SYNOPSIS [Toc] [Back]
/usr/sbin/nettl -start
/usr/sbin/nettl -stop
/usr/sbin/nettl -firmlog 0|1|2 -card dev_name ...
/usr/sbin/nettl -log class ... -entity subsystem ...
/usr/sbin/nettl -status [log |trace |all]
/usr/sbin/nettl -traceon kind ... -entity subsystem ...
[-card dev_name ...] [-file tracename] [-m bytes] [-size portsize]
[-tracemax maxsize] [-n num_files] [-mem init_mem [max_mem]]
[-bind cpu_id] [-timer timer_value]
/usr/sbin/nettl -bind cpu_id
/usr/sbin/nettl -timer timer_value
/usr/sbin/nettl -traceoff -entity subsystem ...
DESCRIPTION [Toc] [Back]
The nettl command 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
through 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 SX25L2. nettl is used to control the network
tracing and logging facility.
Except for the -status option, nettl can be used only by users who
have an effective user ID of 0.
Options [Toc] [Back]
nettl recognizes the following options, which can be used only in the
combinations indicated in SYNOPSIS. Some option and argument keywords
can be abbreviated as described below. All keywords are caseinsensitive.
-start (Abbr.: -st)
Used alone without other options.
Initialize the tracing and logging facility, start up
default logging, and optionally start up console
logging. Logging is enabled for all subsystems as
determined by the /etc/nettlgen.conf file. Log
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: Sep 2004
nettl(1M) nettl(1M)
messages are sent to a log file whose name is
determined by adding the suffix .LOG000 to the log file
name specified in the /etc/nettlgen.conf configuration
file. Console logging is started if console logging
has been configured in the /etc/nettlgen.conf 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; that is, new data is added to the file. The
default name is /var/adm/nettl (thus logging starts to
file /var/adm/nettl.LOG000). See Data File Management
below for more information on how the log file is
handled.
A nettl -start command is performed during system
startup if the NETTL variable in the
/etc/rc.config.d/nettl file has a value of 1.
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. Otherwise, information about disasters will be
lost. To minimize the impact on the system, all
subsystems can be set with the -log option to capture
only disaster-class log messages.
-stop (Abbr.: -sp)
Used alone without other options.
Terminate 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: See note for the -start option.
-timer (Abbr.: -t)
Used with first -traceon option or alone after tracing
has been turned on.
Used to set the buffer flush timer. This value can be
set in seconds. Default value is 5 seconds.
timer_value can be in the range of 1 to 10 seconds.
Set the maximum time (in seconds) by which buffers are
flushed to the disk. The trace buffers are written to
the disk when the timer value expires or once the
buffers are filled, whichever occurs earlier. A larger
value is better when the rate of data traced per second
is high (of the order of 100 MBytes per second); while
a lower value would be preferred for tracing at lower
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: Sep 2004
nettl(1M) nettl(1M)
speeds, and when delays in seeing the data in the trace
cannot be tolerated.
-bind (Abbr.: -b)
Used with first -traceon option or alone after tracing
has been turned on.
Used to bind the daemon process which writes the trace
messages to the file, to the processor given by cpu_id.
This helps in improving performance of tracing. It is
recommended that the processor chosen satisfies one or
more of the following conditions:
+ receives interrupts from the disk to which trace
buffers are being written
+ does not receive non-disk interrupts
+ is least loaded (can be found using the top
command).
Note: The bind request is processed only when the
disk-write daemon process is idle. This means that
-bind operation might return successfully while process
is not yet bound to the processor. Hence, check the
Processor ID field in nettl -status TRACE output to
know if the binding request has been serviced. Hence,
it is advisable to use this option with the first
-traceon operation or while tracing activity is
minimal.
-card dev_name ...
(Abbr.: -c)
This option is required by the X.25 subsystems; it is
optional for other subsystems. Some subsystems do not
support this option.
Limit the trace information gathered to only the data
that comes from the specified network interface card.
More than one dev_name can be specified at a time in
order to trace multiple network interfaces.
dev_name specifies a device which corresponds to a
network interface card that has been installed and
configured. It can be either an integer representing
the network interface, or the device file name of the
network interface. Some subsystems do not support both
types of dev_name. For example, the X25 subsystems
require that dev_name be a device file name. The
product documentation for the subsystems should explain
if the -card option is applicable and how to choose an
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: Sep 2004
nettl(1M) nettl(1M)
appropriate dev_name.
If dev_name is not an integer it is assumed to be a
device file name. The path prefix /dev/ will be
attached in front of dev_name if it is not an absolute
path name to form the device file name, /dev/dev_name.
dev_name must refer to a valid network device file.
-entity all
-entity subsystem ...
(Abbr.: -e)
Limit the action of -log, -traceoff, or -traceon to the
specified protocol layers or software modules specified
by subsystem.
The number and names of subsystems on each system are
dependent on the products that have been installed.
Use the command nettlconf -status to obtain a full
listing of supported subsystems and the products that
own them.
Examples of OSI subsystems:
acse_pres ftam_init mms
asn1 ftam_resp network
cm ftam_vfs ots
em ftp_ftam_gw transport
ftam_ftp_gw hps ula_utils
Examples of LAN subsystems:
ns_ls_driver ns_ls_loopback ns_ls_x25
ns_ls_icmp ns_ls_tcp ns_ls_igmp
ns_ls_nfs ns_ls_udp ns_ls_ip
ns_ls_ipv6 ns_ls_icmpv6
Two X.25-specific subsystems are used for tracing only:
SX25L2 SX25L3
-file tracename
(Abbr.: -f)
Used with the first -traceon option only.
The first time the -traceon keyword is used, it
initializes tracing, creating a file tracename.TRC000
which receives the binary tracing data. If a trace
file of the name tracename.TRC000 already exists the
binary trace data is appended to the end of the file.
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: Sep 2004
nettl(1M) nettl(1M)
To start a fresh trace file, first turn off tracing
then turn it back on again using a different tracename.
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 terminal
device, an error message is issued and no tracing is
generated.
-firmlog 0|1|2 (Abbr.: -fm)
Requires the -card option.
HP-UX servers (Series 800) and X.25 only.
Set 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 the cautionary and default messages.
This option is recognized only by the ns_ls_x25
subsystem.
-log class ... (Abbr.: -l)
Requires the -entity option.
Control 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 Abbr. Mask
__________________________
informative i 1
warning w 2
error e 4
disaster d 8
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
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: Sep 2004
nettl(1M) nettl(1M)
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.
Classes can be specified as keywords or as a single
numeric mask depicting which classes to log. The mask
is formed by adding the individual masks of the log
classes. 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 is configured into the
configuration file, /etc/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. If desired, the command can be run
for different log classes and different entities.
-m bytes Specify the number of bytes (bytes) of each trace
record to trace. This option allows you to specify the
number of bytes to be captured in the trace packet.
You may prefer not to capture an entire PDU trace, such
as when you are only interested in the header.
The maximum value for bytes is 2000. By default, the
entire packet is traced. A value of 0 will also cause
the entire packet to be traced. This option currently
applies only to kernel subsystems.
-mem init_mem [max_mem]
Used with the first -traceon option only.
Set the amount of memory (in kilobytes) used to hold
the trace messages until they are written to the file.
init_mem is the memory allocated with the first
-traceon operation. If not specified, the default
value of init_mem is 7% of the free memory avaiable
(can be found using vmstat command) when tracing is
first enabled. The minimum value that can be specified
for init_mem is 8KB and the maximum value is 50% of the
free memory available.
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: Sep 2004
nettl(1M) nettl(1M)
If the memory allocated when tracing is first enabled
proves to be insufficient, that is, when trace buffers
cannot accommodate more messages, additional memory may
be allocated up to a maximum limit given by max_mem.
If not specified, the default value of max_mem is
init_mem itself. Hence, if the volume of trace
messages is high, max_mem must be set in order to avoid
loss of trace messages. The maximum value that can be
specified for max_mem is 70% of free memory available.
The minimum value for max_mem should be greater than or
equal to the init_mem value. Please note that
specifying a max_mem value for -mem option is optional.
Setting these values too low increases the possibility
of dropped messages. See the Trace Memory Management
section below to determine the size of the trace buffer
and for more details.
Note: The default unit for init_mem and max_mem is
Kilobytes. Use m or M suffix to specify the values in
Megabytes. Refer to examples 9 and 10 for the usage.
-size portsize (Abbr.: -s)
Note: This option is being maintained for backward
compatibility and is currently ignored. This option
will be obsoleted in the next major release. Use -mem
option to configure memory used for trace buffers.
Used with first -traceon option only.
Set the size in kilobytes (KB) of the trace buffer used
to hold trace messages until they are written to the
file. The default size for this buffer is 68 KB. The
possible range for portsize is 1 to 1024. Setting this
value too low increases the possibility of dropped
trace messages from fast subsystems.
-status log
-status trace
-status [all] (Abbr.: -ss)
Used alone without other options.
Report the tracing and logging facility status. The
facility must be operational, that is, nettl -start has
been completed. The additional options define the type
of trace or log information that is to be displayed.
The default value is all.
log Log status information
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: Sep 2004
nettl(1M) nettl(1M)
trace Trace status information
all Trace and log status information
-tracemax maxsize
(Abbr.: -tm)
Used with first -traceon option only.
Tracing uses a circular file method such that when one
file fills up, another file is used. The number of
trace files that can exist on a system at any given
time can be specified using the -n option. See Data
File Management below for more information on file
behavior.
maxsize specifies the maximum size in kilobytes (KB) of
any two trace files combined. Therefore, the maximum
size of each trace file will be approximately half of
maxsize kilobytes (KB). The default value for the
combined file sizes is 1000 KB. The possible range for
maxsize is 100 to 99999.
Note: maxsize/2 should be greater than or equal to the
the size of a trace buffer. If this condition is
satisfied, the default value for maxsize is 1000. If
not, the file size will be automatically adjusted to
meet the requirement and nettl -status can be used to
see the actual trace file used. See Trace Memory
Management for more information.
-n num_files Used with first -traceon option only.
Specifies the number of trace files that can exist on a
system at any given time. However, nettl can reduce
the number of trace files depending on the available
disk space. If the option is not specified, the default
value is two trace files.
-traceoff (Abbr.: -tf)
Requires the -entity option.
Disable 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)).
-traceon all
-traceon kind ...
(Abbr.: -tn)
Hewlett-Packard Company - 8 - HP-UX 11i Version 2: Sep 2004
nettl(1M) nettl(1M)
Requires the -entity option. The -card option is
required for X.25 subsystems. Other options are not
required.
Start tracing on the specified 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; it can be
overridden by the -file option. If standard output is
a terminal device, then an informative message is
displayed and no trace data is produced.
When tracing is enabled, every operation through the
subsystems is recorded if the kind mask is matched.
kind defines the trace masks used by the tracing
facility before recording a message. If -traceon all
is specified, all trace masks are enabled. 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
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.
Hewlett-Packard Company - 9 - HP-UX 11i Version 2: Sep 2004
nettl(1M) nettl(1M)
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 either
pduin pduout or 0x10000000 0x20000000 or the
combination 0x30000000.
Not all subsystems support all trace kinds. No error
is returned if a given subsystem does not support a
particular trace kind.
If a -traceon is issued on a subsystem that is already
being traced, the tracing mask and optional values are
changed to those specified by the new command, but the
new -file, -size, and -tracemax options are ignored and
a message is issued.
If -entity all is specified, all recognized subsystems
are traced except X.25-specific subsystems. To turn on
tracing for X.25, use the command
nettl -traceon kind -e x.25_subsys -card dev_name
where the value of x.25_subsys is SX25L2 or SX25L3.
Trace Memory Management [Toc] [Back]
Memory used for tracing is made up of a circular linked list of trace
buffers, each of which holds the trace messages until they are written
to the file. Trace messages are written to a buffer until it is
filled, after which the buffer is written to the file as a whole.
While the buffer is being written to the file, the next buffer in the
list is used to hold the incoming trace messages. If no buffer is
free to hold the incoming trace messages, the messages will be
dropped. Under this condition, additional trace buffers can be
allocated if the max_mem value is specified for -mem option.
To achieve best tracing performance, the tracing algorithm imposes the
following constraints:
a) Since a buffer is written to the file as a whole, the
individual file size should be at least the buffer size.
b) The additional amount of memory that can be allocated under
heavy traffic given by (max_mem - init_mem) should be at least
the buffer size.
where: buffer size = MIN( init_mem/4, 32MB )
Refer to examples 10 and 11 for further details.
Hewlett-Packard Company - 10 - HP-UX 11i Version 2: Sep 2004
nettl(1M) nettl(1M)
Data File Management [Toc] [Back]
Data files created by the tracing and logging facility require special
handling by the facility that you must be aware of. When files are
created, they have the suffix .LOG000 or .TRC000 appended to them,
depending on whether they are log or trace files, respectively. This
scheme is used to keep the files distinct for cases where you specify
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 .LOG000 or .TRC000. When a logname.LOG000 or tracename.TRC000
file is full, each log or trace is renamed to the next higher number
in its sequence; that is, a file with sequence number N is renamed as
a file with sequence number N+1 and a new file named logname.LOG000 or
tracename.TRC000 is created. The number of files that can exist
simultaneously on the system can be specified by the -n option.
Note: The file name prefix (logname or tracename) 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. To see the actual name of the trace or log file,
use the nettl -status all command.
Console Logging [Toc] [Back]
Console logging is used to display significant log events on the
system console. The values in the /etc/nettlgen.conf file determine
if console logging is to be started and the entries in the
/var/adm/conslog.opts file determine what log messages will be
reported to the console. The nettlconf command can be used to
configure and maintain the information in the /etc/nettlgen.conf file
(see nettlconf(1M)). If changes are made to these files, nettl must
be stopped and restarted for the new information to take effect.
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.
Console logging may be disabled if conservation of system resources is
valued more than notification of log events.
EXTERNAL INFLUENCES [Toc] [Back]
International Code Set Support
Single- and multibyte character code sets are supported in data;
single-byte character code sets are supported in file names.
EXAMPLES [Toc] [Back]
1. Initialize the tracing/logging facility:
nettl -start
Hewlett-Packard Company - 11 - HP-UX 11i Version 2: Sep 2004
nettl(1M) nettl(1M)
(See note for the -start option.)
2. Display the status of the tracing/logging facility.
nettl -status all
3. Change log class to error and warning for all the subsystems.
disaster logging is always on for all subsystems.
nettl -log e w -e all
4. Turn on inbound and outbound PDU tracing for the transport and
session (OTS/9000) subsystems and send binary trace messages to
file /var/adm/trace.TRC000.
nettl -traceon pduin pduout -entity transport session \
-file /var/adm/trace
5. Turn on outbound PDU tracing for X.25 level two and subsystems
ns_ls_ipv6 and ns_ls_ip. 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 option to
indicate which X.25 card to trace.
nettl -tn pduout -e SX25L2 ns_ls_ipv6 ns_ls_ip -c x25_0
6. Determine status of tracing from the previous two examples.
nettl -status trace
The output should resemble the following:
Tracing Information:
Trace Filename: /var/adm/trace.TRC*
Trace file size(Kbytes): 1000
Trace memory allocated(KB): 512
Trace memory to be allocated(KB): 0
Messages Dropped: 0
Processor ID: -1
Subsystem Name: Trace Mask: Card:
TRANSPORT 0x30000000
SESSION 0x30000000
NS_LS_IP 0x10000000
NS_LS_IPV6 0x10000000
SX25L2 0x10000000 x25_0
7. Stop tracing for all subsystems.
Hewlett-Packard Company - 12 - HP-UX 11i Version 2: Sep 2004
nettl(1M) nettl(1M)
nettl -traceoff -e all
8. Enable pduin and pduout tracing for ns_ls_driver (LAN driver)
subsystem. Binary trace data goes to file /var/adm/LAN.TRC000.
The -file option of this command is only valid the first time
tracing is called. The trace file is not automatically reset
with the -file option. To change the trace output file, stop
tracing and start up again. This example assumes that the
-traceon option is being used for the first time.
nettl -tn pduin pduout -e ns_ls_driver -file /var/adm/LAN
9. Enable all kinds of tracing for gelan (GELAN driver) with initial
trace memory being 256MB. Binary trace data goes to file
/tmp/gelan.TRC000 and combined file size being 128MB. This
example assumes that the -traceon option is being used for the
first time.
nettl -tn all -e gelan -mem 256M -tm 128M -f /tmp/gelan
10. Enable all kinds of tracing for igelan (IGELAN driver) with
initial trace memory being 128MB and maximum memory that can be
allocated being 512MB. Binary trace data goes to file
/tmp/igelan.TRC000. Also, bind the disk-write process to
processor 1. This example assumes that the -traceon option is
being used for the first time.
nettl -tn all -e gelan -mem 128M 512M -b 1 -f /tmp/gelan
Warning: Trace file size is less than that required by the
tracing framework. Use 'nettl -status TRACE' to see the actual
trace file size that is used.
nettl -ss TRACE
Tracing Information:
Trace Filename: /tmp/gelan.TRC*
Max Trace file size(Kbytes): 65536
Trace memory allocated(KB): 131072
Trace memory to be allocated(KB): 393216
Messages Dropped: 0
Processor ID: -1
Note that the combined trace file size used is 64MB (as buffer
size = 64MB/2).
11. Terminate the tracing and logging facility.
nettl -stop
Hewlett-Packard Company - 13 - HP-UX 11i Version 2: Sep 2004
nettl(1M) nettl(1M)
(See note for the -start option.)
WARNINGS [Toc] [Back]
Although the nettl command allows the specification of all log classes
and all trace kinds for all subsystems, many subsystems do not support
all log classes and all trace kinds. No error or warning will be
issued if a subsystem does not support a log class or trace kind.
Refer to the product documentation of the subsystem for information on
supported log classes and trace kinds.
Tracing to a file that resides on a NFS file system can impact system
performance and result in loss of trace data. It is recommended that
NFS file systems not be used to contain tracing output files.
Tracing 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 kinds of trace data being captured.
The nettl and netfmt commands read the /etc/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 [Toc] [Back]
/dev/netlog Kernel log pseudo-device file.
/dev/nettrace Kernel trace pseudo-device file.
/etc/nettlgen.conf Tracing and logging subsystem
configuration file.
/etc/rc.config.d/nettl Contains variables which control
the behavior of nettl during system
startup.
/var/adm/conslog.opts Default console logging options
filter file as specified in
/etc/nettlgen.conf.
/var/adm/nettl.LOG000 Default log file as specified in
/etc/nettlgen.conf.
AUTHOR [Toc] [Back]
nettl was developed by HP.
SEE ALSO [Toc] [Back]
netfmt(1M), nettlconf(1M), nettlgen.conf(4).
Hewlett-Packard Company - 14 - HP-UX 11i Version 2: Sep 2004 [ Back ] |
