NAME

klogd - Kernel Log Daemon

SYNOPSIS

klogd [ -c n ] [ -d ] [ -f fname ] [ -u username ] [ -j chroot_dir ] [ -iI ] [ -n ] [ -o ] [ -s ] [ -v ]

DESCRIPTION

klogd is a system daemon which intercepts and logs Linux kernel messages.

OPTIONS

-c n

Sets the default log level of console messages to n.

-d

Enable debugging mode. This will generate LOTS of output to stderr.

-f file

Log messages to the specified filename rather than to the syslog facility.

-u username

Tells klogd to become the specified user and drop root privileges before starting logging.

-j chroot_dir

Tells klogd to chroot(2) into this directory after initializing. This option is only valid if the -u option is also used to run klogd without root privileges. Note that the use of this option will prevent -i and -I from working unless you set up the chroot directory in such a way that klogd can still read the kernel module symbols.

-i -I

Signal the currently executing klogd daemon. Both of these switches control the loading/reloading of symbol information. The -i switch signals the daemon to reload the kernel module symbols. The -I switch signals for a reload of both the static kernel symbols and the kernel module symbols.

-n

Avoid auto-backgrounding. This is needed especially if the klogd is started and controlled by init(8).

-o

Execute in 'one-shot' mode. This causes klogd to read and log all the messages that are found in the kernel message buffers. After a single read and log cycle the daemon exits.

-s

Force klogd to use the system call interface to the kernel message buffers.

-v

Print version and exit.

-k file

Does nothing, retained for compatibility.

-p

Does nothing, retained for compatibility.

-x

Does nothing, retained for compatibility.

-2

Does nothing, retained for compatibility.

OVERVIEW

The functionality of klogd has been typically incorporated into other versions of syslogd but this seems to be a poor place for it. In the modern Linux kernel a number of kernel messaging issues such as sourcing, prioritization and resolution of kernel addresses must be addressed. Incorporating kernel logging into a separate process offers a cleaner separation of services.

In Linux there are two potential sources of kernel log information: the /proc file system and the syscall (sys_syslog) interface, although ultimately they are one and the same. Klogd is designed to choose whichever source of information is the most appropriate. It does this by first checking for the presence of a mounted /proc file system. If this is found the /proc/kmsg file is used as the source of kernel log information. If the proc file system is not mounted klogd uses a system call to obtain kernel messages. The command line switch (-s) can be used to force klogd to use the system call interface as its messaging source.

If kernel messages are directed through the syslogd daemon the klogd daemon, as of version 1.1, has the ability to properly prioritize kernel messages. Prioritization of the kernel messages was added to it at approximately version 0.99pl13 of the kernel. The raw kernel messages are of the form:

<[0-7]>Something said by the kernel.

The priority of the kernel message is encoded as a single numeric digit enclosed inside the <> pair. The definitions of these values is given in the kernel include file kernel.h. When a message is received from the kernel the klogd daemon reads this priority level and assigns the appropriate priority level to the syslog message. If file output (-f) is used the prioritization sequence is left pre-pended to the kernel message.

The klogd daemon can also be used in a 'one-shot' mode for reading the kernel message buffers. One shot mode is selected by specifying the -o switch on the command line. Output will be directed to either the syslogd daemon or to an alternate file specified by the -f switch.

For example, to read all the kernel messages after a system boot and record them in a file called krnl.msg the following command would be given.

	klogd -o -f ./krnl.msg

CONSOLE LOG LEVEL

The klogd daemon allows the ability to alter the presentation of kernel messages to the system console. Consequent with the prioritization of kernel messages was the inclusion of default messaging levels for the kernel. In a stock kernel the the default console log level is set to 7. Any messages with a priority level numerically lower than 7 (higher priority) appear on the console.

Messages of priority level 7 are considered to be 'debug' messages and will thus not appear on the console. Many administrators, particularly in a multi-user environment, prefer that all kernel messages be handled by klogd and either directed to a file or to the syslogd daemon. This prevents 'nuisance' messages such as line printer out of paper or disk change detected from cluttering the console.

When -c is given on the commandline the klogd daemon will execute a system call to inhibit all kernel messages from being displayed on the console. Former versions always issued this system call and defaulted to all kernel messages except for panics. This is handled differently currently so klogd doesn't need to set this value anymore. The argument given to the -c switch specifies the priority level of messages which will be directed to the console. Note that messages of a priority value LOWER than the indicated number will be directed to the console.

For example, to have the kernel display all messages with a priority level of 3 (KERN_ERR) or more severe the following command would be executed:

	klogd -c 4

The definitions of the numeric values for kernel messages are given in the file kernel.h which can be found in the /usr/include/linux directory if the kernel sources are installed. These values parallel the syslog priority values which are defined in the file syslog.h found in the /usr/include/sys sub-directory.

The console log level is usually configured with the sysctl(8) program, directly or via its configuration file /etc/sysctl.conf. In this file the following line

kernel.printk = 4 4 1 7

corresponds to the sampe setting above.

SIGNAL HANDLING

The klogd will respond to eight signals: SIGHUP, SIGINT, SIGKILL, SIGTERM, SIGTSTP, SIGUSR1, SIGUSR2 and SIGCONT. The SIGINT, SIGKILL, SIGTERM and SIGHUP signals will cause the daemon to close its kernel log sources and terminate gracefully.

The SIGTSTP and SIGCONT signals are used to start and stop kernel logging. Upon receipt of a SIGTSTP signal the daemon will close its log sources and spin in an idle loop. Subsequent receipt of a SIGCONT signal will cause the daemon to go through its initialization sequence and re-choose an input source. Using SIGSTOP and SIGCONT in combination the kernel log input can be re-chosen without stopping and restarting the daemon. For example if the /proc file system is to be un-mounted the following command sequence should be used:

# kill -TSTP pid

# umount /proc

# kill -CONT pid

Notations will be made in the system logs with LOG_INFO priority documenting the start/stop of logging.

The SIGUSR1 and SIGUSR2 signals are used to initiate loading/reloading of kernel symbol information. Receipt of the SIGUSR1 signal will cause the kernel module symbols to be reloaded. Signaling the daemon with SIGUSR2 will cause both the static kernel symbols and the kernel module symbols to be reloaded.

Provided that the System.map file is placed in an appropriate location the signal of generally greatest usefulness is the SIGUSR1 signal. This signal is designed to be used to signal the daemon when kernel modules are loaded/unloaded. Sending this signal to the daemon after a kernel module state change will insure that proper resolution of symbols will occur if a protection fault occurs in the address space occupied by a kernel module.

FILES

/proc/kmsg

One Source for kernel messages klogd

/var/run/klogd.pid

The file containing the process id of klogd

/boot/System.map, /System.map, /usr/src/linux/System.map

Default locations for kernel system maps.

BUGS

Probably numerous. Well formed context diffs appreciated.

AUTHORS

The kernel log daemon klogd was originally written by Steve Lord <lord@cray.com>, Greg Wettstein made major improvements. Martin Schulze <joey@infodrom.org> fixed some bugs and took over maintenance.