kl(1M) kl(1M)
NAME [Toc] [Back]
kl - control kernel logging
SYNOPSIS [Toc] [Back]
/usr/sbin/kl -e [-q qsize] [-s fsize] [-w (on|off)] [-l {d|e|w|i}
{subsys_name...| all}]
/usr/sbin/kl -d
/usr/sbin/kl -l {d|e|w|i} {subsys_name...| all}
/usr/sbin/kl -w {on [-s fsize ] | off}
/usr/sbin/kl -s fsize
/usr/sbin/kl -i
/usr/sbin/kl -p filename [-w on [-s fsize ]]
/usr/sbin/kl -q qsize
DESCRIPTION [Toc] [Back]
The kl command controls the operation of the Kernel Logging facility.
Kernel Logging is a high-availability feature that gives system
administrators the ability to collect the information necessary to
diagnose problems with the HP-UX kernel while the system is running.
kl is used to specify the levels of events to be logged and the kernel
subsystems that will write messages to memory or disk. kl also
provides for managing the contents of the logfile in memory and on
disk.
At startup, Kernel Logging determines its default configuration by
reading the file /etc/nettlgen.conf. See nettlgen.conf(4) for an
explanation of the file format. The kl command permits only temporary
changes to the default Kernel Logging configuration without having to
stop and restart Kernel Logging facility. Note that any values you
specify on the kl command line do not modify the contents of the
/etc/nettlgen.conf file. To make permanent changes to the values in
the /etc/nettlgen.conf file, run nettlconf(1M).
Only users with appropriate privileges (root) can invoke the kl
command to control the Kernel Logging facility.
Options [Toc] [Back]
kl recognizes the following options, which can be used only in the
combinations indicated in the SYNOPSIS section. All options and
keywords are case-sensitive.
-e Enable the Kernel Logging facility and start up default
logging as defined in the file /etc/nettlgen.conf.
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: Sep 2004
kl(1M) kl(1M)
If the -l option is used in conjunction with the -e
option, the -l option must be specified as the last
option on the command line.
-d Disable the Kernel Logging facility. Once this option
is issued, Kernel Logging stops accepting logging calls
from the kernel subsystems.
-w {on|off} Turn on/off write-to-disk logging. If write-to-disk
logging is enabled, log messages residing on the log
queue in memory are written to disk and removed from
the queue.
The name of the log file on disk is formed by adding
the suffix .KLOG0 to the log file name specified in the
/etc/nettlgen.conf file. If the log file (including
suffix) already exists, one of the following events
takes place:
+ If the existing file contains messages logged during
the system run when a panic occurred, the file will
be preserved (in a new location). See the USAGE
section for more information on how this situation
is handled.
+ Otherwise, the existing file and whatever
information it contains will be lost; that is, the
contents of the file are overwritten with new kernel
logging data.
When write-to-disk logging is turned off, messages are
not written out to disk, but continue to be collected
in memory (circular buffer).
-l { d | e | w | i } { subsys_name ... | all }
Modify the level of log messages to be captured for the
specified subsystem(s).
The subsys_name argument is a subsystem name specified
in the file /etc/nettlgen.conf. The list of available
subsystem names can be obtained using the command
nettlconf -KL -status. The keyword all changes the
logging level for all subsystems specified in the file
/etc/nettlgen.conf.
The following table describes the classes of messages
that can be logged
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: Sep 2004
kl(1M) kl(1M)
Message Class Description
___________________________________________________
Disaster Signals an event or condition which
affected the the operation of an
entire subsystem, or the entire
kernel, causing several programs to
fail or the entire machine to shut
down.
Error Signals an event or condition which
did not affect the overall
operation of an entire subsystem,
or the entire kernel, but may have
caused an application program to
fail.
Warning Indicates abnormal events, possibly
caused by problems in an individual
subsystem.
Informative Describes routine operations and
current system values.
The following table identifies the classes of messages
that are captured at each log level
Log Level Classes of Messages
____________________________________________________
d Disaster
e Disaster and Error
w Disaster, Error and Warning
i Disaster, Error, Warning and Informative
Note that, although the log level is specified as a
single keyword, messages are logged according to the
following rule: if level x is specified, then all
messages whose severity is greater than or equal to the
severity of class x will be logged. The order of
severity is as follows: Disaster (the most severe),
Error, Warning, Informative (the least severe).
-s fsize Set the size of the two log files used to store logged
messages when write-to-disk is enabled. The maximum
fsize is 1 gigabyte; the minimum fsize is 16 kilobytes.
When write-to-disk is started, the default log file
size is taken from the file /etc/nettlgen.conf. The -s
option allows you to modify the size of the log file
without stopping write-to-disk operations.
Note that, when setting the file size, you can specify
a numeric value followed by the character 'M' or 'K',
which indicates that fsize is being defined in units of
megabytes or kilobytes, respectively. This suffix
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: Sep 2004
kl(1M) kl(1M)
character is case-insensitive.
-p filename Take a picture (snapshot) of the current contents in
memory of the kernel logging buffer. This option
causes all messages residing in the log queue to be
dumped to filename and removed from the queue.
Note that taking a picture (snapshot) and write-to-disk
are mutually exclusive operations, because there is no
reason to take a picture of Kernel Logging messages if
write-to-disk component already writes them to disk.
If the -w on option is specified in conjunction with
the -p option, write-to-disk logging will be started
immediately after the picture is taken.
-q qsize Set the size of the Kernel Logging queue. qsize
indicates the number of buffers of size 8 kbytes each.
The maximum qsize is 1024 buffers; the minimum qsize is
8 buffers. At startup, this value is taken from the
file /etc/nettlgen.conf.
-i Report information about the status of the Kernel
Logging facility.
Information returned by the -i option includes:
+ kernel logging facility is on or off.
+ write-to-disk logging is on or off.
+ picture (snapshot) tool is on or off.
+ current size of the Kernel Logging queue.
+ number of messages currently held in the queue.
+ name of the log file used by write-to-disk.
+ maximum file size of the log file used by write-todisk,
together with the minimum file size available
for the current session of write-to-disk.
+ number of messages not written to file (could be due
to the lack of memory or small size of the circular
buffer).
+ list of all subsystems currently specified in the
/etc/nettlgen.conf file and the associated message
class(es) logged for each subsystem.
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: Sep 2004
kl(1M) kl(1M)
USAGE [Toc] [Back]
When to Use Kernel Logging
Mission critical systems should have KL always enabled. Failing to
enable Kernel Logging causes diagnostic information about any
suspicious events that might occur on the system to be lost. The
recommended classes to capture are Disaster, Error and Warning. Use kl
-l w all command to do so.
To minimize Kernel Logging's impact on a running system, use the
kl -l e all command to set all kernel subsystems to capture
error-level log messages only.
Log File Management [Toc] [Back]
The write-to-disk facility uses two files to hold logging information.
The base name of the log files is specified in /etc/nettlgen.conf.
The default base log file name is /var/adm/kl; see nettlgen.conf(4).
The most current data is always in the file with suffix .KLOG0. If
the size of the .KLOG0 file reaches a user-defined maximum, Kernel
Logging renames the .KLOG0 file to .KLOG1, overwriting the previous
contents of the .KLOG1 file, then continues writing messages to the
.KLOG0 file. (Specify maximum log file size in /etc/nettlgen.conf or
use the -s option.)
The Kernel Logging facility has a protection feature for saving old
log files. When write-to-disk starts and encounters old log files
that contain messages collected during a prior run of the system when
a panic occurred (thus, the log files may contain important
information about the panic), then log files are not overwritten.
Instead, write-to-disk first attempts to move the old log files to the
default crash directory (typically /var/adm/crash/crash.ID, where ID
is a numeric counter). If the move fails, then write-to-disk tries to
rename the log files with the prefix OLD, allowing the files to remain
in the same directory. For example, if write-to-disk finds an old log
file named /var/adm/kl.KLOG0, it first tries to move the file into the
default crash directory. If this move is not successful, write-todisk
then tries to move the file to /var/adm/OLDkl.KLOG0.
If both attempts to save old log files fail, the write-to-disk
component is not started. To preserve the messages in the old log
files, do one of the following:
+ If possible, eliminate the conditions that caused both
attempts to move the old log files to fail.
+ Manually move old log files.
+ Using the nettlconf command, modify the file
/etc/nettlgen.conf to specify a different log file name for
write-to-disk logging.
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: Sep 2004
kl(1M) kl(1M)
Once the problem is corrected, start write-to-disk again. If
successful, the Kernel Logging facility will notify you about the move
of the old log files.
RETURN VALUE [Toc] [Back]
kl exits with one of the following values:
0 Operation was successful
1 kl command aborted due to error(s)
EXAMPLES [Toc] [Back]
1. Enable the default Kernel Logging facility.
kl -e
2. Display the information about the Kernel Logging facility.
kl -i
3. Change level to log disaster, error and warning messages for all
subsystems.
kl -l w all
4. Request a picture (snapshot) of the collected log messages.
kl -p kl_snap.kl
5. Turn on default write-to-disk logging.
kl -w on
6. Change the maximum size of the current log file to 512KB.
kl -s 512K
7. Turn off write-to-disk logging.
kl -w off
8. Disable the Kernel Logging facility.
kl -d
9. Enable on the Kernel Logging facility with the following
parameters: queue size is 1000, write-to-disk component is on,
maximum file size is 4 megabytes, and log level for the KL_PM
subsystem is Warning.
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: Sep 2004
kl(1M) kl(1M)
kl -e -q 1000 -w on -s 4M -l w KL_PM
Note that -l w KL_PM changes the initial level of the KL_PM
subsystem only. This means that the initial levels of the rest
of the subsystems specified in the /etc/nettlgen.conf file remain
unchanged.
10. Take a picture (snapshot) and start write-to-disk logging with a
maximum file size of 128K.
kl -p -w on 128K
AUTHOR [Toc] [Back]
kl was developed by HP in partnership with NEC.
FILES [Toc] [Back]
/dev/kernlog Kernel log pseudo-device file.
/etc/nettlgen.conf NetTL and KL subsystem configuration
file.
/var/adm/kl.KLOG0 Default log files as specified in
/etc/nettlgen.conf
/var/adm/kl.KLOG1
SEE ALSO [Toc] [Back]
netfmt(1M), nettl(1M), nettlconf(1M), nettlgen.conf(4).
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: Sep 2004 [ Back ] |
