unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 kl(1M)								      kl(1M)




 NAME
      kl - control kernel logging

 SYNOPSIS
      /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
      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
      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 Release 11i: November 2000






 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 Release 11i: November 2000






 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 8 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 Release 11i: November 2000






 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.	The maximum
		     qsize is 10000 messages; the minimum qsize is 100
		     messages.	Note that qsize indicates the number of
		     messages the queue can hold in memory, not the amount
		     of memory the messages themselves would occupy.  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-to-
			disk, 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



 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 kl(1M)								      kl(1M)




			class(es) logged for each subsystem.

 USAGE
    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
      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-to-
      disk 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 Release 11i: November 2000






 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
      kl exits with one of the following values:

	   0  Operation was successful

	   1  kl command aborted due to error(s)

 EXAMPLES
      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 Release 11i: November 2000






 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
      kl was developed by HP in partnership with NEC.

 FILES
      /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
      netfmt(1M), nettl(1M), nettlconf(1M), nettlgen.conf(4).





























 Hewlett-Packard Company	    - 7 -   HP-UX Release 11i: November 2000