Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > N

nettl(1M)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

nettl — control network tracing and logging

SYNOPSIS

/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...

/usr/sbin/nettl -setfilter filter_file

/usr/sbin/nettl -filteron subsystem...

/usr/sbin/nettl -filteroff subsystem...

/usr/sbin/nettl -displayfilter subsystem...

/usr/sbin/nettl -removefilter subsystem...

DESCRIPTION

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

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 case-insensitive.

-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 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 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.

-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 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.

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:

FullAbbr.Mask
informativei1
warningw2
errore4
disasterd8

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 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 available (can be found using vmstat 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 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

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)

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:

keywordmask keywordmask
__ __
hdrin0x80000000 state0x04000000
hdrout0x40000000 error0x02000000
pduin0x20000000 logging0x01000000
pduout0x10000000 loopback0x00800000
proc0x08000000   

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.

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.

For example, the following NS_LS_* subsystems support only the pduin and pduout 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 -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.

-setfilter filter_file

(Abbr.: -sfl)

Used as a standalone option.

This command is used to set filter expressions for subsystems. The filter expressions are specified in the filter configuration 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.

-filteron all

-filteron subsystem ...

(Abbr.: -flon)

Used as a standalone option.

Used to turn on a filter that has been set with the setfilter option for the subsystem. This makes the filter active. If the attribute all is specified then filters are turned on for all the subsystems that currently support filters as listed above.

-filteroff all

-filteroff subsystem ...

(Abbr.: -floff)

Used as a standalone option.

Used to turn off a filter that has been previously turned on with the filteron option for the subsystem. This makes the filter inactive, but it is still set to be turned on in the future. If the attribute all is specified then filters are removed for all the subsystems that currently support filters as listed above.

-displayfilter all

-displayfilter subsystem ...

(Abbr.: -dfl)

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 all is specified then filter status is displayed for all the subsystems that currently support filters as listed above.

-removefilter all

-removefilter subsystem ...

(Abbr.: -rfl)

Used as a standalone option.

This option is used to remove filter expressions for subsystems that have been set with the setfilter command. If the attribute all 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 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, 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 .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

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.

Trace Filters

Trace filters are a filter criteria applied on trace packets before actually capturing them. The filter criteria is an expression consisting 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:

nettl -start

(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.

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 256 MB. Binary trace data goes to file /tmp/gelan.TRC000 and combined file size being 128 MB. 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 128 MB and maximum memory that can be allocated being 512 MB. 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 64 MB (as buffer size = 64 MB/2).

11.

Terminate the tracing and logging facility.

nettl -stop

(See note for the -start option.)

12.

Add a filter configuration file entry to capture packets that have the Syn and Ack flags set.

subsystem NS_LS_TCP th_flags==SA

13.

Turn the filter on for the NS_LS_TCP subsystem.

nettl -flon NS_LS_TCP

14.

Turn the filter off for the NS_LS_TCP subsystem.

nettl -floff NS_LS_TCP

15.

Display the filter for the GELAN subsystem.

nettl -dfl GELAN

16.

Remove the filter for the NS_LS_TCP subsystem.

nettl -rfl NS_LS_TCP

WARNINGS

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

/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

nettl was developed by HP.

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.