- -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
.LOG00
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.LOG00).
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.
- -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_ni
ns_ls_icmp ns_ls_netisr ns_ls_tcp
ns_ls_igmp ns_ls_nfs ns_ls_udp
ns_ls_ip ns_ls_nft ns_ls_x25
Two X.25-specific subsystems are used for tracing only:
- -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.TRC0
which receives the binary tracing data.
If a trace file of the name
tracename.TRC0
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.
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:
- 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 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 the user is 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.
- -size portsize
(Abbr.: -s)
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, a second is used.
Two trace files can exist on a system at any given time.
See "Data File Management" below for more information on file behavior.
maxsize
specifies the maximum size in kilobytes (KB) of both trace files combined.
The default value for the combined file sizes is 1000 KB.
The possible range for
maxsize
is 100 to 99999.
- -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:
- 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.
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
X25L2
or
X25L3.
