nettl(1M)

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

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

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

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

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.

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

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

Examples of LAN subsystems:

Two X.25-specific subsystems are used for tracing only:

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

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

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

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.

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

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

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

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

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.

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

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

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

where the value of x.25_subsys is SX25L2 or SX25L3.

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

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

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

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

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

Since a buffer is written to the file as a whole, the individual file size should be at least the buffer size.

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.