From 1d5c71c6d90eb0d05ac6f10fa5bc0c2da9c3b688 Mon Sep 17 00:00:00 2001 From: Joachim Nilsson Date: Sat, 7 Dec 2019 12:36:14 +0100 Subject: [PATCH] man: Adapt FreeBSD syslogd.8 to the flags and history of sysklogd - Much less command line options (for now) - Mention support for RFC3164 and RFC5424 - Add the history of the sysklogd project Signed-off-by: Joachim Nilsson --- man/syslogd.8 | 409 +++++++++++++++++++++----------------------------- 1 file changed, 175 insertions(+), 234 deletions(-) diff --git a/man/syslogd.8 b/man/syslogd.8 index 0e11697..a3ab864 100644 --- a/man/syslogd.8 +++ b/man/syslogd.8 @@ -36,24 +36,87 @@ .Nd log systems messages .Sh SYNOPSIS .Nm -.Op Fl 468ACcdFHkNnosTuv -.Op Fl a Ar allowed_peer -.Op Fl b Ar bind_address -.Op Fl f Ar config_file -.Op Fl l Oo Ar mode Ns \&: Oc Ns Ar path -.Op Fl m Ar mark_interval -.Op Fl O Ar format -.Op Fl P Ar pid_file -.Op Fl p Ar log_socket -.Op Fl S Ar logpriv_socket +.Op Fl ?46AdFknsTv +.Op Fl a Ar addr[/len][:port] +.Op Fl a Ar name[:port] +.Op Fl b Ar addr[:port] +.Op Fl b Ar :port +.Op Fl f Ar file +.Op Fl m Ar interval +.Op Fl P Ar file +.Op Fl p Ar sock +.Op Fl r Ar size[:count] .Sh DESCRIPTION The .Nm -utility reads and logs messages to the system console, -log files, -other +utility reads and logs messages to the system console, log files, other machines and/or users as specified by its configuration file. .Pp +.Nm +support RFC3164 and RFC5424 style log messages for both local and remote +logging using Internet and UNIX domain sockets. Differences in style is +shown below. +.Pp +.Bl -tag -compact -width "RFC3164:" +.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 +Note, for remote logging the messages are prefixed with +.Cm +or +.Cm 1 , +respectively. +.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 , +.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 +By default, +.Nm +reads messages from the +.Ux +domain socket +.Pa /dev/log , +from an Internet domain socket specified in +.Pa /etc/services , +and from +.Pa /proc/kmsg +.Pq to read kernel messages . +The command line options defined below can be used to change this +behavior. +.Pp The options are as follows: .Bl -tag -width indent .It Fl 4 @@ -90,89 +153,54 @@ 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 allowed_peer -Allow -.Ar allowed_peer -to log to this -.Nm -using UDP datagrams. -Multiple +.It Fl a Ar address[/len][:service] | Fl a Ar domainname[:service] +Allow peers to log to this syslogd using UDP datagrams. Multiple .Fl a -options may be specified. +options may be specified. Any +.Fl a +option is ignored if the +.Fl s +option is also specified. .Pp -The -.Ar allowed_peer -option may be any of the following: -.Bl -tag -width "ipaddr[/prefixlen][:service]XX" -.It Xo -.Sm off -.Ar ipaddr -.Op / Ar masklen -.Op \&: Ar service -.Pp -.Ar ipaddr -.Op / Ar prefixlen -.Op \&: Ar service -.Sm on -.Xc -Accept datagrams from -.Ar ipaddr , -.Ar ipaddr -can be specified as an IPv4 address or as an IPv6 -address enclosed with -.Ql \&[ +The peer argument may be any of the following: +.Bl -tag -width 'address[/len][:service]' +.It Ql address[/len][:service] +Accept datagrams from IP +.Ar address , +which can be specified as an IPv4 address or as an IPv6 address enclosed +with +.Sq \&[ and -.Ql \&] . -If specified, -.Ar service -is the name or number of an UDP service (see +.Sq \&] . +If specified, service is the name or port number of an UDP service (see .Xr services 5 ) -the source packet must belong to. -A -.Ar service -of -.Ql \&* -accepts UDP packets from any source port. -The default -.Ar service -is +the source packet must belong to. A service of +.Ql * +accepts UDP packets from any source port. The default service is .Ql syslog . If -.Ar ipaddr -is IPv4 address, a missing -.Ar masklen +.Ar address +is an IPv4 address, a missing prefix +.Ar len will be substituted by the historic class A or class B netmasks if -.Ar ipaddr -belongs into the address range of class A or B, -respectively, -or by 24 otherwise. -If -.Ar ipaddr -is IPv6 address, -a missing -.Ar masklen +.Ar address +belongs in the address range of class A or B, respectively, or by' +.Ar /24 +otherwise. If +.Ar address +is an IPv6 address, a missing prefix +.Ar len will be substituted by 128. -.It Xo -.Sm off -.Ar domainname Op \&: Ar service -.Sm on -.Xc +.It Ql domainname[:service] Accept datagrams where the reverse address lookup yields .Ar domainname -for the sender address. -The meaning of +for the sender address. The meaning of .Ar service is as explained above. .Ar domainname can contain special characters of a shell-style pattern such as -.Ql Li \&* . +.Ql * . .El -.Pp -The -.Fl a -options are ignored if the -.Fl s -option is also specified. .It Xo .Fl b .Sm off @@ -198,16 +226,6 @@ is .Ql syslog . This option can be specified multiple times to bind to multiple addresses and/or ports. -.It Fl C -Create log files that do not exist -.Pq permission is set to Ql Li 0600 . -.It Fl c -Disable the compression of repeated instances of the same line -into a single line of the form -.Dq Li "last message repeated N times" -when the output is a pipe to another program. -If specified twice, -disable this compression in all cases. .It Fl d Put .Nm @@ -230,9 +248,6 @@ and to run .Nm , and wants to monitor when and how it exits. -.It Fl H -When logging remote messages use hostname from the message (if supplied) -instead of using address from which the message was received. .It Fl k Disable the translation of messages received with facility @@ -242,47 +257,18 @@ to facility Usually the .Dq kern facility is reserved for messages read directly from -.Pa /dev/klog . +.Pa /proc/kmsg . .It Fl m Ar mark_interval Select the number of minutes between .Dq mark messages; the default is 20 minutes. -.It Fl N -Disable binding on UDP sockets. -RFC 3164 recommends that outgoing -.Nm -messages should originate from the privileged port, -this option -.Em disables -the recommended behavior. -This option inherits -.Fl s . .It Fl n Disable DNS query for every request. -.It Fl O Ar format -Select the output format of generated log messages. -The values -.Ar bsd -and -.Ar rfc3164 -are used to generate RFC 3164 log messages. -The values -.Ar syslog -and -.Ar rfc5424 -are used to generate RFC 5424 log messages, -having RFC 3339 timestamps with microsecond precision. -The default is to generate RFC 3164 log messages. -.It Fl o -Prefix kernel messages with the full kernel boot file as determined by -.Xr getbootfile 3 . -Without this, the kernel message prefix is always -.Dq Li kernel: . .It Fl p Ar log_socket Specify the pathname of an alternate log socket to be used instead; the default is -.Pa /var/run/log . +.Pa /dev/log . When a single .Fl p option is specified, @@ -295,63 +281,24 @@ the remaining pathnames are treated as additional log sockets. Specify an alternative file in which to store the process ID. The default is .Pa /var/run/syslog.pid . -.It Fl S Ar logpriv_socket -Specify the pathname of an alternate log socket for privileged -applications to be used instead; -the default is -.Pa /var/run/logpriv . -When a single -.Fl S -option is specified, -the default pathname is replaced with the specified one. -When two or more -.Fl S -options are specified, -the remaining pathnames are treated as additional log sockets. -.It Fl l Oo Ar mode Ns \&: Oc Ns Ar path -Specify a location where -.Nm -should place an additional log socket. -The primary use for this is to place additional log sockets in -.Pa /var/run/log -of various chroot filespaces. -File permissions for socket can be specified in octal representation in -.Ar mode , -delimited with a colon. -The socket location must be specified as an absolute pathname in -.Ar path . .It Fl s -Operate in secure mode. -Do not log messages from remote machines. -If specified twice, -no network socket will be opened at all, -which also disables logging to remote machines. +Operate in secure mode. Do not log messages from remote machines. If +specified twice, no network socket will be opened at all, which also +disables logging to remote machines. .It Fl T Always use the local time and date for messages received from the network, instead of the timestamp field supplied in the message by the remote host. This is useful if some of the originating hosts cannot keep time properly or are unable to generate a correct timestamp. -.It Fl u -Unique priority logging. -Only log messages at the specified priority. -Without this option, -messages at the stated priority or higher are logged. -This option changes the default comparison from -.Dq => -to -.Dq = . .It Fl v -Verbose logging. -If specified once, -the numeric facility and priority are -logged with each locally-written message. -If specified more than once, -the names of the facility and priority are logged with each locally-written -message. +Verbose logging. If specified once, the numeric facility and priority +are logged with each locally-written message. If specified more than +once, the names of the facility and priority are logged with each +locally-written message. .Pp -This option only affects the formatting of RFC 3164 messages. -Messages formatted according to RFC 5424 always include a -facility/priority number. +This option only affects the formatting of RFC 3164 messages. Messages +formatted according to RFC 5424 always include a facility/priority +number. .El .Pp The @@ -364,92 +311,93 @@ see .Pp The .Nm -utility reads messages from the -.Ux -domain sockets -.Pa /var/run/log -and -.Pa /var/run/logpriv , -from an Internet domain socket specified in -.Pa /etc/services , -and from the special device -.Pa /dev/klog -.Pq to read kernel messages . -.Pp -The -.Nm utility creates its process ID file, by default .Pa /var/run/syslog.pid , -and stores its process -ID there. -This can be used to kill or reconfigure +and stores its process ID there. This can be used to kill or +reconfigure .Nm . .Pp The message sent to .Nm -should consist of a single line. -The message can contain a priority code, -which should be a preceding -decimal number in angle braces, -for example, +should consist of a single line. The message can contain a priority +code, which should be a preceding decimal number in angle braces, for +example, .Sq Aq 5 . This priority code should map into the priorities defined in the include file .In sys/syslog.h . +To log with RFC5424 style messages the priority code must be directly +followed by the version number, this is all handled by the +.Lb libsyslog , +which is the +.Nx +.Xr syslogp 3 +API included with the +.Nm sysklogd +project. .Pp -For security reasons, -.Nm -will not append to log files that do not exist -.Po unless Fl C -option is specified -.Pc ; -therefore, they must be created manually before running -.Nm . -.Pp -The date and time are taken from the received message. -If the format of the timestamp field is incorrect, -time obtained from the local host is used instead. -This can be overridden by the +The date and time are taken from the received message. If the format of +the timestamp field is incorrect, time obtained from the local host is +used instead. This can be overridden by the .Fl T flag. .Sh FILES -.Bl -tag -width /var/run/syslog.pid -compact +.Bl -tag -width /etc/syslog.d/50-default.conf -compact .It Pa /etc/syslog.conf -configuration file +configuration file. See +.Xr syslog.conf 5 +for more information. +.It Pa /etc/syslog.d/*.conf +Conventional sub-directory of +.Pa .conf +files read by +.Nm . +.It Pa /etc/syslog.d/50-default.conf +Conventional name for default rules. .It Pa /var/run/syslog.pid default process ID file -.It Pa /var/run/log +.It Pa /dev/log name of the .Ux domain datagram log socket -.It Pa /var/run/logpriv -.Ux -socket for privileged applications -.It Pa /dev/klog +.It Pa /proc/kmsg kernel log device .El .Sh SEE ALSO .Xr logger 1 , .Xr syslog 3 , +.Xr syslogp 3 , .Xr services 5 , .Xr syslog.conf 5 , -.Xr newsyslog 8 .Sh HISTORY The .Nm -utility appeared in +utility first appeared in .Bx 4.3 . .Pp -The -.Fl a , -.Fl s , -.Fl u , -and -.Fl v -options are -.Fx 2.2 -extensions. +It was originally ported to Linux by +.An Greg Wettstein Aq Mt greg@wind.enjellic.com +and the project was renamed +.Nm sysklogd +when a separate log daemon, +.Nm klogd , +for Linux kernel messages was added. It was +the default +.Nm +in Debian and Ubuntu, maintained by +.An Martin Schulze Aq Mt joey@infodrom.org , +who fixed some bugs and added several new features. When Debian replaced +.Nm sysklogd +with +.Nm rsyslogd +the project was abandoned. In 2018 +.An Joachim Nilsson Aq Mt troglobit@gmail.com +picked up maintenance. In 2019 the project was revived with fresh DNA +strands from both FreeBSD and NetBSD, +.Nm klogd +was removed and the project was eventually relicensed under the 3-clause +BSD license, like its bretheren. .Sh BUGS The ability to log messages received in UDP packets is equivalent to an unauthenticated remote disk-filling service, @@ -471,10 +419,3 @@ peer groups where frequent messages are being anticipated from should be put early into the .Fl a list. -.Pp -The log socket was moved from -.Pa /dev -to ease the use of a read-only root file system. -This may confuse -some old binaries so that a symbolic link might be used for a -transitional period.