emo/sysklogd
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Convert man pages to mdoc format, remove sysklogd.8 man page

Browse Source 
- Major cleanup, simplifications, grammar corrections
- Remove inappropriate sections
- Update syntax and add tables for facility and priority

Signed-off-by: Joachim Nilsson <troglobit@gmail.com>
This commit is contained in:
Joachim Nilsson 2019-10-30 15:56:30 +01:00
parent a1e5680aee
commit dfff48fb04
5 changed files with 1348 additions and 1317 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
man/Makefile.am
View File

@ -1,3 +1,3 @@
dist_man1_MANS = logger.1 dist_man1_MANS = logger.1
dist_man5_MANS = syslog.conf.5 dist_man5_MANS = syslog.conf.5
dist_man8_MANS = syslogd.8 klogd.8 sysklogd.8 dist_man8_MANS = syslogd.8 klogd.8

671
man/klogd.8
View File

@ -1,143 +1,140 @@
.\" Copyright 1994-6 Dr. Greg Wettstein, Enjellic Systems Development. -*- nroff -*- .\" -*- nroff -*-
.\" Copyright 1997-2007 Martin Schulze <joey@infodrom.org> .\" Copyright 1994-1996 Dr. Greg Wettstein, Enjellic Systems Development.
.\" Copyright 1997-2007 Martin Schulze <joey@infodrom.org>
.\" Copyright 2018-2019 Joachim Nilsson <troglobit@gmail.com>
.\"
.\" May be distributed under the GNU General Public License .\" May be distributed under the GNU General Public License
.\" .\"
.TH KLOGD 8 "12 October 2019" "Version 2.0" "Linux System Administration" .Dd Oct 30, 2019
.SH NAME .Dt klogd 8
klogd \- Kernel Log Daemon .Os "sysklogd (2.0)"
.SH SYNOPSIS .Sh NAME
.B klogd .Nm klogd
.RB [ " \-c " .Nd Kernel Log Daemon
.I n .Sh SYNOPSIS
] .Nm
.RB [ " \-d " ] .Op Fl 2ndiInopsvx
.RB [ " \-f " .Op Fl c Ar NUM
.I fname .Op Fl f Ar FILE
] .Op Fl k Ar FILE
.RB [ " \-iI " ] .Sh DESCRIPTION
.RB [ " \-n " ] .Nm
.RB [ " \-o " ] is a system daemon which intercepts and logs Linux kernel messages.
.RB [ " \-p " ] .Sh OPTIONS
.RB [ " \-s " ] .Bl -tag -width Ds
.RB [ " \-k " .It Fl c Ar NUM
.I fname Sets the default log level of console messages to
] .Ar NUM
.RB [ " \-v " ] (1-8).
.RB [ " \-x " ] .It Fl d
.RB [ " \-2 " ] Enable debugging mode. This will generate potentially LOTS of output to
.SH DESCRIPTION
.B klogd
is a system daemon which intercepts and logs Linux kernel
messages.
.SH OPTIONS
.TP
.BI "\-c " n
Sets the default log level of console messages to \fIn\fR.
.TP
.B "\-d"
Enable debugging mode. This will generate \fBLOTS\fR of output to
stderr. stderr.
.TP .It Fl f Ar FILE
.BI "\-f " file
Log messages to the specified filename rather than to the syslog facility. Log messages to the specified filename rather than to the syslog facility.
.TP .It Fl i | Fl I
.BI "\-i \-I"
Signal the currently executing klogd daemon. Both of these switches control Signal the currently executing klogd daemon. Both of these switches control
the loading/reloading of symbol information. The \-i switch signals the the loading/reloading of symbol information. The
daemon to reload the kernel module symbols. The \-I switch signals for a .Fl i
reload of both the static kernel symbols and the kernel module symbols. switch signals the daemon to reload the kernel module symbols. The
.TP .Fl I
.B "\-n" switch signals for a reload of both the static kernel symbols and the
Avoid auto-backgrounding. This is needed especially if the kernel module symbols.
.B klogd .It Fl n
Avoid auto-backgrounding. This is needed especially if
.Nm
is started and controlled by is started and controlled by
.BR init (8). .Xr init 8 .
.TP .It Fl o
.B "\-o" Execute in one-shot mode. This causes
Execute in 'one\-shot' mode. This causes \fBklogd\fP to read and log .Nm
all the messages that are found in the kernel message buffers. After to read and log all the messages that are found in the kernel message
a single read and log cycle the daemon exits. buffers. After a single read and log cycle the daemon exits.
.TP .It Fl p
.B "\-p" Enable paranoia mode. This option controls when klogd loads kernel
Enable paranoia. This option controls when klogd loads kernel module symbol module symbol information. This mode causes klogd to load the kernel
information. Setting this switch causes klogd to load the kernel module module symbol information whenever a kernel "Oops" string is detected in
symbol information whenever an Oops string is detected in the kernel message the kernel message stream.
stream. .It Fl s
.TP Force
.B "\-s" .Nm
Force \fBklogd\fP to use the system call interface to the kernel message to use the system call interface to the kernel message buffers.
buffers. .It Fl k Ar FILE
.TP
.BI "\-k " file
Use the specified file as the source of kernel symbol information. Use the specified file as the source of kernel symbol information.
.TP .It Fl v
.B "\-v"
Print version and exit. Print version and exit.
.TP .It Fl x
.B "\-x"
Omits EIP translation and therefore doesn't read the System.map file. Omits EIP translation and therefore doesn't read the System.map file.
.TP .It Fl 2
.B "\-2"
When symbols are expanded, print the line twice. Once with addresses When symbols are expanded, print the line twice. Once with addresses
converted to symbols, once with the raw text. This allows external converted to symbols, once with the raw text. This allows external
programs such as ksymoops do their own processing on the original programs such as ksymoops do their own processing on the original data.
data. .Sh OVERVIEW
.SH OVERVIEW
The functionality of klogd has been typically incorporated into other 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 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 modern Linux kernel a number of kernel messaging issues such as
sourcing, prioritization and resolution of kernel addresses must be sourcing, prioritization and resolution of kernel addresses must be
addressed. Incorporating kernel logging into a separate process addressed. Incorporating kernel logging into a separate process offers
offers a cleaner separation of services. a cleaner separation of services.
.Pp
In Linux there are two potential sources of kernel log information: the In Linux there are two potential sources of kernel log information: the
.I /proc .Pa /proc
file system and the syscall (sys_syslog) interface, although file system and the syscall,
ultimately they are one and the same. Klogd is designed to choose .Fn sys_syslog
whichever source of information is the most appropriate. It does this interface, although ultimately
by first checking for the presence of a mounted they are one and the same.
.I /proc .Nm
is designed to choose whichever source of information is the most
appropriate. It does this by first checking for the presence of a
mounted
.Pa /proc
file system. If this is found the file system. If this is found the
.I /proc/kmsg .Pa /proc/kmsg
file is used as the source of kernel log file is used as the source of kernel log
information. If the proc file system is not mounted information. If the proc file system is not mounted
.B klogd .Nm
uses a uses a system call to obtain kernel messages. The command line switch
system call to obtain kernel messages. The command line switch .Fl s
.RB ( "\-s" ) can be used to force
can be used to force klogd to use the system call interface as its .Nm
messaging source. to use the system call interface as its messaging source.
.Pp
If kernel messages are directed through the If kernel messages are directed through the
.BR syslogd " daemon the " klogd .Nm syslogd
daemon, as of version 1.1, has the ability to properly prioritize daemon,
kernel messages. Prioritization of the kernel messages was added to it .Nm ,
at approximately version 0.99pl13 of the kernel. The raw kernel messages as of version 1.1, has the ability to properly prioritize kernel
are of the form: messages. Prioritization of kernel log messages was added around Linux
.IP version 0.99pl13. The raw kernel messages are of the form:
\<[0\-7]\>Something said by the kernel. .Bd -literal -offset indent
.PP <[0-7]>Something said by the kernel.
.Ed
.Pp
The priority of the kernel message is encoded as a single numeric The priority of the kernel message is encoded as a single numeric
digit enclosed inside the <> pair. The definitions of these values is digit enclosed inside the
given in the kernel include file kernel.h. When a message is received .Ql <>
from the kernel the klogd daemon reads this priority level and assigns pair. The definitions of these values is given in the kernel include
the appropriate priority level to the syslog message. If file output file kernel.h. When a message is received from the kernel the klogd
(\fB-f\fR) is used the prioritization sequence is left pre\-pended to the daemon reads this priority level and assigns the appropriate priority
kernel message. level to the syslog message. If file output,
.Fl f Ar FILE ,
The klogd daemon can also be used in a 'one\-shot' mode for reading the is used the prioritization sequence is left pre-pended to the kernel
message.
.Pp
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 kernel message buffers. One shot mode is selected by specifying the
\fB\-o\fR switch on the command line. Output will be directed to either the .Fl o
syslogd daemon or to an alternate file specified by the \fB-f\fR switch. switch on the command line. Output will be directed to either the
.IP syslog daemon or to an alternate file specified by the
.Fl -f Ar FILE
switch.
.Pp
For example, to read all the kernel messages after a system For example, to read all the kernel messages after a system
boot and record them in a file called krnl.msg the following boot and record them in a file called krnl.msg the following
command would be given. command would be given:
.IP .Bd -literal -offset indent
.nf klogd -o -f ./krnl.msg
klogd -o -f ./krnl.msg .Ed
.fi .Sh KERNEL ADDRESS RESOLUTION
.SH KERNEL ADDRESS RESOLUTION
If the kernel detects an internal error condition a general protection If the kernel detects an internal error condition a general protection
fault will be triggered. As part of the GPF handling procedure the fault will be triggered. As part of the GPF handling procedure the
kernel prints out a status report indicating the state of the kernel prints out a status report indicating the state of the
@ -145,9 +142,9 @@ processor at the time of the fault. Included in this display are the
contents of the microprocessor's registers, the contents of the kernel contents of the microprocessor's registers, the contents of the kernel
stack and a tracing of what functions were being executed at the time stack and a tracing of what functions were being executed at the time
of the fault. of the fault.
.Pp
This information is This information is
.B EXTREMELY IMPORTANT .Sy EXTREMELY IMPORTANT
in determining what caused the internal error condition. The in determining what caused the internal error condition. The
difficulty comes when a kernel developer attempts to analyze this difficulty comes when a kernel developer attempts to analyze this
information. The raw numeric information present in the protection information. The raw numeric information present in the protection
@ -157,271 +154,279 @@ variable locations or functions will not be the same in all kernels.
In order to correctly diagnose the cause of failure a kernel developer In order to correctly diagnose the cause of failure a kernel developer
needs to know what specific kernel functions or variable locations needs to know what specific kernel functions or variable locations
were involved in the error. were involved in the error.
.Pp
As part of the kernel compilation process a listing is created which As part of the kernel compilation process a listing is created which
specified the address locations of important variables and function in specified the address locations of important variables and function in
the kernel being compiled. This listing is saved in a file called the kernel being compiled. This listing is saved in a file called
System.map in the top of the kernel directory source tree. Using this System.map in the top of the kernel directory source tree. Using this
listing a kernel developer can determine exactly what the kernel was listing a kernel developer can determine exactly what the kernel was
doing when the error condition occurred. doing when the error condition occurred.
.Pp
The process of resolving the numeric addresses from the protection The process of resolving the numeric addresses from the protection
fault printout can be done manually or by using the fault printout can be done manually or by using the
.B ksymoops .Xr ksymoops 8
program which is included in the kernel sources. program which is included in Linux kernel sources before 1999, or
from this location:
.Lk https://www.kernel.org/pub/linux/utils/kernel/ksymoops
.Pp
As a convenience As a convenience
.B klogd .Nm
will attempt to resolve kernel numeric addresses to their symbolic will attempt to resolve kernel numeric addresses to their symbolic forms
forms if a kernel symbol table is available at execution time. If you if a kernel symbol table is available at execution time. If you require
require the original address of the symbol, use the the original address of the symbol, use the
.B -2 .Fl 2
switch to preserve the numeric address. A switch to preserve the numeric address. A symbol table may be specified
symbol table may be specified by using the \fB\-k\fR switch on the by using the
command line. If a symbol file is not explicitly specified the .Fl k Ar FILE
following filenames will be tried: switch on the command line. If a symbol file is not explicitly
specified the following filenames will be tried:
.nf .Pp
.I /boot/System.map .Bl -tag -width /usr/src/linux/System.map -compact -offset indent
.I /System.map .It Pa /boot/System.map
.I /usr/src/linux/System.map .It Pa /System.map
.fi .It Pa /usr/src/linux/System.map
.El
Version information is supplied in the system maps as of kernel .Pp
1.3.43. This version information is used to direct an intelligent Version information is supplied in the system maps as of Linux 1.3.43.
search of the list of symbol tables. This feature is useful since it This version information is used to direct an intelligent search of the
provides support for both production and experimental kernels. list of symbol tables. This feature is useful since it provides support
for both production and experimental kernels.
.Pp
For example a production kernel may have its map file stored in For example a production kernel may have its map file stored in
/boot/System.map. If an experimental or test kernel is compiled with .Pa /boot/System.map .
the sources in the 'standard' location of /usr/src/linux the system If an experimental or test kernel is compiled with
map will be found in /usr/src/linux/System.map. When klogd starts the sources in the 'standard' location of
under the experimental kernel the map in /boot/System.map will be .Pa /usr/src/linux
bypassed in favor of the map in /usr/src/linux/System.map. the system
map will be found in
.Pa /usr/src/linux/System.map .
When
.Nm
starts under the experimental kernel the map in
.Pa /boot/System.map
will be bypassed in favor of the map in
.Pa /usr/src/linux/System.map .
.Pp
Modern kernels as of 1.3.43 properly format important kernel addresses Modern kernels as of 1.3.43 properly format important kernel addresses
so that they will be recognized and translated by klogd. Earlier so that they will be recognized and translated by klogd. Earlier
kernels require a source code patch be applied to the kernel sources. kernels require a source code patch be applied to the kernel sources.
This patch is supplied with the sysklogd sources. This patch is supplied with the sysklogd sources.
.Pp
The process of analyzing kernel protections faults works very well The process of analyzing kernel protections faults works very well with
with a static kernel. Additional difficulties are encountered when a static kernel. Additional difficulties are encountered when
attempting to diagnose errors which occur in loadable kernel modules. attempting to diagnose errors which occur in loadable kernel modules.
Loadable kernel modules are used to implement kernel functionality in Loadable kernel modules are used to implement kernel functionality in a
a form which can be loaded or unloaded at will. The use of loadable form which can be loaded or unloaded at will. The use of loadable
modules is useful from a debugging standpoint and can also be useful modules is useful from a debugging standpoint and can also be useful in
in decreasing the amount of memory required by a kernel. decreasing the amount of memory required by a kernel.
.Pp
The difficulty with diagnosing errors in loadable modules is due to The difficulty with diagnosing errors in loadable modules is due to the
the dynamic nature of the kernel modules. When a module is loaded the dynamic nature of the kernel modules. When a module is loaded the
kernel will allocate memory to hold the module, when the module is kernel will allocate memory to hold the module, when the module is
unloaded this memory will be returned back to the kernel. This unloaded this memory will be returned back to the kernel. This dynamic
dynamic memory allocation makes it impossible to produce a map file memory allocation makes it impossible to produce a map file which
which details the addresses of the variable and functions in a kernel details the addresses of the variable and functions in a kernel loadable
loadable module. Without this location map it is not possible for a module. Without this location map it is not possible for a kernel
kernel developer to determine what went wrong if a protection fault developer to determine what went wrong if a protection fault involves a
involves a kernel module. kernel module.
.Pp
.B klogd .Nm
has support for dealing with the problem of diagnosing protection has support for dealing with the problem of diagnosing protection faults
faults in kernel loadable modules. At program start time or in in kernel loadable modules. At program start time or in response to a
response to a signal the daemon will interrogate the kernel for a signal the daemon will interrogate the kernel for a listing of all
listing of all modules loaded and the addresses in memory they are modules loaded and the addresses in memory they are loaded at.
loaded at. Individual modules can also register the locations of Individual modules can also register the locations of important
important functions when the module is loaded. The addresses of these functions when the module is loaded. The addresses of these exported
exported symbols are also determined during this interrogation symbols are also determined during this interrogation process.
process. .Pp
When a protection fault occurs an attempt will be made to resolve kernel
When a protection fault occurs an attempt will be made to resolve addresses from the static symbol table. If this fails the symbols from
kernel addresses from the static symbol table. If this fails the the currently loaded modules are examined in an attempt to resolve the
symbols from the currently loaded modules are examined in an attempt addresses. At the very minimum this allows klogd to indicate which
to resolve the addresses. At the very minimum this allows klogd to loadable module was responsible for generating the protection fault.
indicate which loadable module was responsible for generating the Additional information may be available if the module developer chose to
protection fault. Additional information may be available if the export symbol information from the module.
module developer chose to export symbol information from the module. .Pp
Proper and accurate resolution of addresses in kernel modules requires Proper and accurate resolution of addresses in kernel modules requires
that that
.B klogd .Nm
be informed whenever the kernel module status changes. The be informed whenever the kernel module status changes. The
.B \-i .Fl i
and and
.B \-I .Fl I
switches can be used to signal the currently executing daemon that switches can be used to signal the currently executing daemon that
symbol information be reloaded. Of most importance to proper symbol information be reloaded. Of most importance to proper resolution
resolution of module symbols is the of module symbols is the
.B \-i .Fl i
switch. Each time a kernel module is loaded or removed from the switch. Each time a kernel module is loaded or removed from the kernel
kernel the following command should be executed: the following command should be executed:
.Bd -literal -offset indent
.nf klogd -i
.I klogd \-i .Ed
.fi .Pp
The The
.B \-p .Fl p
switch can also be used to insure that module symbol information is up switch can also be used to insure that module symbol information is up
to date. This switch instructs to date. This switch instructs
.B klogd .Nm
to reload the module symbol information whenever a protection fault to reload the module symbol information whenever a protection fault
is detected. Caution should be used before invoking the program in is detected. Caution should be used before invoking the program in
\&'paranoid\&' mode. The stability of the kernel and the operating 'paranoid' mode. The stability of the kernel and the operating
environment is always under question when a protection fault occurs. environment is always under question when a protection fault occurs.
Since the klogd daemon must execute system calls in order to read the Since the klogd daemon must execute system calls in order to read the
module symbol information there is the possibility that the system may module symbol information there is the possibility that the system may
be too unstable to capture useful information. A much better policy be too unstable to capture useful information. A much better policy is
is to insure that klogd is updated whenever a module is loaded or to insure that klogd is updated whenever a module is loaded or unloaded.
unloaded. Having uptodate symbol information loaded increases the Having uptodate symbol information loaded increases the probability of
probability of properly resolving a protection fault if it should occur. properly resolving a protection fault if it should occur.
.Pp
Included in the sysklogd source distribution is a patch to the Included in the sysklogd source distribution is a patch to the
modules-2.0.0 package which allows the modules-2.0.0 package which allows the
.B insmod, .Xr insmod 8 ,
.B rmmod .Xr rmmod 8 ,
and and
.B modprobe .Xr modprobe 8
utilities to automatically signal utilities to automatically signal
.B klogd .Nm
whenever a module is inserted or removed from the kernel. Using this whenever a module is inserted or removed from the kernel. Using this
patch will insure that the symbol information maintained in klogd is patch will insure that the symbol information maintained in klogd is
always consistent with the current kernel state. always consistent with the current kernel state.
.SH CONSOLE LOG LEVEL .Sh CONSOLE LOG LEVEL
The The
.B klogd .Nm
daemon allows the ability to alter the presentation of daemon allows the ability to alter the presentation of kernel messages
kernel messages to the system console. Consequent with the to the system console. Consequent with the prioritization of kernel
prioritization of kernel messages was the inclusion of default messages was the inclusion of default messaging levels for the kernel.
messaging levels for the kernel. In a stock kernel the the default In a stock kernel the the default console log level is set to 7. Any
console log level is set to 7. Any messages with a priority level messages with a priority level numerically lower than 7 (higher
numerically lower than 7 (higher priority) appear on the console. priority) appear on the console.
.Pp
Messages of priority level 7 are considered to be 'debug' messages and Messages of priority level 7 are considered to be 'debug' messages and
will thus not appear on the console. Many administrators, will thus not appear on the console. Many administrators, particularly
particularly in a multi\-user environment, prefer that all kernel in a multi-user environment, prefer that all kernel messages be handled
messages be handled by klogd and either directed to a file or to by klogd and either directed to a file or to the syslogd daemon. This
the syslogd daemon. This prevents 'nuisance' messages such as line prevents 'nuisance' messages such as line printer out of paper or disk
printer out of paper or disk change detected from cluttering the change detected from cluttering the console.
console. .Pp
When When
.B \-c .Fl c
is given on the commandline the is given on the commandline,
.B klogd .Nm
daemon will execute a system call to inhibit all kernel messages from will execute a system call to inhibit all kernel messages from being
being displayed on the console. Former versions always issued this displayed on the console. Former versions always issued this system
system call and defaulted to all kernel messages except for panics. call and defaulted to all kernel messages except for panics. This is
This is handled differently currently so handled differently currently so
.B klogd .Nm
doesn't need to set this value anymore. The doesn't need to set this value anymore. The
argument given to the \fB\-c\fR switch specifies the priority level of .Ar NUM
messages which will be directed to the console. Note that messages of argument given to the
a priority value LOWER than the indicated number will be directed to .Fl c
the console. switch specifies the priority level of messages which will be directed
.IP to the console. Note that messages of a priority value LOWER than the
For example, to have the kernel display all messages with a indicated number will be directed to the console.
priority level of 3 .Pp
.BR "" ( KERN_ERR ) For example, to have the kernel display all messages with a priority
or more severe the following level of 3,
command would be executed: .Ql (KERN_ERR)
.IP or more severe the following command would be executed:
.nf .Bd -literal -offset indent
klogd \-c 4 klogd \-c 4
.fi .Ed
.PP .Pp
The definitions of the numeric values for kernel messages are given in The definitions of the numeric values for kernel messages are given in
the file the file
.IR kernel.h " which can be found in the " /usr/include/linux .Pa kernel.h
which can be found in the
.Pa /usr/include/linux
directory if the kernel sources are installed. These values parallel directory if the kernel sources are installed. These values parallel
the syslog priority values which are defined in the file the syslog priority values which are defined in the file
.IR syslog.h " found in the " /usr/include/sys " sub\-directory." .Pa syslog.h
found in the
.PA /usr/include/sys
sub-directory.
.Pp
The console log level is usually configured with the The console log level is usually configured with the
.BR sysctl (8) .Xr sysctl 8
program, directly or via its configuration file program, directly or via its configuration file
.IR /etc/sysctl.conf . .Pa /etc/sysctl.conf .
In this file the following line In this file the following line
.IP .Bd -lilteral -offset indent
.nf
kernel.printk = 4 4 1 7 kernel.printk = 4 4 1 7
.fi .Ed
.PP .Pp
corresponds to the sampe setting above. corresponds to the sampe setting above.
.SH SIGNAL HANDLING .Sh SIGNALS
The .Nm
.B klogd responds to eight signals:
will respond to eight signals: .Pp
.BR SIGHUP ", " SIGINT ", " SIGKILL ", " SIGTERM ", " SIGTSTP ", " .Bl -tag -width TERM -compact
.BR SIGUSR1 ", "SIGUSR2 " and " SIGCONT ". The" .It HUP
.BR SIGINT ", " SIGKILL ", " SIGTERM " and " SIGHUP .It INT
signals will cause the daemon to close its kernel log sources and .It KILL
terminate gracefully. .It TERM
The SIGINT, SIGKILL, SIGTERM and SIGHUP signals cause the daemon to
The close its kernel log sources and terminate gracefully.
.BR SIGTSTP " and " SIGCONT .It TSTP
signals are used to start and stop kernel logging. Upon receipt of a .It CONT
.B SIGTSTP The SIGTSTP and SIGCONT signals are used to start and stop kernel
signal the daemon will close its logging. Upon receipt of SIGTSTP the daemon will close its log sources
log sources and spin in an idle loop. Subsequent receipt of a and spin in an idle loop. Subsequent receipt of SIGCONT cause the
.B SIGCONT daemon to go through its initialization sequence and re-choose an input
signal will cause the daemon to go through its initialization sequence source. Using SIGSTOP and SIGCONT in combination the kernel log input
and re-choose an input source. Using can be re-chosen without stopping and restarting the daemon. For
.BR SIGSTOP " and " SIGCONT example if the
in combination the kernel log input can be re-chosen without stopping and .PA /proc
restarting the daemon. For example if the \fI/proc\fR file system is to be file system is to be un-mounted the following command sequence should be
un-mounted the following command sequence should be used: used:
.PP .Bd -literal -offset indent
.PD 0 kill -TSTP pid
.TP umount /proc
# kill -TSTP pid kill -CONT pid
.TP .Ed
# umount /proc .Pp
.TP
# kill -CONT pid
.PD
.PP
Notations will be made in the system logs with Notations will be made in the system logs with
.B LOG_INFO .Ql LOG_INFO
priority priority documenting the start/stop of logging.
documenting the start/stop of logging. .It USR1
.It USR2
The The SIGUSR1 and SIGUSR2 signals are used to initiate loading/reloading
.BR SIGUSR1 " and " SIGUSR2 of kernel symbol information. Receipt of SIGUSR1 will cause the kernel
signals are used to initiate loading/reloading of kernel symbol information. module symbols to be reloaded. Signaling the daemon with SIGUSR2 will
Receipt of the cause both the static kernel symbols and the kernel module symbols to be
.B SIGUSR1 reloaded.
signal will cause the kernel module symbols to be reloaded. Signaling the .Pp
daemon with Provided that the
.B SIGUSR2 .Pa System.map
will cause both the static kernel symbols and the kernel module symbols to file is placed in an appropriate location the signal of generally
be reloaded. greatest usefulness is SIGUSR1. It is designed to be used to signal the
daemon when kernel modules are loaded/unloaded. Sending this signal to
Provided that the System.map file is placed in an appropriate location the the daemon after a kernel module state change will insure that proper
signal of generally greatest usefulness is the resolution of symbols will occur if a protection fault occurs in the
.B SIGUSR1 address space occupied by a kernel module.
signal. This signal is designed to be used to signal the daemon when kernel .El
modules are loaded/unloaded. Sending this signal to the daemon after a .Pp
kernel module state change will insure that proper resolution of symbols will .Sh FILES
occur if a protection fault occurs in the address space occupied by a kernel .Bl -tag -width TERM -compact
module. .It Pa /proc/kmsg
.SH FILES One source for kernel messages for
.PD 0 .Nm klogd
.TP .It Pa /var/run/klogd.pid
.I /proc/kmsg
One Source for kernel messages
.B klogd
.TP
.I /var/run/klogd.pid
The file containing the process id of The file containing the process id of
.B klogd .Nm
.TP .It Pa /boot/System.map , Pa /System.map , Pa /usr/src/linux/System.map
.I /boot/System.map, /System.map, /usr/src/linux/System.map Default locations for kernel system maps
Default locations for kernel system maps. .Ed
.PD .Sh BUGS
.SH BUGS Probably numerous. Well formed unidiffs and/or GitHub pull
Probably numerous. Well formed context diffs appreciated. requests appreciated.
.SH AUTHORS .Sh SEE ALSO
.Xr syslogd 8
.Xr syslog 2
.Xr klogctl 2
.Sh AUTHORS
The kernel log daemon The kernel log daemon
.B klogd .Nm
was originally written by Steve Lord <lord@cray.com>, Greg Wettstein was originally written by Steve Lord <lord@cray.com>, Greg Wettstein
made major improvements. Martin Schulze <joey@infodrom.org> fixed made major improvements. Martin Schulze <joey@infodrom.org> fixed some
some bugs and took over maintenance. bugs and took over maintenance. Later Joachim Nilsson, @troglobit
picked up maintenance at GitHub.

613
man/sysklogd.8
View File

@ -1,613 +0,0 @@
.\" Copyright 1994 Dr. Greg Wettstein, Enjellic Systems Development. -*- nroff -*-
.\" Copyright 2004,6-8 Martin Schulze <joey@infodrom.org>
.\" May be distributed under the GNU General Public License
.\"
.TH SYSKLOGD 8 "12 October 2019" "Version 2.0" "Linux System Administration"
.SH NAME
sysklogd \- Linux system logging utilities.
.SH SYNOPSIS
.B syslogd
.RB [ " \-4" " ] [ " \-6 " ] [ " \-A " ]"
.RB [ " \-a "
.I socket
]
.RB [ " \-d " ]
.RB [ " \-f "
.I config file
]
.RB [ " \-h " ]
.RB [ " \-l "
.I hostlist
]
.RB [ " \-m "
.I interval
]
.RB [ " \-n " ]
.RB [ " \-P "
.I pid file
]
.RB [ " \-p"
.IB socket
]
.RB [ " \-R "
.I size:count
]
.RB [ " \-r " ]
.RB [ " \-s "
.I domainlist
]
.RB [ " \-v " ]
.SH DESCRIPTION
.B Sysklogd
provides two system utilities which provide support for system logging
and kernel message trapping. Support of both internet and unix domain
sockets enables this utility package to support both local and remote
logging. The latter can optionally use RFC5424 style formatting of
messages, see
.BR syslog.conf (5)
for more information.
System logging is provided by a version of
.BR syslogd (8)
derived from the
stock BSD sources. Support for kernel logging is provided by the
.BR klogd (8)
utility which allows kernel logging to be conducted in either a
standalone fashion or as a client of syslogd.
.B Syslogd
provides a kind of logging that many modern programs use. Every logged
message contains at least a time and a hostname field, normally a
program name field, too, but that depends on how trusty the logging
program is.
While the
.B syslogd
sources have been heavily modified a couple of notes
are in order. First of all there has been a systematic attempt to
insure that syslogd follows its default, standard BSD behavior.
The second important concept to note is that this version of syslogd
interacts transparently with the version of syslog found in the
standard libraries. If a binary linked to the standard shared
libraries fails to function correctly we would like an example of the
anomalous behavior.
The main configuration file
.I /etc/syslog.conf
or an alternative file, given with the
.B "\-f"
option, is read at startup. Any lines that begin with the hash mark
(``#'') and empty lines are ignored. If an error occurs during parsing
the whole line is ignored.
.SH OPTIONS
.TP
.B "\-4"
Force
.B syslogd
to use IPv4 addresses only.
.TP
.B "\-6"
Force
.B syslogd
to use IPv6 addresses only.
.TP
.B "\-A"
Ordinarily,
.B syslogd
tries to send the message to only one address even if the host has
more than one A or AAAA record. If this option is specified,
.B syslogd
tries to send the message to all addresses.
.TP
.BI "\-a " "socket"
Using this argument you can specify additional sockets from that
.B syslogd
has to listen to. This is needed if you're going to let some daemon
run within a chroot() environment. You can use up to 19 additional
sockets. If your environment needs even more, you have to increase
the symbol
.B MAXFUNIX
within the syslogd.c source file. An example for a chroot() daemon is
described by the people from OpenBSD at
<http://www.guides.sk/psionic/dns/>.
.TP
.B "\-d"
Turns on debug mode. Using this the daemon will not proceed a
.BR fork (2)
to set itself in the background, but opposite to that stay in the
foreground and write much debug information on the current tty. See the
DEBUGGING section for more information.
.TP
.BI "\-f " "config file"
Specify an alternative configuration file instead of
.IR /etc/syslog.conf ","
which is the default.
.TP
.BI "\-h "
By default syslogd will not forward messages it receives from remote hosts.
Specifying this switch on the command line will cause the log daemon to
forward any remote messages it receives to forwarding hosts which have been
defined.
This can cause syslog loops that fill up hard disks quite fast and
thus needs to be used with caution.
.TP
.BI "\-l " "hostlist"
Specify a hostname that should be logged only with its simple hostname
and not the fqdn. Multiple hosts may be specified using the colon
(``:'') separator.
.TP
.BI "\-m " "interval"
The
.B syslogd
logs a mark timestamp regularly. The default
.I interval
between two \fI-- MARK --\fR lines is 20 minutes. This can be changed
with this option. Setting the
.I interval
to zero turns it off entirely. Depending on other log messages
generated these lines may not be written consecutively.
The \fI-- MARK --\fR message is only written if the log file hasn't
been touched in
.IR interval /2
minutes.
.TP
.B "\-n"
Avoid auto-backgrounding. This is needed especially if the
.B syslogd
is started and controlled by
.BR init (8).
.TP
.BI "\-P " "pid_file"
Specify an alternative file in which to store the process ID.
The default is
.IR /var/run/syslog.pid .
.TP
.BI "\-p " "socket"
You can specify an alternative unix domain socket instead of
.IR /dev/log "."
.TP
.BI "\-R " "size[:count]"
This option controls the max size and number of backup files kept by the
built-in log-rotation. When present on the command line it activates
log rotation of all files with the given maximum size. It is also
possible to control log rotate per log file, see
.BR syslog.conf (5)
for details.
The size argument takes optional modifiers; k, M, G. E.g., 100M is
100MB, 42k is 42 kB, etc.
The optional number of files kept include both gzipped files and the
first rotated (not zipped) file. The default for this, when omitted,
is 5.
Default: disabled.
.TP
.B "\-r"
This option will enable the facility to receive message from the
network using an internet domain socket with the syslog service (see
.BR services (5)).
The default is to not receive any messages from the network.
This option is introduced in version 1.3 of the sysklogd
package. Please note that the default behavior is the opposite of
how older versions behave, so you might have to turn this on.
.TP
.BI "\-s " "domainlist"
Specify a domainname that should be stripped off before
logging. Multiple domains may be specified using the colon (``:'')
separator.
Please be advised that no sub-domains may be specified but only entire
domains. For example if
.B "\-s north.de"
is specified and the host logging resolves to satu.infodrom.north.de
no domain would be cut, you will have to specify two domains like:
.BR "\-s north.de:infodrom.north.de" .
.TP
.B "\-v"
Print version and exit.
.SH SIGNALS
.B Syslogd
reacts to a set of signals. You may easily send a signal to
.B syslogd
using the following:
.IP
.nf
kill -SIGNAL `cat /var/run/syslogd.pid`
.fi
.PP
.TP
.B SIGHUP
This lets
.B syslogd
perform a re-initialization. All open files are closed, the
configuration file (default is
.IR /etc/syslog.conf ")"
will be reread and the
.BR syslog (3)
facility is started again.
.TP
.B SIGTERM
The
.B syslogd
will die.
.TP
.BR SIGINT ", " SIGQUIT
If debugging is enabled these are ignored, otherwise
.B syslogd
will die.
.TP
.B SIGUSR1
Switch debugging on/off. This option can only be used if
.B syslogd
is started with the
.B "\-d"
debug option.
.TP
.B SIGCHLD
Wait for childs if some were born, because of wall'ing messages.
.SH CONFIGURATION FILE SYNTAX DIFFERENCES
.B Syslogd
uses a slightly different syntax for its configuration file than
the original BSD sources. Originally all messages of a specific priority
and above were forwarded to the log file.
.IP
For example the following line caused ALL output from daemons using
the daemon facilities (debug is the lowest priority, so every higher
will also match) to go into
.IR /usr/adm/daemons :
.IP
.nf
# Sample syslog.conf
daemon.debug /usr/adm/daemons
.fi
.PP
Under the new scheme this behavior remains the same. The difference
is the addition of four new specifiers, the asterisk (\fB*\fR)
wildcard, the equation sign (\fB=\fR), the exclamation mark
(\fB!\fR), and the minus sign (\fB-\fR).
The \fB*\fR specifies that all messages for the
specified facility are to be directed to the destination. Note that
this behavior is degenerate with specifying a priority level of debug.
Users have indicated that the asterisk notation is more intuitive.
The \fB=\fR wildcard is used to restrict logging to the specified priority
class. This allows, for example, routing only debug messages to a
particular logging source.
.IP
For example the following line in
.I syslog.conf
would direct debug messages from all sources to the
.I /usr/adm/debug
file.
.IP
.nf
# Sample syslog.conf
*.=debug /usr/adm/debug
.fi
.PP
.\" The \fB!\fR as the first character of a priority inverts the above
.\" mentioned interpretation.
The \fB!\fR is used to exclude logging of the specified
priorities. This affects all (!) possibilities of specifying priorities.
.IP
For example the following lines would log all messages of the facility
mail except those with the priority info to the
.I /usr/adm/mail
file. And all messages from news.info (including) to news.crit
(excluding) would be logged to the
.I /usr/adm/news
file.
.IP
.nf
# Sample syslog.conf
mail.*;mail.!=info /usr/adm/mail
news.info;news.!crit /usr/adm/news
.fi
.PP
You may use it intuitively as an exception specifier. The above
mentioned interpretation is simply inverted. Doing that you may use
.nf
mail.none
.fi
or
.nf
mail.!*
.fi
or
.nf
mail.!debug
.fi
to skip every message that comes with a mail facility. There is much
room to play with it. :-)
The \fB-\fR may only be used to prefix a filename if you want to omit
sync'ing the file after every write to it.
This may take some acclimatization for those individuals used to the
pure BSD behavior but testers have indicated that this syntax is
somewhat more flexible than the BSD behavior. Note that these changes
should not affect standard
.BR syslog.conf (5)
files. You must specifically
modify the configuration files to obtain the enhanced behavior.
.SH SUPPORT FOR REMOTE LOGGING
These modifications provide network support to the syslogd facility.
Network support means that messages can be forwarded from one node
running syslogd to another node running syslogd where they will be
actually logged to a disk file.
To enable this you have to specify the
.B "\-r"
option on the command line. The default behavior is that
.B syslogd
won't listen to the network.
The strategy is to have syslogd listen on a unix domain socket for
locally generated log messages. This behavior will allow syslogd to
inter-operate with the syslog found in the standard C library. At the
same time syslogd listens on the standard syslog port for messages
forwarded from other hosts. To have this work correctly the
.BR services (5)
files (typically found in
.IR /etc )
must have the following
entry:
.IP
.nf
syslog 514/udp
.fi
.PP
If this entry is missing
.B syslogd
neither can receive remote messages nor send them, because the UDP
port cant be opened. Instead
.B syslogd
will die immediately, blowing out an error message.
To forward messages to to a remote host, replace the file line in the
.I syslog.conf
file with the name of the hostname to which the messages is to be sent
prepended with an @ sign. For remote logging the hostname can also be
appended with the flag ;RFC5424 to enable RFC5424 style formatting.
.IP
For example, to forward
.B ALL
messages to a remote host use the
following
.I syslog.conf
entry:
.IP
.nf
# Sample syslogd configuration file to forward all message
# messages to a remote host using RFC5424 style formatting
*.* @hostname;RFC5424
.fi
To forward all \fBkernel\fP messages to a remote host the
configuration file would be as follows:
.IP
.nf
# Sample configuration file to forward all kernel
# messages to a remote host.
kern.* @hostname
.fi
.PP
If the remote hostname cannot be resolved at startup, because the
name-server might not be accessible (it may be started after syslogd)
you don't have to worry.
.B Syslogd
will retry to resolve the name ten times and then complain. Another
possibility to avoid this is to place the hostname in
.IR /etc/hosts .
With normal
.BR syslogd s
you would get syslog-loops if you send out messages that were received
from a remote host to the same host (or more complicated to a third
host that sends it back to the first one, and so on). In my domain
(Infodrom Oldenburg) we accidently got one and our disks filled up
with the same single message. :-(
To avoid this no messages received from a
remote host are sent out to another (or the same) remote host
anymore. If you experience are setup in which you need this behaviour,
please use the
.B \-h
command line switch.
However, this option needs to be handled with caution since a syslog
loop can fill up hard disks quite fast.
If the remote host is located in the same domain as the host,
.B syslogd
is running on, only the simple hostname will be logged instead of
the whole fqdn.
In a local network you may provide a central log server to have all
the important information kept on one machine. If the network consists
of different domains you don't have to complain about logging fully
qualified names instead of simple hostnames. You may want to use the
strip-domain feature
.B \-s
of this server. You can tell the
.B syslogd
to strip off several domains other than the one the server is located
in and only log simple hostnames.
Using the
.B \-l
option there's also a possibility to define single hosts as local
machines. This, too, results in logging only their simple hostnames
and not the fqdns.
The UDP socket used to forward messages to remote hosts or to receive
messages from them is only opened when it is needed. In releases
prior to 1.3-23 it was opened every time but not opened for reading or
forwarding respectively.
.SH OUTPUT TO NAMED PIPES (FIFOs)
This version of syslogd has support for logging output to named pipes
(fifos). A fifo or named pipe can be used as a destination for log
messages by prepending a pipy symbol (``|'') to the name of the
file. This is handy for debugging. Note that the fifo must be created
with the mkfifo command before syslogd is started.
.IP
The following configuration file routes debug messages from the
kernel to a fifo:
.IP
.nf
# Sample configuration to route kernel debugging
# messages ONLY to /usr/adm/debug which is a
# named pipe.
kern.=debug |/usr/adm/debug
.fi
.LP
.SH INSTALLATION CONCERNS
There is probably one important consideration when installing this
version of syslogd. This version of syslogd is dependent on proper
formatting of messages by the syslog function. The functioning of the
syslog function in the shared libraries changed somewhere in the
region of libc.so.4.[2-4].n. The specific change was to
null-terminate the message before transmitting it to the
.I /dev/log
socket. Proper functioning of this version of syslogd is dependent on
null-termination of the message.
This problem will typically manifest itself if old statically linked
binaries are being used on the system. Binaries using old versions of
the syslog function will cause empty lines to be logged followed by
the message with the first character in the message removed.
Relinking these binaries to newer versions of the shared libraries
will correct this problem.
Both the
.BR syslogd "(8) and the " klogd (8)
can either be run from
.BR init (8)
or started as part of the rc.*
sequence. If it is started from init the option \fI\-n\fR must be set,
otherwise you'll get tons of syslog daemons started. This is because
.BR init (8)
depends on the process ID.
.SH SECURITY THREATS
There is the potential for the syslogd daemon to be
used as a conduit for a denial of service attack. Thanks go to John
Morrison (jmorriso@rflab.ee.ubc.ca) for alerting me to this potential.
A rogue program(mer) could very easily flood the syslogd daemon with
syslog messages resulting in the log files consuming all the remaining
space on the filesystem. Activating logging over the inet domain
sockets will of course expose a system to risks outside of programs or
individuals on the local machine.
There are a number of methods of protecting a machine:
.IP 1.
Implement kernel firewalling to limit which hosts or networks have
access to the 514/UDP socket.
.IP 2.
Logging can be directed to an isolated or non-root filesystem which,
if filled, will not impair the machine.
.IP 3.
The ext2 filesystem can be used which can be configured to limit a
certain percentage of a filesystem to usage by root only. \fBNOTE\fP
that this will require syslogd to be run as a non-root process.
\fBALSO NOTE\fP that this will prevent usage of remote logging since
syslogd will be unable to bind to the 514/UDP socket.
.IP 4.
Disabling inet domain sockets will limit risk to the local machine.
.IP 5.
Use step 4 and if the problem persists and is not secondary to a rogue
program/daemon get a 3.5 ft (approx. 1 meter) length of sucker rod*
and have a chat with the user in question.
Sucker rod def. \(em 3/4, 7/8 or 1in. hardened steel rod, male
threaded on each end. Primary use in the oil industry in Western
North Dakota and other locations to pump 'suck' oil from oil wells.
Secondary uses are for the construction of cattle feed lots and for
dealing with the occasional recalcitrant or belligerent individual.
.SH DEBUGGING
When debugging is turned on using
.B "\-d"
option then
.B syslogd
will be very verbose by writing much of what it does on stdout. Whenever
the configuration file is reread and re-parsed you'll see a tabular,
corresponding to the internal data structure. This tabular consists of
four fields:
.TP
.I number
This field contains a serial number starting by zero. This number
represents the position in the internal data structure (i.e. the
array). If one number is left out then there might be an error in the
corresponding line in
.IR /etc/syslog.conf .
.TP
.I pattern
This field is tricky and represents the internal structure
exactly. Every column stands for a facility (refer to
.BR syslog (3)).
As you can see, there are still some facilities left free for former
use, only the left most are used. Every field in a column represents
the priorities (refer to
.BR syslog (3)).
.TP
.I action
This field describes the particular action that takes place whenever a
message is received that matches the pattern. Refer to the
.BR syslog.conf (5)
manpage for all possible actions.
.TP
.I arguments
This field shows additional arguments to the actions in the last
field. For file-logging this is the filename for the logfile; for
user-logging this is a list of users; for remote logging this is the
hostname of the machine to log to; for console-logging this is the
used console; for tty-logging this is the specified tty; wall has no
additional arguments.
.SH FILES
.PD 0
.TP
.I /etc/syslog.conf
Configuration file for
.BR syslogd .
See
.BR syslog.conf (5)
for exact information.
.TP
.I /dev/log
The Unix domain socket to from where local syslog messages are read.
.TP
.I /var/run/syslogd.pid
The file containing the process id of
.BR syslogd .
.PD
.SH BUGS
If an error occurs in one line the whole rule is ignored.
.B Syslogd
doesn't change the filemode of opened logfiles at any stage of
process. If a file is created it is world readable. If you want to
avoid this, you have to create it and change permissions on your own.
This could be done in combination with rotating logfiles using the
.BR savelog (8)
program that is shipped in the
.B smail
3.x distribution. Remember that it might be a security hole if
everybody is able to read auth.* messages as these might contain
passwords.
.SH SEE ALSO
.BR syslog.conf (5),
.BR klogd (8),
.BR logger (1),
.BR syslog (2),
.BR syslog (3),
.BR services (5),
.BR savelog (8).
.SH AUTHORS
The system log daemon
.B syslogd
is originally taken from BSD sources, Greg Wettstein <greg@wind.enjellic.com>
performed the port to Linux, Martin Schulze <joey@infodrom.org>
fixed some bugs, added several new features and took over maintenance.

787
man/syslog.conf.5
View File

@ -1,5 +1,6 @@
.\" syslog.conf - syslogd(8) configuration file -*- nroff -*- .\" syslog.conf - syslogd(8) configuration file -*- nroff -*-
.\" Copyright (c) 1995-2009 Martin Schulze <joey@infodrom.org> .\" Copyright (c) 1995-2009 Martin Schulze <joey@infodrom.org>
.\" Copyright (c) 2018-2019 Joachim Nilsson <troglobit@gmail.com>
.\" .\"
.\" This file is part of the sysklogd package, a kernel and system log daemon. .\" This file is part of the sysklogd package, a kernel and system log daemon.
.\" .\"
@ -17,25 +18,28 @@
.\" along with this program; if not, write to the Free Software .\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA. .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA.
.\" .\"
.TH SYSLOG.CONF 5 "12 October 2019" "Version 2.0" "Linux System Administration" .Dd Oct 30, 2019
.SH NAME .Dt syslog.conf 5
syslog.conf \- syslogd(8) configuration file .Os "sysklogd (2.0)"
.SH DESCRIPTION .Sh NAME
.Nm syslog.conf
.Nd configuration file for syslogd
.Sh DESCRIPTION
The The
.I syslog.conf .Nm
file is the main configuration file for file is the main configuration file for
.BR syslogd (8) .Xr syslogd 8
which logs system messages on *nix systems. This file specifies rules which logs system messages on UNIX like systems. This file specifies
for logging. For special features see the rules for logging. For special features see the
.BR sysklogd (8) .Xr syslogd 8
manpage. man page.
.Pp
Every rule consists of two fields, a Every rule consists of two fields, a
.I selector .Em selector
field an field an
.I action .Em action
and an optional and an optional
.I logrotate .Em logrotate
field. The fields are separated by one or more spaces or tabs. The field. The fields are separated by one or more spaces or tabs. The
selector field specifies a pattern of facilities and priorities selector field specifies a pattern of facilities and priorities
belonging to the specified action. The action details where or what to belonging to the specified action. The action details where or what to
@ -44,209 +48,249 @@ files and details the max SIZE:COUNT a file can reach before it is
rotated, and later compressed. The log rotated feature is mostly rotated, and later compressed. The log rotated feature is mostly
intended for embedded systems that do not want to have cron and a intended for embedded systems that do not want to have cron and a
separate log rotate daemon. separate log rotate daemon.
.Pp
Lines starting with a hash mark (``#'') and empty lines are ignored. Lines starting with a hash mark ('#') and empty lines are ignored. If
an error occurs during parsing the whole line is ignored.
.Pp
This variant of This variant of
.B syslogd .Nm syslogd
is able to understand a slightly extended syntax compared to the is able to understand a slightly extended syntax compared to the
original BSD syslogd. original BSD
One rule may be divided .Nm syslogd .
into several lines if the leading line is terminated with an backslash One rule may be divided into several lines if the leading line ends
(``\\''). with a single backslash ('\\') character.
.SH SELECTORS .Sh SELECTORS
The selector field consists of two parts, a The selector field consists of two parts, a
.I facility .Em facility
and a and a
.IR priority , .Em priority ,
separated by a period (``.''). separated by a period ('.'). Both parts are case insensitive and can
Both parts are case insensitive and can also be specified as decimal also be specified as decimal numbers corresponding to the definitions in
numbers corresponding to the definitions in .Pa /usr/include/syslog.h .
.IR /usr/include/syslog.h . It is safer to use symbolic names rather than decimal numbers. Both
It is safer to use symbolic names rather than decimal numbers. facilities and priorities are described in
Both facilities and priorities are described in .Xr syslog 3 .
.BR syslog (3).
The names mentioned below correspond to the similar The names mentioned below correspond to the similar
.BR LOG_ -values .Ql LOG_FOO
in values in
.IR /usr/include/syslog.h . .Pa /usr/include/syslog.h .
.Pp
The The
.I facility .Em facility
is one of the following keywords: is one of the following keywords:
.BR auth ", " authpriv ", " cron ", " daemon ", " ftp ", " kern ", " lpr ", " .Bl -column "Code" "Facility" "Description" -offset indent
.BR mail ", " mark ", " news ", " security " (same as " auth "), " .It Sy "Code" Ta Sy "Facility" Ta Sy "Description"
.BR syslog ", " user ", " uucp " and " local0 " through " local7 . .It 0 Ta kern Ta Kernel log messages
The keyword .It 1 Ta user Ta User-level messages
.B security .It 2 Ta mail Ta Mail system
is deprecated and .It 3 Ta daemon Ta General system daemons
.B mark .It 4 Ta auth Ta Security/authorization messages
is only for internal use and therefore should not be used in .It 5 Ta syslog Ta Messages generated by syslogd
.It 6 Ta lpr Ta Line printer subystem
.It 7 Ta news Ta Network news subsystem
.It 8 Ta uucp Ta UNIX-to-UNIX copy
.It 9 Ta cron Ta Clock/cron daemon (BSD, Linux)
.It 10 Ta authpriv Ta Security/authorization messages (private)
.It 11 Ta ftp Ta FTP daemon
.It 12 Ta ntp Ta NTP subsystem
.It 13 Ta security Ta Log audit
.It 14 Ta console Ta Log alert
.It 15 Ta unused Ta Clock/cron daemon (Solaris)
.It 16 Ta local0 Ta Reserved for local/system use
.It 17 Ta local1 Ta Reserved for local/system use
.It 18 Ta local2 Ta Reserved for local/system use
.It 19 Ta local3 Ta Reserved for local/system use
.It 20 Ta local4 Ta Reserved for local/system use
.It 21 Ta local5 Ta Reserved for local/system use
.It 22 Ta local6 Ta Reserved for local/system use
.It 23 Ta local7 Ta Reserved for local/system use
.El
.Pp
Notice, several of the above listed facilities are not supported
by the standard C library (GLIBC, musl libc, or uClibc) on Linux.
The
.Lb libsyslog
shipped with
.Nm sysklogd ,
however, supports all the above facilities in full. Also, the keyword
.Ql mark
is only for internal use and should therefore not be used in
applications. The applications. The
.I facility .Em facility
specifies the subsystem that produced the message, e.g. all mail specifies the subsystem that produced the message, e.g. all mail
programs log with the mail facility programs log with the mail facility,
.RB ( LOG_MAIL ) .Ql LOG_MAIL ,
if they log using syslog. if they log using syslog.
.Pp
In most cases anyone can log to any facility, so we rely on convention In most cases anyone can log to any facility, so we rely on convention
for the correct facility to be chosen. However, generally only the for the correct facility to be chosen. However, generally only the
kernel can log to the "kern" facility. This is because the implementation kernel can log to the
of openlog() and syslog() in glibc does not allow logging to the "kern" .Ql kern
facility. Klogd circumvents this restriction when logging to syslogd facility. This because the implementation of
by reimplementing those functions itself. .Xr openlog 3
and
.Xr syslog 3
in GLIBC does not allow logging to the
.Ql kern
facility.
.Xr klogd 8
circumvents this restriction when logging to
.Xr syslogd 8
by using the
.Lb libsyslog
.Pp
The The
.I priority .I priority
is one of the following keywords, in ascending order: is one of the following keywords, in ascending order:
.BR debug ", " info ", " notice ", " warning ", " warn " (same as " .Bl -column "Code" "Facility" "Description" -offset indent
.BR warning "), " err ", " error " (same as " err "), " crit ", " .It Sy "Value" Ta Sy "Severity" Ta Sy "Description"
.BR alert ", " emerg ", " panic " (same as " emerg ). .It 0 Ta emergency Ta System is unusable
The keywords .It 1 Ta alert Ta Action must be taken immediately
.BR warn ", " error " and " panic .It 2 Ta critical Ta Critical condtions
are deprecated and should not be used anymore. The .It 3 Ta error Ta Error conditions
.I priority .It 4 Ta warning Ta Warning conditions
defines the severity of the message .It 5 Ta notice Ta Normal but significal conditions
.It 6 Ta info Ta Informational messages
The behavior of the original BSD syslogd is that all messages of the .It 7 Ta debug Ta Debug-level messages
specified priority and higher are logged according to the given .El
action. This .Pp
.BR syslogd (8) The default log level of most applications is
behaves the same, but has some extensions. .Ql notice ,
meaning only
In addition to the above mentioned names the .Ql notice
.BR syslogd (8) and above are forwarded to
understands the following extensions: An asterisk (``*'') stands for .Nm syslogd .
all facilities or all priorities, depending on where it is used See
(before or after the period). The keyword .Xr setlogmask 3
.B none for more information on how to change the default log level of your
application.
.Pp
In addition to the above mentioned facility and priority names,
.Xr syslogd 8
understands the following extensions:
.Pp
.Bl -tag -compact -width "'none'"
.It *
An asterisk ('*') matches all facilities or all priorities, depending on
where it is used (before or after the period).
.It none
The keyword
.Ql none
stands for no priority of the given facility. stands for no priority of the given facility.
.It ,
Multiple facilities may be specified for a single priority pattern in Multiple facilities may be specified for a single priority pattern in
one statement using the comma (``,'') operator to separate the one statement using the comma (',') operator to separate the facilities.
facilities. You may specify as many facilities as you want. You may specify as many facilities as you want. Please note that only
Please note that only the facility part from the facility part from such a statement is taken, a priority part would
such a statement is taken, a priority part would be ignored. be ignored.
.It ;
Multiple selectors may be specified for a single Multiple selectors may be specified for a single
.I action .Em action
using the semicolon (``;'') separator. Selectors are processed from using the semicolon (';') separator. Selectors are processed from left
left to right, with each selector being able to overwrite preceding ones. to right, with each selector being able to overwrite preceding ones.
Using this behavior you are able to exclude some priorities from the pattern. Using this behavior you are able to exclude some priorities from the
pattern.
This .It =
.BR syslogd (8) This version of
.Xr syslogd 8
has a syntax extension to the original BSD source, which makes its use has a syntax extension to the original BSD source, which makes its use
more intuitive. You may precede every priority with an equation sign more intuitive. You may precede every priority with an equation sign
(``='') to specify that ('=') to specify that only this single priority should be matched,
.B syslogd instead of the default: this priority and all higher priorities.
should only refer to this single priority and not this priority and .It !
all higher priorities. You may also precide the priority with an exclamation mark ('!') if you
want to ignore this priority and all higher priorities. You may even
You may also precide the priority with an exclamation mark (``!'') if use both the exclamation mark and the equation sign if you want to
you want ignore a single priority. If both extensions are used, the exclamation
.B syslogd mark must occur before the equation sign.
to ignore this priority and all higher priorities. .El
You may even use both, the exclamation mark and the equation sign if .Sh ACTIONS
you want The action field of a rule is the destination or target for a match. It
.B syslogd can be a file, a UNIX named pipe, the console, or a remote machine.
to ignore only this single priority. If you use both extensions .Ss Regular File
than the exclamation mark must occur before the equation sign, just Typically messages are logged to real files. The filename is specified
use it intuitively. with an absolute pathname.
.SH ACTIONS .Pp
The action field of a rule describes the abstract term You may prefix each entry with a minus sign ('-') to avoid syncing the
``logfile''. A ``logfile'' need not to be a real file, btw. The file after each log message. Note that you might lose information if
.BR syslogd (8) the system crashes right after a write attempt. Nevertheless this might
provides the following actions. give you back some performance, especially if you run programs that use
logging in a very verbose manner.
.SS Regular File .Ss Named Pipes
Typically messages are logged to real files.
The filename is specified with an absolute pathname.
You may prefix each entry with a minus sign (``-'') to avoid syncing
the file after each log message. Note that you might lose information if
the system crashes right after a write attempt. Nevertheless this
might give you back some performance, especially if you run programs
that use logging in a very verbose manner.
.SS Named Pipes
This version of This version of
.BR syslogd (8) .Xr syslogd 8
has support for logging output to supports logging to named pipes (FIFOs). A FIFO, or named pipe, can be
named pipes (fifos). A fifo or named pipe can be used as used as a destination for log messages by prepending a pipe symbol ('|')
a destination for log messages by prepending a pipe symbol (``|'') to to the name of the file. This can be very handy for debugging. Note
the name of the file. This is handy for debugging. Note that the fifo that the FIFO must be created with the
must be created with the .Xr mkfifo 1
.BR mkfifo (1) command before
command before .Nm syslogd
.BR syslogd (8)
is started. is started.
.Ss Terminal and Console
.SS Terminal and Console
If the file you specified is a tty, special tty-handling is done, same If the file you specified is a tty, special tty-handling is done, same
with with
.IR /dev/console . .Pa /dev/console .
.Ss Remote Machine
.SS Remote Machine Full remote logging support is available in
This .Nm syslogd ,
.BR syslogd (8) i.e. to send messages to a remote syslog server, and and to receive
provides full remote logging, i.e. is able to send messages to a messages from remote hosts. To forward messages to another host,
remote host running prepend the hostname with the at sign ('@').
.BR syslogd (8) .Pp
and to receive messages from remote hosts. The remote This feature makes it possible to collect all syslog messages in a
host won't forward the message again, it will just log them network on a central host. This reduces administration needs and
locally. To forward messages to another host, prepend the hostname can be really helpful when debugging distributed systems.
with the at sign (``@''). .Pp
Using a named pipe log method, messages from remote hosts can be sent to
Using this feature you are able to collect all syslog messages on a a log program. By reading log messages line by line such a program is
central host, if all other machines log remotely to that one. This able to sort log messages by host name or program name on the central
reduces administration needs. log host. This way it is possible to split the log into separate files.
.Pp
Using a named pipe log method, messages from remote hosts can be sent By default messages to remote remote hosts were formatted in the original
to a log program. By reading log messages line by line such a program BSD style, without timestamp or hostname. As of
is able to sort log messages by host name or program name on the .Nm syslogd
central log host. This way it is possible to split the log into v2.0 the default includes timstamp and hostname. It is also possible to
separate files. enable the new RFC5424 style formatting, append ';RFC5424' after the
hostname.
By default messages to remote remote hosts are formatted in the original .Ss List of Users
BSD style. To enable new RFC5424 style formatting, append ``;RFC5424`` Usually critical messages are also directed to
after the hostname. .Ql root
on that machine. You can specify a list of users that ought to receive
.SS List of Users the log message on their terminal by writing their usernames. You may
Usually critical messages are also directed to ``root'' on that specify more than one user by separating the usernames with commas
machine. You can specify a list of users that ought to receive the (','). Only logged in users will receive the log messages.
log message on the terminal by writing their usernames. .Ss Everyone logged on
You may specify more than one user by Emergency messages often go to all users currently online to notify them
separating the usernames with commas (``,''). If they're logged in they that something strange is happening with the system. To specify this
will receive the log messages. .Xr wall 1
feature use an asterisk ('*').
.SS Everyone logged on .Sh EXAMPLES
Emergency messages often go to all users currently online to notify This section lists some examples, partially from actual site setups.
them that something strange is happening with the system. To specify .Ss Critical
this This stores all messages of priority
.IR wall (1)-feature .Ql crit
use an asterisk (``*''). in the file
.SH EXAMPLES .Pa /var/adm/critical ,
Here are some examples, partially taken from a real existing site and with the exception of any kernel messages.
configuration. Hopefully they answer all questions about .Bd -literal -offset indent
configuring this
.BR syslogd (8) .
If not, don't hesitate to contact the mailing list.
.IP
.nf
# Store critical stuff in critical # Store critical stuff in critical
# #
*.=crit;kern.none /var/adm/critical *.=crit;kern.none /var/adm/critical
.fi .Ed
.LP .Ss Kernel
This will store all messages of priority This is an example of the 2nd selector overwriting part of the first
.B crit one. The first selector selects kernel messages of priority
in the file .Ql info
.IR /var/adm/critical , and higher. The second selector filters out kernel messages of priority
with the exception of any kernel messages. .Ql error
and higher. This leaves just priorities
.IP .Ql info ,
.nf .Ql notice ,
and
.Ql warning
to get logged.
.Bd -literal -offset indent
# Kernel messages are stored in the kernel file, # Kernel messages are stored in the kernel file,
# critical messages and higher ones also go # critical messages and higher ones also go
# to another host and to the console # to another host and to the console
@ -255,214 +299,227 @@ kern.* /var/adm/kernel
kern.crit @finlandia;RFC5424 kern.crit @finlandia;RFC5424
kern.crit /dev/console kern.crit /dev/console
kern.info;kern.!err /var/adm/kernel-info kern.info;kern.!err /var/adm/kernel-info
.fi .Ed
.LP .Pp
The first rule directs any message that has the kernel facility to the The first rule directs any message that has the kernel facility to the
file file
.IR /var/adm/kernel . .Pa /var/adm/kernel .
(But recall that only the kernel itself can log to this facility.) Recall that only the kernel itself can log to this facility.
.Pp
The second statement directs all kernel messages of priority The second statement directs all kernel messages of priority
.B crit .Ql crit
and higher to the remote host finlandia in RFC5424 style formatting. and higher to the remote host
This is useful, because if the host crashes and the disks get .Ql finlandia
irreparable errors you might not be able to read the stored messages. in RFC5424 style formatting. This is useful, because if the host
If they're on a remote host, too, you still can try to find out the crashes and the disks get irreparable errors you might not be able to
reason for the crash. read the stored messages. If they're on a remote host, too, you still
can try to find out the reason for the crash.
The third rule directs kernel messages of priority crit and higher to .Pp
the actual console, so the person who works on the machine will get The third rule directs kernel messages of priority
them, too. .Ql crit
and higher to the actual console, so the person who works on the machine
The fourth line tells the syslogd to save all kernel messages that will get them, too.
come with priorities from .Pp
.BR info " up to " warning The fourth line tells
.Nm syslogd
to save all kernel messages that come with priorities from
.Ql info
up to
.Ql warning
in the file in the file
.IR /var/adm/kernel-info . .Pa /var/adm/kernel-info .
.Ss Redirecting to a TTY
This is an example of the 2nd selector overwriting part of the first
one. The first selector selects kernel messages of priority
.BR info
and higher. The second selector filters out kernel messages of
priority
.BR error
and higher. This leaves just priorities
.BR info ", " notice " and " warning
to get logged.
.IP
.nf
# The tcp wrapper logs with mail.info, we display
# all the connections on tty12
#
mail.=info /dev/tty12
.fi
.LP
This directs all messages that use This directs all messages that use
.BR mail.info " (in source " LOG_MAIL " | " LOG_INFO ) .Ql mail.info
(in source
.Ql LOG_MAIL | LOG_INFO )
to to
.IR /dev/tty12 , .IR /dev/tty12 ,
the 12th console. For example the tcpwrapper the 12th console. For example the tcpwrapper
.BR tcpd (8) .BR tcpd (8)
uses this as its default. uses this as its default.
.Bd -literal -offset indent
.IP # The tcp wrapper logs with mail.info, we display
.nf # all the connections on tty12
#
mail.=info /dev/tty12
.Ed
.Ss Redirecting to a file
This pattern matches all messages that come with the
.Ql mail
facility, except for the
.Ql info
priority. These will be stored in the file
.Pa /var/adm/mail .
.Bd -literal -offset indent
# Write all mail related logs to a file # Write all mail related logs to a file
# #
mail.*;mail.!=info /var/adm/mail mail.*;mail.!=info /var/adm/mail
.fi .Ed
.LP .Ss Single Priority from Two Facilities
This pattern matches all messages that come with the This will extract all messages that come either with
.B mail .Ql mail.info
facility, except for the or with
.B info .Ql news.info
priority. These will be stored in the file and store them in the file
.IR /var/adm/mail . .Pa /var/adm/info .
.Bd -literal -offset indent
.IP
.nf
# Log all mail.info and news.info messages to info # Log all mail.info and news.info messages to info
# #
mail,news.=info /var/adm/info mail,news.=info /var/adm/info
.fi .Ed
.LP .Ss Advanced Filtering, part 1
This will extract all messages that come either with This logs all messages that come with either the
.BR mail.info " or with " news.info .Ql info
and store them in the file or the
.IR /var/adm/info . .Ql notice
priority into the file
.IP .Pa /var/log/messages ,
.nf except for all messages that use the
.Ql mail
facility.
.Bd -literal -offset indent
# Log info and notice messages to messages file # Log info and notice messages to messages file
# #
*.=info;*.=notice;\\ *.=info;*.=notice;\\
mail.none /var/log/messages mail.none /var/log/messages
.fi .Ed
.LP .Ss Advanced Filtering, part 2
The following is almost the same but will also log rotate and compress This statement logs all messages that come with the
aged out messages. The size argument takes the same modifiers as the .Ql info
command line '-b' option. Notice the leading '-' to ensure the file is priority to the file
flushed to disk after each message. .Pa /var/log/messages .
But any message with either
.IP .Ql mail
.nf or the
# Log all messages, including kernel, to messages file .Ql news
# rotated every 100 kB and keep up to 10 aged out and facility are not logged.
# compressed files. .Bd -literal -offset indent
*.*;kern,kern.none -/log/messages 100k:10
.fi
.LP
This lets the
.B syslogd
log all messages that come with either the
.BR info " or the " notice
priority into the file
.IR /var/log/messages ,
except for all messages that use the
.B mail
facility.
.IP
.nf
# Log info messages to messages file # Log info messages to messages file
# #
*.=info;\\ *.=info;\\
mail,news.none /var/log/messages mail,news.none /var/log/messages
.fi .Ed
.LP .Ss Wall Messages
This statement causes the This rule tells
.B syslogd .Nm syslogd
to log all messages that come with the to write all emergency messages to all currently logged in users. This
.B info is the wall action.
priority to the file .Bd -literal -offset indent
.IR /var/log/messages .
But any message coming either with the
.BR mail " or the " news
facility will not be stored.
.IP
.nf
# Emergency messages will be displayed using wall # Emergency messages will be displayed using wall
# #
*.=emerg * *.=emerg *
.fi .Ed
.LP .Ss Alerting Users
This rule tells the This rule directs all messages of priority
.B syslogd .Ql alert
to write all emergency messages to all currently logged in users. This or higher to the terminals of the operator, i.e. of the users 'root'
is the wall action. and 'joey', if they're logged in.
.Bd -literal -offset indent
.IP
.nf
# Messages of the priority alert will be directed # Messages of the priority alert will be directed
# to the operator # to the operator
# #
*.alert root,joey *.alert root,joey
.fi .Ed
.LP .Ss Log Rotation
This rule directs all messages of priority This logs all messages except kernel messages to the file
.B alert .Pa /log/messages
or higher to the terminals of the operator, i.e. of the users ``root'' without syncing ('-') the file after each log message. When the file
and ``joey'' if they're logged in. reaches 100 kiB it is rotated. In total are only 10 rotated files,
including the main file itself and compressed files kept. The size
.IP argument takes the same modifiers as the
.nf .Xr syslogd 8
*.* @finlandia;RFC5424 command line option,
.fi .Fl R .
.LP .Bd -literal -offset indent
This rule would redirect all messages to a remote host called finlandia # Log all messages, including kernel, to messages file
# rotated every 100 kB and keep up to 10 aged out and
# compressed files.
*.*;kern.none -/log/messages 100k:10
.Ed
.Ss Logging to Remote Syslog Server
This rule redirects all messages to a remote host called
.Ql finlandia
with RFC5424 style formatting. This is useful especially in a cluster with RFC5424 style formatting. This is useful especially in a cluster
of machines where all syslog messages will be stored on only one of machines where all syslog messages will be stored on only one
machine. machine.
.SH CONFIGURATION FILE SYNTAX DIFFERENCES .Bd -literal -offset indent
.B Syslogd *.* @finlandia;RFC5424
uses a slightly different syntax for its configuration file than .Ed
the original BSD sources. Originally all messages of a specific priority .Sh SYNTAX DIFFERENCES
and above were forwarded to the log file. The modifiers ``='', ``!'' .Nm syslogd
and ``-'' were added to make the allows for a slightly extended syntax for
.B syslogd .Nm
more flexible and to use it in a more intuitive manner. compared to the original BSD
.Nm syslogd .
The original BSD syslogd doesn't understand spaces as separators between The modifiers '=', '!', and '-' were added to make the syntax more
the selector and the action field. flexible and to use it in a more intuitive manner. Also, the original
.SH FILES BSD
.PD 0 .Nm syslogd
.TP doesn't understand spaces as separators between the selector and the
.I /etc/syslog.conf action field.
.Sh FILES
.Bl -tag -compact -width /etc/syslog.conf
.It /etc/syslog.conf
Configuration file for Configuration file for
.B syslogd .Xr syslogd 8
.SH BUGS .El
.Sh BUGS
The effects of multiple selectors are sometimes not intuitive. For The effects of multiple selectors are sometimes not intuitive. For
example ``mail.crit,*.err'' will select ``mail'' facility messages at example
the level of ``err'' or higher, not at the level of ``crit'' or .Ql mail.crit,*.err
higher. will select
.Ql mail
Also, if you specify a selector with an exclamation mark in it facility messages at the level of
which isn't preceded by a corresponding selector without an .Ql err
exclamation mark, nothing will be logged. Intuitively, the or higher, not at the level of
selector ``ftp.!alert'' on its own will select all ftp messages .Ql crit or higher.
with priorities less than alert. In fact it selects nothing. .Pp
Similarly ``ftp.!=alert'' might reasonably be expected to select Also, if you specify a selector with an exclamation mark in it, which
all ftp messages other than those with priority alert, but again isn't preceded by a corresponding selector without an exclamation mark,
it selects nothing. It seems the selectors with exclamation nothing will be logged. Intuitively, the selector
marks in them should only be used as `filters' following .Ql ftp.!alert
selectors without exclamation marks. on its own will select all
.Ql ftp
Finally, using a backslash to divide a line into two doesn't messages with priorities less than
work if the backslash is used immediately after the end of the .Ql alert .
selector, without intermediate whitespace. In fact it selects nothing. Similarly,
.Ql ftp.!=alert
.SH SEE ALSO might reasonably be expected to select all
.BR sysklogd (8), .Ql ftp
.BR klogd (8), messages other than those with priority
.BR logger (1), .Ql alert ,
.BR syslog (2), but again it selects nothing. It seems the selectors with exclamation
.BR syslog (3). marks in them should only be used as "filters" following selectors
.SH AUTHORS without exclamation marks.
The .Pp
.B syslogd Finally, using a backslash to divide a line into two doesn't work if the
is taken from BSD sources, Greg Wettstein <greg@wind.enjellic.com> backslash is used immediately after the end of the selector, without
performed the port to Linux, Martin Schulze <joey@infodrom.org> intermediate whitespace.
.Sh SEE ALSO
.Xr mkfifo 1 ,
.Xr sysklogd 8 ,
.Xr klogd 8 ,
.Xr logger 1 ,
.Xr syslog 2 ,
.Xr syslog 3 .
.Sh AUTHORS
The system log daemon
.Nm syslogd
is originally taken from BSD sources and later updated with new
funcitonality from
.Fx
and
.Nx .
.An -nosplit
.An Greg Wettstein Aq Mt greg@wind.enjellic.com
performed the initial port to Linux.
.An Martin Schulze Aq Mt joey@infodrom.org
fixed some bugs, added several new features and took over maintenance. fixed some bugs, added several new features and took over maintenance.
.An Joachim Nilsson Aq Mt troglobit@gmail.com
later picked up the aging
.Nm sysklogd
and gave it a home at GitHub with new features imported from
.Fx
and
.Nx .

584
man/syslogd.8
View File

@ -1 +1,583 @@
.so man8/sysklogd.8 .\" -*- nroff -*-
.\" Copyright 1994-1996 Dr. Greg Wettstein, Enjellic Systems Development.
.\" Copyright 1997-2008 Martin Schulze <joey@infodrom.org>
.\" Copyright 2018-2019 Joachim Nilsson <troglobit@gmail.com>
.\"
.\" May be distributed under the GNU General Public License
.\"
.Dd Oct 30, 2019
.Dt syslogd 8
.Os "sysklogd (2.0)"
.Sh NAME
.Nm syslogd
.Nd System Log Daemon
.Sh SYNOPSIS
.Nm
.Op Fl ?46Adhnrv
.Op Fl a Ar SOCK
.Op Fl f Ar FILE
.Op Fl l Ar HOST[:HOST]
.Op Fl m Ar MINUTES
.Op Fl P Ar FILE
.Op Fl p Ar SOCK
.Op Fl R Ar size[:count]
.Op Fl s Ar NAME[:NAME]
.Sh DESCRIPTION
.Nm
support RFC3164 and RFC5424 style log messages for both local and remote
logging using Internet and UNIX domain sockets. The companion daemon,
.Xr klogd 8 ,
is used for trapping kernel messages and events.
.Pp
.Nm
is derived from BSD sources, today
.Fx
is the reference for
.Nm
and
.Nx
for the new
.Xr syslogp 3
API, which fully supports the new features of RFC5424. Please note; 1)
the intention is to follow standard BSD
.Nm
behavior, 2) despite having a stand-alone
.Xr syslog 3 ,
and
.Xr syslogp 3
API in
.Lb libsyslog ,
this version of
.Nm
interacts transparently with the standard C library
.Xr syslog 3
API, as implemented in GLIBC, musl libc, and uClibc.
.Pp
When
.Nm
starts up it reads its main configuration file
.Pa /etc/syslog.conf ,
or an alternate file given with the
.Fl f Ar FILE
option. For details on how to configure syslog priority
(facility.severity) filtering, see
.Xr syslog.conf 5 .
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl 4
Force
.Nm
to use IPv4 addresses only.
.It Fl 6
Force
.Nm
to use IPv6 addresses only.
.It Fl A
Ordinarily,
.Nm
tries to send the message to only one address even if the host has
more than one A or AAAA record. If this option is specified,
.Nm
tries to send the message to all addresses.
.It Fl a Ar SOCK
Using this argument you can specify additional sockets from that
.Nm
has to listen to. This is needed if you're going to let some daemon
run within a
.Xr chroot 8
environment. You can use up to 19 additional sockets. If your
environment needs even more, you have to increase the symbol
.Ql MAXFUNIX
within the
.Pa syslogd.c
source file.
.It Fl d
Turns on debug mode. This implicitly enables
.Fl n
to prevent
.Nm
from backgrounding itself. Debug information is written to the current
TTY. SIGUSR1 is required to confirm continued debug messages when the
daemon has finished started up. See the
.Sx DEBUGGING
section for more information.
.It Fl f Ar FILE
Specify an alternative configuration file instead of the default
.Pa /etc/syslog.conf .
.It Fl h
By default syslogd will not forward messages it receives from remote
hosts. Specifying this switch on the command line will cause the log
daemon to forward any remote messages it receives to forwarding hosts
which have been defined. This can cause syslog loops that fill up hard
disks quite fast and thus needs to be used with caution.
.It Fl l Ar HOST
Specify a hostname that should be logged only with its simple hostname
and not the fqdn. Multiple hosts may be specified using the colon (':')
separator.
.It Fl m Ar MINUTES
.Nm
logs a mark timestamp regularly. The default interval between two
.Ql -- MARK --
lines is 20 minutes. This can be changed with this option. Setting
this to zero disables log marks entirely.
.Pp
Depending on other log messages generated these lines may not be written
consecutively. The
.Ql -- MARK --
message is only written if the log file hasn't been touched in
.Ar MINUTES / 2
minutes.
.It Fl n
Run in foreground, required when run from a modern init/supervisor. See
your system
.Xr init 8
for details.
.It Fl P Ar FILE
Specify an alternate file in which to store the process ID.
The default is
.Pa /var/run/syslog.pid .
.It Fl p Ar SOCK
Specify an alternate UNIX domain socket instead of the default
.Pa /dev/log .
.It Fl R Ar size[:count]
Enable built-in support for log rotation of files listed in
.Pa /etc/syslog.conf .
This feature is particulary useful for small and embedded systems that
do not want the overhead of
.Xr cron 8
and
.Xr logrotate 8 .
.Pp
The option controls the max size and number of backup files kept by the
built-in log-rotation. When present on the command line it activates
log rotation of all files with the given maximum size. It is also
possible to control log rotate per log file, see
.Xr syslog.conf 5
for details.
.Pp
The size argument takes optional modifiers; k, M, G. E.g., 100M is
100MB, 42k is 42 kB, etc.
.Pp
The optional number of files kept include both gzipped files and the
first rotated (not zipped) file. The default for this, when omitted,
is 5.
.It Fl r
This option enables the facility to receive message from the network
using an internet domain socket with the syslog service (see
.Xr services 5 ).
The default is to not receive any messages from the network.
.Pp
This option is introduced in version 1.3 of the
.Nm sysklogd
package. Please note that the default behavior is the opposite of how
older versions behave, so you might have to turn this on.
.It Fl s NAME
Specify domain name(s) to be stripped off before logging. Multiple
domains may be specified using the colon (':') separator. Note, no
sub-domains may be specified but only entire domains. For example if
.Fl s Ar north.de
is specified and the host logging resolves to
.Ql satu.infodrom.north.de
nothing is stripped, instead two domains must be specified:
.Fl s Ar north.de:infodrom.north.de .
.It Fl v
Print
.Nm
version and exit.
.Sh CONFIGURATION FILE SYNTAX DIFFERENCES
.Nm
uses a slightly different syntax for its configuration file than the
original BSD sources. Originally all messages of a specific priority
and above were forwarded to the log file.
.Pp
For example the following line caused ALL output from daemons using
the daemon facilities (debug is the lowest priority, so every higher
will also match) to go into
.Pa /usr/adm/daemons :
.Bd -literal -offset indent
# Sample syslog.conf
daemon.debug /usr/adm/daemons
.Ed
.Pp
Under the new scheme this behavior remains the same. The difference is
the addition of four new specifiers, the asterisk ('*') wildcard, the
equation sign ('='), the exclamation mark ('!'), and the minus sign
('-').
.Pp
The '*' specifies that all messages for the specified facility are to be
directed to the destination. Note that this behavior is degenerate with
specifying a priority level of debug. Users have indicated that the
asterisk notation is more intuitive.
.Pp
The '=' wildcard is used to restrict logging to the specified priority
class. This allows, for example, routing only debug messages to a
particular logging source.
.Pp
For example, the following line in
.Pa syslog.conf
directs debug messages from all sources to the
.Pa /usr/adm/debug
file.
.Bd -literal -offset indent
# Sample syslog.conf
*.=debug /usr/adm/debug
.Ed
.Pp
.\" The '!' as the first character of a priority inverts the above
.\" mentioned interpretation.
The '!' is used to exclude logging of the specified priorities. This
affects all (!) possibilities of specifying priorities.
.Pp
For example the following lines in
.Pa syslog.conf
log all messages of facility
.Ql mail
except those with priority
.Ql info
to the
.Pa /usr/adm/mail
file. All messages from
.Ql news.info
(including) to
.Ql news.crit
(excluding) are logged to the
.Pa /usr/adm/news
file.
.Bd -literal -offset indent
# Sample syslog.conf
mail.*;mail.!=info /usr/adm/mail
news.info;news.!crit /usr/adm/news
.Ed
.Pp
You may use it intuitively as an exception specifier. The above
mentioned interpretation is simply inverted. Doing that you may use
.Bd -literal -offset indent
mail.none
.Ed
or
.Bd -literal -offset indent
mail.!*
.Ed
or
.Bd -literal -offset indent
mail.!debug
.Ed
.Pp
to skip every message that comes with a mail facility. There is much
room to play with it. :-)
.Pp
The '-' may only be used to prefix a filename if you want to omit
sync'ing the file after every write to it.
.Pp
This may take some acclimatization for those individuals used to the
pure BSD behavior but testers have indicated that this syntax is
somewhat more flexible than the BSD behavior. Note that these changes
do not affect standard
.Xr syslog.conf 5
files. You must specifically modify the configuration files to obtain
the new features.
.Sh REMOTE LOGGING
The following modifications provide network support to the
.Nm
facility. Network support means that messages can be forwarded from one
node running
.Nm
to another node running
.Nm
where they will be actually logged to a disk file.
.Pp
This feature is enabled using the
.Fl r
option on the command line. The default behavior to not listen to
network connections.
.Pp
The strategy is to have syslogd listen on a UNIX domain socket for
locally generated log messages. This behavior will allow syslogd to
inter-operate with the syslog found in the standard C library. At the
same time syslogd listens on the standard syslog port for messages
forwarded from other hosts. To have this work correctly the
.Xr services 5
files (typically found in
.Pa /etc/servces )
must have the following entry:
.Bd -literal -offset indent
syslog 514/udp
.Ed
.Pp
If this entry is missing
.Nm
cannot receive remote messages, or send them, because the UDP port cannot
be determined. Instead
.Nm
will die immediately with an error message.
.Pp
To forward messages to to a remote host, replace the file line in the
.Pa syslog.conf
file with the name of the hostname to which the messages is to be sent
prepended with an at ('@') sign. For remote logging the hostname can
also be appended with the flag
.Ql ;RFC5424
to enable RFC5424 style formatting which includes RFC3339 timestamp and
hostname information, which is not included in the default BSD
.Nm .
.Pp
For example, to forward
.Sy ALL
messages to a remote host use the following
.Pa syslog.conf
entry:
.Bd -literal -offset indent
# Sample syslogd configuration file to forward all message
# messages to a remote host using RFC5424 style formatting
*.* @hostname;RFC5424
.Ed
.Pp
To forward all
.Ql kernel
messages to a remote host the configuration file would be as follows:
.Bd -literal -offset indent
# Sample configuration file to forward all kernel
# messages to a remote host.
kern.* @hostname
.Ed
.Pp
If the remote hostname cannot be resolved at startup, because the
name-server might not be accessible (it may be started after
.Nm ),
.Nm
will retry resolving the name ten times before logging the error.
Another possibility to avoid this is to place the hostname in
.Pa /etc/hosts .
.Pp
To avoid syslog-loops (messages that were received from a remote host
are sent back to the same host, or more complicated to a third host that
sends it back to the first one, and so on),
.Nm
by default does not forward remote messages to another remote server.
If this for some reason is required, use the
.Fl h
option on the command line. However, this option needs to be handled
with caution since a syslog loop can fill up hard disks quite fast.
.Pp
If the remote host is located in the same domain as the host,
.Nm
is running on, only the simple hostname will be logged instead of the
whole FQDN.
.Pp
In a local network you may provide a central log server to have all the
important information kept on one machine. If the network consists of
different domains, you may want to use the strip-domain feature
.Fl s .
See above.
.Pp
Using the
.Fl l
option it is possibile to define single hosts as local machines. This
also results in logging only their simple hostnames and not the FQDNs.
.Pp
The UDP socket used to forward messages to remote hosts or to receive
messages from them is only opened when it is needed. In releases
prior to 1.3-23 it was opened every time but not opened for reading or
forwarding respectively.
.Sh OUTPUT TO NAMED PIPES (FIFOs)
This version of syslogd has support for logging output to named pipes
(fifos). A FIFO or named pipe can be used as a destination for log
messages by prepending a pipy symbol ('|') to the name of the file.
This is very handy for debugging. Note, the FIFO must be created with
the
.Xr mkfifo 1
command before
.Nm
is started.
.Pp
The following configuration file routes debug messages from the kernel
to a FIFO:
.Bd -literal -offset indent
# Sample configuration to route kernel debugging
# messages ONLY to /usr/adm/debug which is a
# named pipe.
kern.=debug |/usr/adm/debug
.Ed
.Sh CONCERNS
There is probably one important consideration when installing this
version of syslogd. This version of syslogd is dependent on proper
formatting of messages by the syslog function. The functioning of the
syslog function in the shared libraries changed somewhere in the region
of libc.so.4.[2-4].n. The specific change was to null-terminate the
message before transmitting it to the
.Pa /dev/log
socket. Proper functioning of this version of
.Nm
is dependent on null-termination of the message.
.Pp
This problem will typically manifest itself if old statically linked
binaries are being used on the system. Binaries using old versions of
the syslog function will cause empty lines to be logged followed by the
message with the first character in the message removed. Relinking
these binaries to newer versions of the shared libraries will correct
this problem.
.Sh SECURITY
There is the potential for
.Nm
to be used as a conduit for a denial of service attack. Thanks go to
.An John Morrison Aq Mt jmorriso@rflab.ee.ubc.ca
for alerting the project of this. A rogue program(mer) could very
easily flood
.Nm
with syslog messages resulting in the log files consuming all the
remaining space on the filesystem. Activating logging over network
domain sockets will of course expose a system to risks outside of
programs or individuals on the local machine.
.Pp
There are a number of methods of protecting a machine:
.Bl -enum
.It
Implement kernel firewalling to limit which hosts or networks have
access to the 514/UDP socket.
.It
Logging can be directed to an isolated or non-root filesystem which,
if filled, will not impair the machine.
.It
The ext2 filesystem can be used which can be configured to limit a
certain percentage of a filesystem to usage by root only.
.Sy NOTE:
this requires
.Nm
to be run as a non-root process. Also, this prevents usage of remote
logging since
.Nm
will be unable to bind to the 514/UDP socket.
.It
Disabling inet domain sockets will limit risk to the local machine.
.El
.Sh DEBUGGING
When debug mode (
.Fl d )
is enabled
.Nm
is very verbose, writing most of what it does on stdout. Whenever
the configuration file is reread and re-parsed you'll see a tabular,
corresponding to the internal data structure. This tabular consists of
four fields:
.Pp
.Bl -tag -compact -width arguments
.It number
This field contains a serial number starting by zero. This number
represents the position in the internal data structure (i.e. the array).
If one number is left out then there might be an error in the
corresponding line in
.Pa /etc/syslog.conf .
.It pattern
This field is tricky and represents the internal structure exactly.
Every column stands for a facility, refer to
.Xr syslog 3 .
As you can see, there are still some facilities left free for former
use, only the left most are used. Every field in a column represents
the priorities, refer to
.Xr syslog 3 .
.It action
This field describes the particular action that takes place whenever a
message is received that matches the pattern. Refer to the
.Xr syslog.conf 5
manpage for all possible actions.
.It arguments
This field shows additional arguments to the actions in the last field.
For file-logging this is the filename for the logfile; for user-logging
this is a list of users; for remote logging this is the hostname of the
machine to log to; for console-logging this is the used console; for
tty-logging this is the specified tty; wall has no additional arguments.
.El
.Sh SIGNALS
.Nm
supports the following signals:
.Pp
.Bl -tag -width "TERM, QUIT" -compact
.It HUP
This lets
.Nm
perform a re-initialization. All open files are closed, the
configuration file (see above) is reread and the
.Xr syslog 3
facility is started again.
.It TERM
This tells
.Nm
to exit gracefully. Flushing any log files to disk.
.It INT, QUIT
In debug mode these are ignored. In normal operation they act as
SIGTERM.
.It USR1
In debug mode this switches debugging on/off. In normal operation
it is ignored.
.El
.Pp
For convenience the PID is, by default, stored in
.Pa /var/run/syslogd.pid .
Example usage:
.Bd -literal -offset indent
kill -SIGNAL `cat /var/run/syslogd.pid`
.Ed
.Sh FILES
.Bl -tag -width TERM -compact
.It Pa /etc/syslog.conf
Configuration file for
.Nm .
See
.Xr syslog.conf 5
for more information.
.It Pa /dev/log
The UNIX domain socket to from where local syslog messages are read.
.It Pa /var/run/syslogd.pid
The file containing the process id of
.Nm .
.El
.Sh BUGS
As mentioned in the
.Sx DESCRIPTION ,
.Nm
transparently supports the standard C library
.Xr syslog 3
API. If a binary linked to the standard C libraries do not operate
correctly, this should be reported as a bug to this project. See below
for contact details.
.Pp
.Nm
doesn't change the file mode of opened log files at any stage. If a
file is created it is world readable. If you want to avoid this, you
have to create it and change permissions on your own. This could be
done in combination with rotating logfiles using the
.Xr savelog 8
program that is shipped in the
.Nm smail
3.x distribution. Remember that it might be a security hole if
everybody is able to read
.Ql auth.*
messages as these might contain passwords.
.Sh SEE ALSO
.Xr syslog.conf 5 ,
.Xr klogd 8 ,
.Xr logger 1 ,
.Xr syslog 2 ,
.Xr syslog 3 ,
.Xr services 5 ,
.Xr savelog 8 .
.Sh AUTHORS
The system log daemon
.Nm
is originally taken from BSD sources and later updated with new
funcitonality from
.Fx
and
.Nx .
.An -nosplit
.An Greg Wettstein Aq Mt greg@wind.enjellic.com
performed the initial port to Linux.
.An Martin Schulze Aq Mt joey@infodrom.org
fixed some bugs, added several new features and took over maintenance.
.An Joachim Nilsson Aq Mt troglobit@gmail.com
later picked up the aging
.Nm sysklogd
and gave it a home at GitHub with new features imported from
.Fx
and
.Nx .