nettl(1M)nettl(1M)NAMEnettl - control network tracing and logging
SYNOPSIS
dev_name...
class... subsystem...
kind... subsystem... dev_name...] tracename] bytes] portsize] maxsize]
num_files] init_mem [max_mem]] cpu_id] timer_value]
cpu_id
timer_value
subsystem...
filter_file
subsystem...
subsystem...
subsystem...
subsystem...
DESCRIPTION
The command is a tool used to capture network events or packets. Log‐
ging 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 net‐
work, as well as loopback or header information. A subsystem is a par‐
ticular network module that can be acted upon, such as or is used to
control the network tracing and logging facility.
Except for the option, can be used only by users who have an effective
user ID of 0.
Options
recognizes the following options, which can be used only in the combi‐
nations indicated in Some option and argument keywords can be abbrevi‐
ated as described below. All keywords are case-insensitive.
Used alone without other options.
Initialize the tracing and logging facility, start up
default logging, and optionally start up console log‐
ging. Logging is enabled for all subsystems as deter‐
mined by the file. Log messages are sent to a log file
whose name is determined by adding the suffix to the log
file name specified in the configuration file. Console
logging is started if console logging has been config‐
ured in the file. See nettlconf(1M) and nettl‐
gen.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 (thus logging starts to
file See below for more information on how the log file
is handled.
A command is performed during system startup if the
variable in the file has a value of
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. Oth‐
erwise, information about disasters will be lost. To
minimize the impact on the system, all subsystems can be
set with the option to capture only log messages.
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 net‐
work subsystems.
See Note for the option.
Used with first
option or as a standalone option after tracing has been
turned on.
Used to set the buffer flush timer; this value is set in
seconds. The default value is 5 seconds. The
timer_value can be in the range of 1 to 10 seconds.
The trace buffers are written to disk when the
timer_value expires or after the buffers are filled,
whichever occurs first. A larger value is better when
the rate of data traced per second is high (in the order
of 100 MB per second). A lower value is preferred when
the rate of data traced per second is low and when
delays in seeing the trace data cannot be tolerated.
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 buf‐
fers are being written
· does not receive non-disk interrupts
· is least loaded (can be found using the command).
The bind request is processed only when the disk-write
daemon process is idle. This means that operation might
return successfully while process is not yet bound to
the processor. Hence, check the field in output to know
if the binding request has been serviced. Hence, it is
advisable to use this option with the first operation or
while tracing activity is minimal.
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 net‐
work interface card that has been installed and config‐
ured. It can be either an integer representing the net‐
work 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 documenta‐
tion for the subsystems should explain if the option is
applicable and how to choose an appropriate dev_name.
If dev_name is not an integer it is assumed to be a
device file name. The path prefix will be attached in
front of dev_name if it is not an absolute path name to
form the device file name, dev_name must refer to a
valid network device file.
Limit the action of
or 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 to obtain a full
listing of supported subsystems and the products
that own them.
Examples of OSI subsystems:
Examples of LAN subsystems:
Two X.25-specific subsystems are used for tracing
only:
Used with the first
option only.
The first time the keyword is used, it initial‐
izes tracing, creating a file which receives the
binary tracing data. If a trace file of the name
already exists the binary trace data is appended
to the end of the file.
To start a fresh trace file, first turn off trac‐
ing then turn it back on again using a different
tracename. See below for more information on
file naming.
If is omitted, binary trace output goes to stan‐
dard output. If standard output is a terminal
device, an error message is issued and no tracing
is generated.
Requires the
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 mes‐
sages. A level of 1 specifies cautionary mes‐
sages 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 subsystem.
Requires the
option.
Control the class of log messages that are
enabled for the subsystems specified by the
option.
class specifies the logging class. Available
classes are:
Full Abbr. Mask
───────────────────────────
informative i 1
warning w 2
error e 4
disaster d 8
Describes routine operations and current
system values.
Indicates abnormal events possibly caused by
subsystem problems.
Signals an event or condition which was
affecting the overall
subsystem or network
operation, but may have
caused an application
program to fail.
Signals an event or condition which
did affect the overall
subsystem or network
operation, caused sev‐
eral programs to fail or
the entire node to shut
down.
Classes can be specified as keywords or as a sin‐
gle 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.
logging is always on. The default logging
classes for each subsystem is configured into the
configuration file, When the tracing/logging
facility is started, the information in the con‐
figuration file is read and subsystems are
enabled for logging with the specified classes.
To change the log class, use the "" command with
a new log class value. If desired, the command
can be run for different log classes and differ‐
ent entities.
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 pre‐
fer 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 subsys‐
tems.
Used with the first
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 operation. If not specified, the
default value of init_mem is 7% of the free mem‐
ory available (can be found using command) when
tracing is first enabled. The minimum value that
can be specified for init_mem is 8 KB and the
maximum value is 50% of the free memory avail‐
able.
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 maxi‐
mum 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
option is optional.
Setting these values too low increases the possi‐
bility of dropped messages. See the section
below to determine the size of the trace buffer
and for more details.
The default unit for init_mem and max_mem is
Kilobytes. Use or suffix to specify the values
in Megabytes. Refer to examples 9 and 10 for the
usage.
This option is being maintained for back‐
ward
compatibility and is currently ignored. This
option will be obsoleted in the next major
release. Use option to configure memory used for
trace buffers.
Used with first option only.
Set the size in kilobytes (KB) of the trace buf‐
fer 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 mes‐
sages from fast subsystems.
Used alone without other
options.
Report the tracing and logging
facility status. The facility must
be operational, that is, has been
completed. The additional options
define the type of trace or log
information that is to be dis‐
played. The default value is
Log status information
Trace status information
Trace and log status informa‐
tion
Used with first
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 option. See
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 max‐
size kilobytes (KB). The default
value for the combined file sizes
is 1000 KB. The possible range for
maxsize is 100 to 99999.
maxsize/2 should be greater than or
equal to the the size of a trace
buffer. If this condition is sat‐
isfied, the default value for max‐
size is 1000. If not, the file
size will be automatically adjusted
to meet the requirement and can be
used to see the actual trace file
used. See for more information.
Used with first
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 speci‐
fied, the default value is two
trace files.
Requires the
option.
Disable tracing of subsystems spec‐
ified by the option. If is speci‐
fied as an argument to the option,
all tracing is disabled. The trace
file remains, and can be formatted
by using the command to view the
trace messages it contains (see
netfmt(1M)).
Requires the
option. The option is
required for X.25 subsys‐
tems. Other options are not
required.
Start tracing on the speci‐
fied subsystems. The trac‐
ing and logging facility
must have been initialized
by for this command to have
any effect. The default
trace file is standard out‐
put; it can be overridden by
the 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 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
Inbound Protocol
Header.
Outbound Protocol
Header.
Inbound Protocol Data
Unit (including header
and data).
Outbound Protocol Data
Unit (including header
and data).
Procedure entry and
exit.
Protocol or connection
states.
Invalid events or con‐
dition.
Special kind of trace
that contains a log
message.
Packets whose source
and destination system
is the same.
For multiple kinds, the
masks can be specified sepa‐
rately or combined into a
single number. For example,
to enable both and (to trace
all packets coming into and
out of the node) use either
or or the combination
Not all subsystems support
all trace kinds. No error
is returned if a given sub‐
system does not support a
particular trace kind.
For example, the following
NS_LS_* subsystems support
only the and trace kinds:
NS_LS_TCP, NS_LS_UDP,
NS_LS_IGMP, NS_LS_ICMP,
NS_LS_IP, NS_LS_IPV6 and
NS_LS_ICMPV6.
If a is issued on a subsys‐
tem that is already being
traced, the tracing mask and
optional values are changed
to those specified by the
new command, but the new and
options are ignored and a
message is issued.
If is specified, all recog‐
nized subsystems are traced
except X.25-specific subsys‐
tems. To turn on tracing
for X.25, use the command
where the value of x.25_sub‐
sys is or
Used as a standalone
option.
This command is used to set
filter expressions for sub‐
systems. The filter expres‐
sions are specified in the
filter configuration file
filter_file. Currently fil‐
ters are supported for the
following subsystems:
GELAN, IGELAN, BTLAN,
INTL100, IETHER, IEXGBE,
IXGBE, ICXGBE, NS_LS_IP,
NS_LS_TCP, NS_LS_UDP,
NS_LS_ICMP and LINKALL.
Note:LINKALL is a new sub‐
system for users to make a
new link-level function
which allows them to capture
all packets passing through
each link-level drivers
(GELAN, IGELAN, BTLAN,
INTL100, IETHER, IEXGBE,
IXGBE, ICXGBE).
The syntax for the filter
configuration file is given
below.
Used as a
standalone
option.
Used to turn on a
filter that has been
set with the option
for the subsystem.
This makes the filter
active. If the
attribute is speci‐
fied then filters are
turned on for all the
subsystems that cur‐
rently support fil‐
ters as listed above.
Used as
a
stand‐
alone
option.
Used to turn
off a filter
that has been
previously
turned on with
the option for
the subsystem.
This makes the
filter inac‐
tive, but it
is still set
to be turned
on in the
future. If
the attribute
is specified
then filters
are removed
for all the
subsystems
that currently
support fil‐
ters as listed
above.
Used
as
a
stand‐
alone
option.
Used to
display
the
filters
and
their
respec‐
tive
states.
If the
filter
is set
or
turned
on for
a sub‐
system,
the
filter
expres‐
sion is
dis‐
played
along
with
the
status
of the
filter.
If no
filter
is set
for a
subsys‐
tem
then
the
corre‐
spond‐
ing
filter
status
is men‐
tioned.
If the
attribute
is
speci‐
fied
then
filter
status
is dis‐
played
for all
the
subsys‐
tems
that
cur‐
rently
support
filters
as
listed
above.
Used
as
a
stand‐
alone
option.
This
option
is
used
to
remove
fil‐
ter
expres‐
sions
for
sub‐
sys‐
tems
that
have
been
set
with
the
com‐
mand.
If
the
attribute
is
spec‐
i‐
fied
then
fil‐
ters
are
removed
for
all
the
sub‐
sys‐
tems
that
cur‐
rently
sup‐
port
fil‐
ters
as
listed
above.
Trace Memory Man‐
agement
Memory used for
tracing is made
up of a circu‐
lar linked list
of trace buf‐
fers, 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 writ‐
ten to the file
as a whole.
While the buf‐
fer is being
written to the
file, the next
buffer in the
list is used to
hold the incom‐
ing trace mes‐
sages. If no
buffer is free
to hold the
incoming trace
messages, the
messages will
be dropped.
Under this con‐
dition, addi‐
tional trace
buffers can be
allocated if
the max_mem
value is speci‐
fied for
option.
To achieve best
tracing perfor‐
mance, the
tracing algo‐
rithm imposes
the following
constraints:
a) Since
a
buf‐
fer
is
writ‐
ten
to
the
file
as a
whole,
the
indi‐
vid‐
ual
file
size
should
be at
least
the
buf‐
fer
size.
b) The
addi‐
tional
amount
of
mem‐
ory
that
can
be
allo‐
cated
under
heavy
traf‐
fic
given
by
(max_mem
-
init_mem)
should
be at
least
the
buf‐
fer
size.
where:
buf‐
fer
size
=
init_mem/4,
32 MB
)
Refer to
examples
10 and
11 for
further
details.
Data File Manage‐
ment
Data files cre‐
ated by the
tracing and
logging facil‐
ity require
special han‐
dling by the
facility that
you must be
aware of. When
files are cre‐
ated, they have
the suffix or
appended to
them, depending
on whether they
are log or
trace files,
respectively.
This scheme is
used to keep
the files dis‐
tinct for cases
where you spec‐
ify the same
name in both
places. Also,
the files
implement a
type of circu‐
lar buffer,
with new data
always going
into the file
appended with
or When a or
file is full,
each log or
trace is
renamed to the
next higher
number in its
sequence; that
is, a file with
sequence number
is renamed as a
file with
sequence number
and a new file
named or is
created. The
number of files
that can exist
simultaneously
on the system
can be speci‐
fied by the
option.
The file
name
prefix
(logname
or tra‐
cename)
speci‐
fied by
the user
must not
exceed
eight
charac‐
ters so
that the
file
name
plus
suffix
does not
exceed
fourteen
charac‐
ters.
Longer
names
are
trun‐
cated.
To see
the
actual
name of
the
trace or
log
file,
use the
command.
Console Logging
Console logging
is used to dis‐
play signifi‐
cant log events
on the system
console. The
values in the
file determine
if console log‐
ging is to be
started and the
entries in the
file determine
what log mes‐
sages will be
reported to the
console. The
command can be
used to config‐
ure and main‐
tain the infor‐
mation in the
file (see net‐
tlconf(1M)).
If changes are
made to these
files, must be
stopped and
restarted for
the new infor‐
mation to take
effect.
All log mes‐
sages written
to the console
as a result of
this configura‐
tion informa‐
tion are in a
special short
form. If more
information is
desired on the
console, the
formatter can
be used to
direct output
to the console
device. This
may be most
useful in an X
windows envi‐
ronment.
Console logging
may be disabled
if conservation
of system
resources is
valued more
than notifica‐
tion of log
events.
Trace Filters
Trace filters
are a filter
criteria
applied on
trace packets
before actually
capturing them.
The filter cri‐
teria is an
expression con‐
sisting of a
combination of
header fields,
(link level,
TCP/IP and so
on) specified
in the filter
configuration
file. Packets
that pass the
filter criteria
are captured;
all other pack‐
ets are dis‐
carded.
Packets to be
captured are
selected
according to
the following
table.
th_flags==?? | captured packets
S S
A A
F (No packet)
P (No packet)
SA S, A, SA
FA FA, A
PA PA, A
FPA FA, PA, A, FPA
SFPA S, A, SA, FA, PA, FPA
Filter Configura‐
tion File
This file is
used to config‐
ure the fil‐
ters. Entries
in the file
have the fol‐
lowing syntax:
subsys‐
tem sub‐
sys‐
tem_name
filter
expres‐
sion
The filter
expression can
be constructed
using operands
and operators.
The supported
filter operands
are:
─────────────────────────────────────────────────────────────────
Operand Description Format/Range
─────────────────────────────────────────────────────────────────
mac_src Source Mac Address Hex Format Eg.0xffffffffffff
─────────────────────────────────────────────────────────────────
mac_dst Destination Mac Address
─────────────────────────────────────────────────────────────────
mac_type Ethernet type Hex Format, Range: 0x05dd to
0xffff
─────────────────────────────────────────────────────────────────
ip_src Source IP Address Dot notation or hostname
─────────────────────────────────────────────────────────────────
ip_dst Destination IP Address
─────────────────────────────────────────────────────────────────
ip_p IP Protocol Octal, Hex or Decimal Format,
Range: 0-255
─────────────────────────────────────────────────────────────────
th_sport TCP source port Octal, Hex or Decimal Format,
Range: 1-65535, service name
(eg, ftp, telnet, etc)
─────────────────────────────────────────────────────────────────
th_dport TCP destination port
─────────────────────────────────────────────────────────────────
th_flags TCP flags Single value or combination
of: S, F, P, R, A, U
─────────────────────────────────────────────────────────────────
uh_sport UDP source port
─────────────────────────────────────────────────────────────────
uh_dport UDP destination port
─────────────────────────────────────────────────────────────────
icmp_type ICMP type Octal, Hex or Decimal Format,
Range: 0-255
─────────────────────────────────────────────────────────────────
icmp_code ICMP code Octal, Hex or Decimal Format,
Range: 0-255
The supported
operators are
and
Note that the
(single equal)
operator is not
supported.
Logical opera‐
tors that are
supported are
and The logical
operators are
used to combine
the individual
filters for a
subsystem.
Not all opera‐
tors are
allowed on all
operands. For
operands and
the supported
operators are
limited to and
All operators
are supported
for the other
operands.
The supported
operands for
the respective
subsystems are:
Subsystem Supported Operands
Link level subsystems All the operands
NS_LS_IP ip_src, ip_dst, ip_proto, icmp_type, icmp_code
NS_LS_TCP th_sport, th_dport, th_flags
NS_LS_UDP uh_sport, uh_dport
NS_LS_ICMP icmp_type, icmp_code
EXTERNAL INFLUENCES
International Code
Set Support
Single and
multibyte char‐
acter code sets
are supported
in data; sin‐
gle-byte char‐
acter code sets
are supported
in file names.
EXAMPLES
1. Initial‐
ize the
trac‐
ing/log‐
ging
facil‐
ity:
(See
note for
the
option.)
2. Display
the sta‐
tus of
the
trac‐
ing/log‐
ging
facil‐
ity.
3. Change
log
class to
and for
all the
subsys‐
tems.
logging
is
always
on for
all sub‐
systems.
4. Turn on
inbound
and out‐
bound
PDU
tracing
for the
and
(OTS/9000)
subsys‐
tems and
send
binary
trace
messages
to file
5. Turn on
outbound
PDU
tracing
for X.25
level
two and
subsys‐
tems and
Trace
messages
go to
the
trace
file set
up in
the pre‐
vious
example.
This
example
also
uses the
abbrevi‐
ated
options.
Tracing
for X.25
requires
a option
to indi‐
cate
which
X.25
card to
trace.
6. Deter‐
mine
status
of trac‐
ing from
the pre‐
vious
two
exam‐
ples.
The out‐
put
should
resemble
the fol‐
lowing:
7. Stop
tracing
for all
subsys‐
tems.
8. Enable
and
tracing
for (LAN
driver)
subsys‐
tem.
Binary
trace
data
goes to
file
The
option
of this
command
is only
valid
the
first
time
tracing
is
called.
The
trace
file is
not
automat‐
ically
reset
with the
option.
To
change
the
trace
output
file,
stop
tracing
and
start up
again.
This
example
assumes
that the
option
is being
used for
the
first
time.
9. Enable
all
kinds of
tracing
for
gelan
(GELAN
driver)
with
initial
trace
memory
being
256 MB.
Binary
trace
data
goes to
file and
combined
file
size
being
128 MB.
This
example
assumes
that the
option
is being
used for
the
first
time.
10. Enable
all
kinds of
tracing
for ige‐
lan
(IGELAN
driver)
with
initial
trace
memory
being
128 MB
and max‐
imum
memory
that can
be allo‐
cated
being
512 MB.
Binary
trace
data
goes to
file
Also,
bind the
disk-
write
process
to pro‐
cessor
1. This
example
assumes
that the
option
is being
used for
the
first
time.
Note
that the
combined
trace
file
size
used is
64 MB
(as buf‐
fer size
= 64
MB/2).
11. Termi‐
nate the
tracing
and log‐
ging
facil‐
ity.
(See
note for
the
option.)
12. Add a
filter
configu‐
ration
file
entry to
capture
packets
that
have the
and
flags
set.
13. Add the
filter
expres‐
sion to
filter
configu‐
ration
file and
set the
filter.
14. Turn the
filter
on for
the
NS_LS_TCP
subsys‐
tem.
15. Turn the
filter
off for
the
NS_LS_TCP
subsys‐
tem.
16. Display
the fil‐
ter for
the
GELAN
subsys‐
tem.
17. Remove
the fil‐
ter for
the
NS_LS_TCP
subsys‐
tem.
18. Enable
differ‐
ent
NS_LS
oper‐
ands, by
combin‐
ing sub‐
systems.
WARNINGS
Although the
command allows
the specifica‐
tion 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 warn‐
ing will be
issued if a
subsystem does
not support a
log class or
trace kind.
Refer to the
product docu‐
mentation 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 sys‐
tem 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, espe‐
cially when
extensive trac‐
ing information
is being gath‐
ered. If some
data loss is
encountered,
the trace buf‐
fer size can be
increased. Be
selective about
the number of
subsystems
being traced,
as well as the
kinds of trace
data being cap‐
tured.
The and com‐
mands read the
file each time
they are run
(see nettl(1M)
and
netfmt(1M)).
If the file
becomes cor‐
rupted, these
commands will
no longer be
operational.
FILES
Kernel log
pseudo-device
file.
Kernel trace
pseudo-device
file.
Tracing and
logging subsys‐
tem configura‐
tion file.
Contains vari‐
ables which
control the
behavior of dur‐
ing
sys‐
tem
startup.
Default console
logging options
filter file as
specified in
Default log
file as speci‐
fied in
AUTHOR
was developed
by HP.
SEE ALSOnetfmt(1M),
nettlconf(1M),
nettl‐
gen.conf(4).
nettl(1M)