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 <troglobit@gmail.com>

man/syslogd.8

@@ -36,24 +36,87 @@
 .Nd log systems messages
 .Sh SYNOPSIS
 .Nm
-.Op Fl 468ACcdFHkNnosTuv
+.Op Fl ?46AdFknsTv
-.Op Fl a Ar allowed_peer
+.Op Fl a Ar addr[/len][:port]
-.Op Fl b Ar bind_address
+.Op Fl a Ar name[:port]
-.Op Fl f Ar config_file
+.Op Fl b Ar addr[:port]
-.Op Fl l Oo Ar mode Ns \&: Oc Ns Ar path
+.Op Fl b Ar :port
-.Op Fl m Ar mark_interval
+.Op Fl f Ar file
-.Op Fl O Ar format
+.Op Fl m Ar interval
-.Op Fl P Ar pid_file
+.Op Fl P Ar file
-.Op Fl p Ar log_socket
+.Op Fl p Ar sock
-.Op Fl S Ar logpriv_socket
+.Op Fl r Ar size[:count]
 .Sh DESCRIPTION
 The
 .Nm
-utility reads and logs messages to the system console,
+utility reads and logs messages to the system console, log files, other
-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 <PRI>
+or
+.Cm <PRI>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
+.It Fl a Ar address[/len][:service] | Fl a Ar domainname[:service]
-Allow
+Allow peers to log to this syslogd using UDP datagrams.  Multiple
-.Ar allowed_peer
-to log to this
-.Nm
-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
+The peer argument may be any of the following:
-.Ar allowed_peer
+.Bl -tag -width 'address[/len][:service]'
-option may be any of the following:
+.It Ql address[/len][:service]
-.Bl -tag -width "ipaddr[/prefixlen][:service]XX"
+Accept datagrams from IP
-.It Xo
+.Ar address ,
-.Sm off
+which can be specified as an IPv4 address or as an IPv6 address enclosed
-.Ar ipaddr
+with
-.Op / Ar masklen
+.Sq \&[
-.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 \&[
 and
-.Ql \&] .
+.Sq \&] .
-If specified,
+If specified, service is the name or port number of an UDP service (see
-.Ar service
-is the name or number of an UDP service (see
 .Xr services 5 )
-the source packet must belong to.
+the source packet must belong to.  A service of
-A
+.Ql *
-.Ar service
+accepts UDP packets from any source port.  The default service is
-of
-.Ql \&*
-accepts UDP packets from any source port.
-The default
-.Ar service
-is
 .Ql syslog .
 If
-.Ar ipaddr
+.Ar address
-is IPv4 address, a missing
+is an IPv4 address, a missing prefix
-.Ar masklen
+.Ar len
 will be substituted by the historic class A or class B netmasks if
-.Ar ipaddr
+.Ar address
-belongs into the address range of class A or B,
+belongs in the address range of class A or B, respectively, or by'
-respectively,
+.Ar /24
-or by 24 otherwise.
+otherwise.  If
-If
+.Ar address
-.Ar ipaddr
+is an IPv6 address, a missing prefix
-is IPv6 address,
+.Ar len
-a missing
-.Ar masklen
 will be substituted by 128.
-.It Xo
+.It Ql domainname[:service]
-.Sm off
-.Ar domainname Op \&: Ar service
-.Sm on
-.Xc
 Accept datagrams where the reverse address lookup yields
 .Ar domainname
-for the sender address.
+for the sender address.  The meaning of
-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.
+Operate in secure mode.  Do not log messages from remote machines.  If
-Do not log messages from remote machines.
+specified twice, no network socket will be opened at all, which also
-If specified twice,
+disables logging to remote machines.
-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.
+Verbose logging.  If specified once, the numeric facility and priority
-If specified once,
+are logged with each locally-written message.  If specified more than
-the numeric facility and priority are
+once, the names of the facility and priority are logged with each
-logged with each locally-written message.
+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.
+This option only affects the formatting of RFC 3164 messages.  Messages
-Messages formatted according to RFC 5424 always include a
+formatted according to RFC 5424 always include a facility/priority
-facility/priority number.
+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
+and stores its process ID there.  This can be used to kill or
-ID there.
+reconfigure
-This can be used to kill or reconfigure
 .Nm .
 .Pp
 The message sent to
 .Nm
-should consist of a single line.
+should consist of a single line.  The message can contain a priority
-The message can contain a priority code,
+code, which should be a preceding decimal number in angle braces, for
-which should be a preceding
+example,
-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,
+The date and time are taken from the received message.  If the format of
-.Nm
+the timestamp field is incorrect, time obtained from the local host is
-will not append to log files that do not exist
+used instead.  This can be overridden by the
-.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
 .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
+.It Pa /proc/kmsg
-.Ux
-socket for privileged applications
-.It Pa /dev/klog
 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
+It was originally ported to Linux by
-.Fl a ,
+.An Greg Wettstein Aq Mt greg@wind.enjellic.com
-.Fl s ,
+and the project was renamed
-.Fl u ,
+.Nm sysklogd
-and
+when a separate log daemon,
-.Fl v
+.Nm klogd ,
-options are
+for Linux kernel messages was added.  It was
-.Fx 2.2
+the default
-extensions.
+.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.