nettl(1M) nettl(1M)
NAME
nettl - 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. 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 net-
work, as well as loopback or header information. A subsystem is a particular 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 combinations 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 logging. Logging is
enabled for all subsystems as determined 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 configured in the 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 (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. Otherwise, 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 cor-
responding trace/log calls from the network 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:
o receives interrupts from the disk to which trace buffers are being written
o does not receive non-disk interrupts
o 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 suc-
cessfully 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 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 prod-
uct documentation 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 initializes 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 tracing 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 standard 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 messages. A level of 1 specifies cautionary messages as well as the default messages. A level of 2 speci-
fies information messages in addition to the cautionary and default messages. This option is recognized only by the subsys-
tem.
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 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.
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 configuration file is read and subsystems are enabled for log-
ging 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 different 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 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.
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 memory avail-
able (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 available.
If the memory allocated when tracing is first enabled proves to be insufficient, that is, when trace buffers cannot accommo-
date 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 option is optional.
Setting these values too low increases the possibility 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 exam-
ples 9 and 10 for the usage.
This option is being maintained for backward
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 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.
Used alone without other options.
Report the tracing and logging facility status. The facility must be operational, that is, has been completed. The addi-
tional options define the type of trace or log information that is to be displayed. The default value is
Log status information
Trace status information
Trace and log status information
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 maxsize 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 satisfied, the default
value for maxsize 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 specified, the default value is two trace files.
Requires the
option.
Disable tracing of subsystems specified by the option. If is specified as an argument to the option, all tracing is dis-
abled. 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 subsystems. Other options are not required.
Start tracing on the specified subsystems. The tracing and logging facility must have been initialized by for this command
to have any effect. The default trace file is standard output; 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 condition.
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 separately 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 subsystem 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 subsystem that is already being traced, the tracing mask and optional values are changed to those speci-
fied by the new command, but the new and options are ignored and a message is issued.
If is specified, all recognized subsystems are traced except X.25-specific subsystems. To turn on tracing for X.25, use the
command
where the value of x.25_subsys is or
Used as a standalone option.
This command is used to set filter expressions for subsystems. The filter expressions are specified in the filter configu-
ration file filter_file. Currently filters are supported for the following subsystems: GELAN, IGELAN, BTLAN, INTL100,
IETHER, IXGBE, NS_LS_IP, NS_LS_TCP, NS_LS_UDP, and NS_LS_ICMP. 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 specified then filters are turned on for all the subsystems that currently support filters as listed above.
Used as a standalone 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 filters as listed above.
Used as a standalone option.
Used to display the filters and their respective states. If the filter is set or turned on for a subsystem, the filter
expression is displayed along with the status of the filter. If no filter is set for a subsystem then the corresponding
filter status is mentioned. If the attribute is specified then filter status is displayed for all the subsystems that cur-
rently support filters as listed above.
Used as a standalone option.
This option is used to remove filter expressions for subsystems that have been set with the command. If the attribute is
specified then filters are removed for all the subsystems that currently support filters as listed above.
Trace Memory Management
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 writ-
ten 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 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 = init_mem/4, 32 MB )
Refer to examples 10 and 11 for further details.
Data File Management
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 or 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 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 specified by the option.
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 command.
Console Logging
Console logging is used to display significant log events on the system console. The values in the file determine if console logging is to
be started and the entries in the file determine what log messages will be reported to the console. The command can be used to configure
and maintain the information in the file (see nettlconf(1M)). If changes are made to these files, 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 formatter can be used to direct output to the console device. This may be most useful in an X windows environ-
ment.
Console logging may be disabled if conservation of system resources is valued more than notification of log events.
Trace Filters
Trace filters are a filter criteria applied on trace packets before actually capturing them. The filter criteria is an expression consist-
ing 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 packets are discarded.
Filter Configuration File
This file is used to configure the filters. Entries in the file have the following syntax:
Subsystem subsystem_name filter expression
The filter expression can be constructed using operands and operators.
The supported filter operands are:
Operand Description
mac_src Source Mac Address
mac_dst Destination Mac Address
mac_type Ethernet type
ip_src Source IP Address
ip_dst Destination IP Address
ip_p IP Protocol
th_sport TCP source port
th_dport TCP destination port
th_flags TCP flags
uh_sport UDP source port
uh_dport UDP destination port
icmp_type ICMP type
icmp_code ICMP code
The supported operators are and
Note that the (single equal) operator is not supported.
Logical operators that are supported are and The logical operators are used to combine the individual filters for a subsystem.
EXTERNAL INFLUENCES
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
1. Initialize the tracing/logging facility:
(See note for the option.)
2. Display the status of the tracing/logging facility.
3. Change log class to and for all the subsystems. logging is always on for all subsystems.
4. Turn on inbound and outbound PDU tracing for the and (OTS/9000) subsystems and send binary trace messages to file
5. Turn on outbound PDU tracing for X.25 level two and subsystems and Trace messages go to the trace file set up in the previous exam-
ple. This example also uses the abbreviated options. Tracing for X.25 requires a option to indicate which X.25 card to trace.
6. Determine status of tracing from the previous two examples.
The output should resemble the following:
7. Stop tracing for all subsystems.
8. Enable and tracing for (LAN driver) subsystem. 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 automatically 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 igelan (IGELAN driver) with initial trace memory being 128 MB and maximum memory that can be allo-
cated being 512 MB. Binary trace data goes to file Also, bind the disk-write process to processor 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 buffer size = 64 MB/2).
11. Terminate the tracing and logging facility.
(See note for the option.)
12. Add a filter configuration file entry to capture packets that have the and flags set.
13. Turn the filter on for the NS_LS_TCP subsystem.
14. Turn the filter off for the NS_LS_TCP subsystem.
15. Display the filter for the GELAN subsystem.
16. Remove the filter for the NS_LS_TCP subsystem.
WARNINGS
Although the 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 and commands read the 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
Kernel log pseudo-device file.
Kernel trace pseudo-device file.
Tracing and logging subsystem configuration file.
Contains variables which control the behavior of
during system startup.
Default console logging options filter file as specified in
Default log file as specified in
AUTHOR
was developed by HP.
SEE ALSO
netfmt(1M), nettlconf(1M), nettlgen.conf(4).
nettl(1M)