NAME

nettl − control network tracing and logging

SYNOPSIS

/etc/nettl −start
/etc/nettl −stop
/etc/nettl −status [info]
/etc/nettl −traceon kind [kind...] [−card dev_name] −entity subsystem [subsystem...] [−file name] [−size limit] [−tracemax maxsize] [.BI−m bytes]
/etc/nettl −traceoff −entity subsystem [subsystem...]
/etc/nettl −log class −entity subsystem [subsystem...] /etc/nettl −fm 0|1|2 −c  dev_name

DESCRIPTION

nettl is a tool used to capture network events or packets.  Logging is a means of capturing network activities such as state changes, memory errors, and connections.  Tracing is used to capture or take a snapshot of inbound and outbound packets going though 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, X25L2, or FTAM_USER.  nettl is used to control the network tracing and logging facility.  The command can be used in six different forms as indicated above.  Command forms are discussed first, then options and parameters.  nettl can be accessed only by users with appropriate privileges. 

Options

nettl recognizes the following options which can be used only in the combinations indicated above under SYNOPSIS.  Options can be specified by spelling out in full or abbreviating as indicated.  Argument keywords can be abbreviated as shown.  The keywords are case-insensitive.

−start [abbrev:  −st] Used alone without other options.

Initializes the tracing and logging facility and starts up default logging.  Logging is enabled for all subsystems as determined by the /etc/conf/nettlgen.conf file.  Log messages are sent to the file specified in the configuration file /etc/conf/nettlgen.conf.  See nettlconf(1M) and nettlgen.conf(4) for an explanation of the configuration file. The log file name given in the configuration file will have the suffix .LOG00 appended to it.  If the log file (with suffix) already exists, it is opened in append-mode; i.e., new data is added to the file.  The name supplied by default is /usr/adm/nettl (thus logging starts to file /usr/adm/nettl.LOG00.)  See Data File Management below for more information on how the log file is handled. 

NOTE: It is strongly recommended that the tracing and logging facility be started before any other networking.  The /etc/nettl −start command should be placed in /etc/netlinkrc before any other networking commands. 

−stop [abbrev:  −sp] Used alone without other options.

Terminates 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: It is strongly recommended that the tracing and logging facility not be turned off, since information about disasters will be lost.  To minimize impact on the system, all subsystems may be set to capture only DISASTER class log messages. 

−status info [abbrev:  −ss] Used alone without other options.

Reports tracing and logging facility status.  The facility must be operational (i.e.  /etc/nettl −start has been completed).  The default value is ALL.  info defines the type of trace or log information that is to be displayed.  info can be one of the following:

log log status information

trace trace status information

all trace & log status information

−traceon kind [kind...] [abbrev:  −tn] Requires −entity option; −card option required for X.25 subsystems only (ignored otherwise); other options recognized but not required. 

Starts tracing on the specified subsystem or subsystems.  The tracing and logging facility must have been initialized, via nettl −start for this command to have any effect.  kind defines the trace masks used by the tracing facility before recording a message.  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 0x30000000. 

loopback can be enabled by NS subsystems only.  An error is returned if a given subsystem does not support a particular trace kind.  If a −traceon is issued on a subsystem already being traced, the tracing mask and optional values are changed to those specified by the new command, but the new file, size, tracemax and −m parameters are ignored and a message is issued. 

−entity all

−entity subsystem [subsystem...]
[abbrev:  −e] The subsystem parameter limits the action (−status, −traceon, −traceoff, or −log) to the specified (one or more) protocol layers or software modules.  If all is specifed, all recognized subsystems are traced except X.25-specific subsystems.  To turn on tracing for X.25, run

nettl −tn kind −e[x.25_subsys] −c[dev_name]

where the value of [x.25_subsys] is x25l2 or x25l3. Run nettl −ss all to obtain a full listing of supported subsystems.  An example of subsystems include:

OSI-examples of subsystems:

LAN-examples of subsystems:

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

−card dev_name
[abbrev:  −c] This parameter applies to X.25 subsystems only, for setting up tracing.  For other subsystems, this option is ignored and a warning message is issued.  Only one X.25 card can be traced at a time. 

Specifies a device which corresponds to a network interface card that has been installed  and configured.  Internally to nettl, the /dev/ path is attached to the name and therefore, nettl indicates an error if /dev/ is part of the device name.  dev_name must refer to a valid X.25 network device file. 

−file name [abbrev:  −f] Used with the first −traceon option only. 

The first time the −traceon keyword is used, it initializes tracing, creating a file name.TRC0 which receives the binary tracing data.  To start a fresh trace file, the user must turn off tracing and turn it back on again (see Data File Management below for more information on file naming).  The log file is specified in the /etc/conf/nettlgen.conf configuration file. 

When tracing is enabled, every operation through that entity is recorded if it satisfies the kind mask. 

If −file is omitted, binary trace output goes to standard output. 

−size limit [abbrev:  −s] Used with first −traceon option only. 

Sets trace buffer size (in Kbytes) used to hold trace messages until they are written to the file.  Default value for this buffer is 32 Kbytes.  The possible range for this parameter is 1 through 512 Kbytes.  The default trace file is standard output, but can be overridden by the optional −file argument.  Setting this value too low increases the possibility of dropped trace messages from kernel subsystems. 

−tracemax maxsize
Used with first −traceon option only.  Tracing uses a circular file method such that when one file fills up a second is used.  Two trace files can exist on a system at any given time. 

maxsize specifies the maximum size of both trace files combined.  Specify maxsize in multiples of 1 Mbyte.  If this option is not specified, a default size of 10 Mbytes is used.  maxsize can range in value from 1 through 999 Mbytes. 

−traceoff [abbrev:  −tf] Requires −entity option. 

Disables tracing of subsystems specified via 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 to view the trace messages it contains. 

−log class [abbrev:  −l] Requires −entity option. 

Controls the class of log messages that are enabled for the subsystems specified with the −entity option. 

class specifies the logging class.  Available classes are:

Classes can be specified as keywords or as a numeric mask depicting which classes to log.  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 can be configured into a configuration file, /etc/conf/nettlgen.conf.  When the tracing/logging facility is started, this information is read and the subsystems are enabled for logging with the specified classes.  To change the log class, use the nettl −log [class] −e [subsystem] command with a new log class value.  The nettl−l class −e entity command can be run for different log classes and different entities if desired. 

−m num Used with the first −traceon option only.  Number of bytes to trace.  This option allows the user to specify the number of bytes to be captured in the trace packet.  The user may prefer not to capture an entire PDU trace, such as when interested only in the header.  num is the number of bytes traced.  Default is the entire packet is traced.  This option is currently recognized for tracing by the following subsystems only:

−firmware 0|1|2
[abbrev:  −fm] Requires −card option.  S800, X.25 only.  Sets 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 cautionary and default messages.  This option is recognized only by the NS_LS_X25 subsystem. 

Data File Management

Data files created by the tracing and logging facility require special handling by the facility that the user must be aware of.  When files are created, they have the suffix .LOG00 or .TRC0 appended to them, depending on whether they are log or trace files, respectively.  This facility is used to keep the files distinct for cases where the user specifies 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 .LOG00 or .TRC0.  When the files are full, they are renamed to the next higher number in their sequence; i.e., .LOG01 or .TRC1 and new files with the 0 extension are created.  Currently only two generations of files are possible; thus only two log files appear on the system simultaneously (.LOG00 and .LOG01.)  The same is true for trace files as well; only two trace files exist with the same file name, not counting the postfix of .TRC0 and .TRC1. 

NOTE: The file name prefix specified by the user must not exceed eight characters, so that the file name plus suffix will not exceed fourteen characters.  Longer names are truncated silently.  To see the actual name of the trace or log file, use the /etc/nettl −status all command. 

Console Logging

All disaster class log messages are automatically formatted and written to the console in a short form.  If more information is desired on the console, the netfmt(1M) formatter can be used to direct output to the console device. This may be most useful in an X windows environment. See examples below on how to do this.

EXTERNAL INFLUENCES

International Code Set Support

Single- and multi-byte character code sets are supported in data; single-byte character code sets are supported in filenames. 

EXAMPLES

1.  Initialize the tracing/logging facility:

nettl −start

2.  Change log class to WARNING for all the subsystems.  DISASTER logging is always on for all subsystems. 

nettl −log w −e all

3.  Turn on inbound PDU tracing for the subsystems ula_utils, hps (all trace kinds are enabled by ORing the masks) and send binary trace messages to file /usr/adm/trace.file.TRC0. 

nettl −traceon pduin −entity ula_utils hps −file /usr/adm/trace.file

4.  Turn on outbound PDU tracing for X.25 level two, and subsystem NI.  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 parameter to indicate which X.25 card to trace.  If you choose not to trace X.25 by omitting x25l2, the card parameter is ignored. 

nettl −tn  pduout −e x25l2 ns_ls_ni −c x25_0

5.  Determine status of tracing from example 3. 

nettl −status trace

The resulting information should resemble the following:

Date started:            Fri Apr 22 13:47:28 PDT 1988
Trace Information:
Trace File name:    /usr/adm/trace.file
Uid:                0 (root)  Buffer Size:        32
KBytes
Dropped Messages:   0         Messages Queued:    0
Subsystem:               Trace Kind:
ULA_UTILS                20000000
HPS                      20000000
X25L2                    1000000
NS_LS_NI                 1000000

6.  Enable pdu tracing for lan subsystems.  Binary trace data goes to file /usr/adm/LAN.TRC0. 

The −f option of this command is only valid the first time tracing is called.  To change the trace output file, stop tracing and start up again.  The trace file is not automatically reset with the −f option.  This example assumes that the −traceon option is being used for the first time. 

nettl −tn pduin pduout −e ns_ls_lan0 −file /usr/adm/LAN

7.  Terminate the tracing and logging factility.  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. 

nettl −stop

CAVEATS

Tracing or logging 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 may be increased.  Be selective about the number of subsystems being traced, as well as the log class messages being captured. 

FILES

/usr/adm/nettl.LOG00 default Log file as specified in /etc/conf/nettlgen.conf. 

/etc/conf/nettlgen.conf tracing and logging configuration file. 

/dev/nettrace kernel trace pseudo-device file. 

/dev/netlog kernel log pseudo-device file. 

AUTHOR

nettl was developed by HP. 

SEE ALSO

netfmt(1M), nettlgen(1M), nettlconf(1M), nettlgen.conf(4). 

Hewlett-Packard Company  —  HP-UX Release 8.05: June 1991