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_man5_MANS = syslog.conf.5
dist_man8_MANS = syslogd.8 klogd.8 sysklogd.8
dist_man8_MANS = syslogd.8 klogd.8

677
man/klogd.8
View File

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

789
man/syslog.conf.5
View File

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