diff --git a/man/Makefile.am b/man/Makefile.am index 4cb66b7..85b8e47 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -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 diff --git a/man/klogd.8 b/man/klogd.8 index 8261590..2400b82 100644 --- a/man/klogd.8 +++ b/man/klogd.8 @@ -1,143 +1,140 @@ -.\" Copyright 1994-6 Dr. Greg Wettstein, Enjellic Systems Development. -*- nroff -*- -.\" Copyright 1997-2007 Martin Schulze +.\" -*- nroff -*- +.\" Copyright 1994-1996 Dr. Greg Wettstein, Enjellic Systems Development. +.\" Copyright 1997-2007 Martin Schulze +.\" Copyright 2018-2019 Joachim Nilsson +.\" .\" 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 , Greg Wettstein -made major improvements. Martin Schulze fixed -some bugs and took over maintenance. +made major improvements. Martin Schulze fixed some +bugs and took over maintenance. Later Joachim Nilsson, @troglobit +picked up maintenance at GitHub. diff --git a/man/sysklogd.8 b/man/sysklogd.8 deleted file mode 100644 index 4597511..0000000 --- a/man/sysklogd.8 +++ /dev/null @@ -1,613 +0,0 @@ -.\" Copyright 1994 Dr. Greg Wettstein, Enjellic Systems Development. -*- nroff -*- -.\" Copyright 2004,6-8 Martin Schulze -.\" 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 -. -.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 -performed the port to Linux, Martin Schulze -fixed some bugs, added several new features and took over maintenance. diff --git a/man/syslog.conf.5 b/man/syslog.conf.5 index 4e119a2..af9f6a7 100644 --- a/man/syslog.conf.5 +++ b/man/syslog.conf.5 @@ -1,5 +1,6 @@ .\" syslog.conf - syslogd(8) configuration file -*- nroff -*- .\" Copyright (c) 1995-2009 Martin Schulze +.\" Copyright (c) 2018-2019 Joachim Nilsson .\" .\" 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 -performed the port to Linux, Martin Schulze +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 . diff --git a/man/syslogd.8 b/man/syslogd.8 index d5ef84b..17f1f01 100644 --- a/man/syslogd.8 +++ b/man/syslogd.8 @@ -1 +1,583 @@ -.so man8/sysklogd.8 +.\" -*- nroff -*- +.\" Copyright 1994-1996 Dr. Greg Wettstein, Enjellic Systems Development. +.\" Copyright 1997-2008 Martin Schulze +.\" Copyright 2018-2019 Joachim Nilsson +.\" +.\" 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 .