diff --git a/man/syslog.conf.5 b/man/syslog.conf.5 index 50bd429..d777849 100644 --- a/man/syslog.conf.5 +++ b/man/syslog.conf.5 @@ -28,7 +28,7 @@ .\" @(#)syslog.conf.5 8.1 (Berkeley) 6/9/93 .\" $FreeBSD$ .\" -.Dd November 1, 2016 +.Dd December 9, 2019 .Dt SYSLOG.CONF 5 .Os .Sh NAME @@ -41,32 +41,83 @@ The .Nm file is the configuration file for the .Xr syslogd 8 -program. -It consists of -blocks of lines separated by -.Em program -and -.Em hostname -specifications (separations appear alone on their lines), -with each line containing two fields: the +program. It consists of lines of rules for logging, with each line +containing at least two fields: the .Em selector field which specifies the types of messages and priorities to which the line applies, and an .Em action field which specifies the action to be taken if a message .Xr syslogd 8 -receives matches the selection criteria. +receives matches the selection criteria. A rule may also have an +.Em option +field for a setting that applies only to that rule. +.Pp +The fields are separated by one or more tab characters or spaces. A +rule may be divided into several lines if the leading line ends with a +single backslash ('\\') character. +.Pp +.Bd -literal -offset indent +RULE := SELECTOR ACTION [;OPTION] +SELECTOR := [SELECTOR;]facility[,facility].[!=]severity +ACTION := /path/to/file + |= |/path/to/named/pipe + |= @remote[.host.tld][:PORT] +OPTION := [OPTION,] + |= RFC3164 + |= RFC5424 + |= rotate=SIZE:COUNT +.Ed +.Pp The .Em selector -field is separated from the +field specifies a pattern of facilities and priorities belonging to the +specified action. The .Em action -field by one or more tab characters or spaces. +details where or what to do with the selected input. The +.Em option +field, which must start with the semi-colon option delimiter (';'), +currently supports log formatting and log rotation. The default log +format is the traditional RFC3164 (included here for completeness), +.Sy except +for remote syslog targets where the BSD format (without both timestamp +and hostname) is the default. The user must explicitly set RFC3164 on +a remote logging target. RFC5424 is the newest format with RFC3339 time +stamps, msgid, structured data, and more. The BSD format cannot be set, +it is only the default for remote targets for compatibility reasons. +.Pp +.Bl -tag -compact -width "RFC3164:" +.It BSD: +.Cm myproc[8710]: Kilroy was here. +.It RFC3164: +.Cm Aug 24 05:14:15 192.0.2.1 myproc[8710]: Kilroy was here. +.It RFC5424: +.Cm 2003-08-24T05:14:15.000003-07:00 192.0.2.1 myproc 8710 - - Kilroy was here. +.El +.Pp +The log rotation, which is only relevant for files, details the max +.Ar SIZE:COUNT +a file can reach before it is rotated, and later compressed. This +feature is mostly intended for embedded systems that do not want to have +cron or a separate log rotate daemon. +.Pp +Comments, lines starting with a hash mark ('#'), and empty lines are +ignored. If an error occurs during parsing the whole line is ignored. .Pp A special .Em include -keyword can be used to include all files with names ending in '.conf' and not -beginning with a '.' contained in the directory following the keyword. -This keyword can only be used in the first level configuration file. +keyword can be used to include all files with names ending in '.conf' +and not beginning with a '.' contained in the directory following the +keyword. This keyword can only be used in the first level configuration +file. The included example +.Pa /etc/syslog.conf +has the following at the end: +.Bd -literal -offset indent +# +# Drop your subsystem .conf file in /etc/syslog.d/ +# +include /etc/syslog.d/*.conf +.Ed .Pp Note that if you use spaces as separators, your .Nm @@ -79,361 +130,209 @@ This change however preserves backwards compatibility with the old style of .Nm (i.e., tab characters only). -.Pp -The -.Em selectors -are encoded as a -.Em facility , -a period -.Pq Dq \&. , -an optional set of comparison flags -.Pq Oo \&! Oc Op <=> , -and a -.Em level , -with no intervening white-space. -Both the +.Sh SELECTORS +The selector field consists of two parts, a .Em facility -and the -.Em level -are case insensitive. +and a +.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 syslogp 3 . +The names mentioned below correspond to the similar +.Ql LOG_FOO +values in +.Pa /usr/include/syslog.h . .Pp The .Em facility -describes the part of the system generating the message, and is one of -the following keywords: -.Cm auth , authpriv , console , cron , daemon , ftp , kern , lpr , -.Cm mail , mark , news , ntp , security , syslog , user , uucp , -and -.Cm local0 -through -.Cm local7 . -These keywords (with the exception of mark) correspond to -similar -.Dq Dv LOG_ -values specified to the +is one of the following keywords: +.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 subsystem +.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 +.Em facility +specifies the subsystem that produced the message, e.g. all 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 +.Ql kern +facility. This because the implementation of .Xr openlog 3 and .Xr syslog 3 -library routines. +in GLIBC does not allow logging to the +.Ql kern +facility. .Pp The -.Em comparison flags -may be used to specify exactly what is logged. -The default comparison is -.Dq => -(or, if you prefer, -.Dq >= ) , -which means that messages from the specified -.Em facility -list, and of a priority -level equal to or greater than -.Em level -will be logged. -Comparison flags beginning with -.Dq Li \&! -will have their logical sense inverted. -Thus -.Dq !=info -means all levels except info and -.Dq !notice -has the same meaning as -.Dq