xref: /openbsd-src/usr.sbin/syslogd/syslogd.8 (revision 3b624d28064dd5cfdad0a0e01978a6bf6857fe75)
1.\"	$OpenBSD: syslogd.8,v 1.61 2022/06/16 18:44:43 bluhm Exp $
2.\"
3.\" Copyright (c) 1983, 1986, 1991, 1993
4.\"	The Regents of the University of California.  All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\" 3. Neither the name of the University nor the names of its contributors
15.\"    may be used to endorse or promote products derived from this software
16.\"    without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
30.\"     from: @(#)syslogd.8	8.1 (Berkeley) 6/6/93
31.\"	$NetBSD: syslogd.8,v 1.3 1996/01/02 17:41:48 perry Exp $
32.\"
33.Dd $Mdocdate: June 16 2022 $
34.Dt SYSLOGD 8
35.Os
36.Sh NAME
37.Nm syslogd
38.Nd log system messages
39.Sh SYNOPSIS
40.Nm syslogd
41.Bk -words
42.Op Fl 46dFhnruVZ
43.Op Fl a Ar path
44.Op Fl C Ar CAfile
45.Op Fl c Ar cert_file
46.Op Fl f Ar config_file
47.Op Fl K Ar CAfile
48.Op Fl k Ar key_file
49.Op Fl m Ar mark_interval
50.Op Fl p Ar log_socket
51.Op Fl S Ar listen_address
52.Op Fl s Ar reporting_socket
53.Op Fl T Ar listen_address
54.Op Fl U Ar bind_address
55.Ek
56.Sh DESCRIPTION
57.Nm
58writes system messages to log files or a user's terminal.
59Output can be sent to other programs
60for further processing.
61It can also securely send and receive log messages
62to and from remote hosts.
63.Pp
64The options are as follows:
65.Bl -tag -width Ds
66.It Fl 4
67Forces
68.Nm
69to use only IPv4 addresses for UDP.
70.It Fl 6
71Forces
72.Nm
73to use only IPv6 addresses for UDP.
74.It Fl a Ar path
75Specify a location where
76.Nm
77should place an additional log socket.
78The primary use for this is to place additional log sockets in
79.Pa /dev/log
80of various chroot filespaces, though the need for these is
81less urgent after the introduction of
82.Xr sendsyslog 2 .
83.It Fl C Ar CAfile
84PEM encoded file containing CA certificates used for certificate
85validation of a remote loghost;
86the default is
87.Pa /etc/ssl/cert.pem .
88.It Fl c Ar cert_file
89PEM encoded file containing the client certificate for TLS connections
90to a remote loghost.
91The default is not to use a client certificate for the outgoing connection
92to a syslog server.
93This option has to be used together with
94.Fl k Ar key_file .
95.It Fl d
96Enable debugging to the standard output,
97and do not disassociate from the controlling terminal.
98.It Fl F
99Run in the foreground instead of disassociating from the controlling
100terminal and running as a background daemon.
101.It Fl f Ar config_file
102Specify the pathname of an alternate configuration file;
103the default is
104.Pa /etc/syslog.conf .
105.It Fl h
106Include the hostname when sending messages to a remote loghost.
107.It Fl K Ar CAfile
108PEM encoded file containing CA certificates used for client certificate
109validation on the local listen socket.
110By default incoming connections from any TLS client are allowed.
111.It Fl k Ar key_file
112PEM encoded file containing the client private key for TLS connections
113to a remote loghost.
114This option has to be used together with
115.Fl c Ar cert_file .
116.It Fl m Ar mark_interval
117Select the number of minutes between
118.Dq mark
119messages; the default is 20 minutes.
120.It Fl n
121Print source addresses numerically rather than symbolically.
122This saves an address-to-name lookup for each incoming message,
123which can be useful when combined with the
124.Fl u
125option on a loghost with no DNS cache.
126Messages from the local host will still be logged with
127the symbolic local host name.
128.It Fl p Ar log_socket
129Specify the pathname of an alternate log socket to be used instead;
130the default is
131.Pa /dev/log .
132.It Fl r
133Print duplicate lines immediately and suppress the "last message
134repeated" summary when piping to another program or forwarding to
135a remote loghost.
136If given twice, this is done for all log actions.
137.It Fl S Ar listen_address
138Create a TLS listen socket for receiving encrypted messages and
139bind it to the specified address.
140A port number may be specified using the
141.Ar host : Ns Ar port
142syntax.
143The first
144.Ar listen_address
145is also used to find a suitable server key and certificate in
146.Pa /etc/ssl/ .
147.It Fl s Ar reporting_socket
148Specify path to a UNIX-domain
149socket for use in reporting logs stored in memory buffers using
150.Xr syslogc 8 .
151.It Fl T Ar listen_address
152Create a TCP listen socket for receiving messages and bind it to
153the specified address.
154There is no well-known port for syslog over TCP, so a port number
155must be specified using the
156.Ar host : Ns Ar port
157syntax.
158.It Fl U Ar bind_address
159Create a UDP socket for receiving messages and bind it to the
160specified address.
161This can be used, for example, with a pf divert-to rule to receive
162packets when
163.Nm
164is bound to localhost.
165A port number may be specified using the
166.Ar host : Ns Ar port
167syntax.
168.It Fl u
169Select the historical
170.Dq insecure
171mode, in which
172.Nm
173will accept input from the UDP port.
174Some software wants this, but you can be subjected to a variety of
175attacks over the network, including attackers remotely filling logs.
176.It Fl V
177Do not perform remote server certificate and hostname validation
178when sending messages.
179.It Fl Z
180Generate timestamps in ISO format.
181This includes the year and the timezone, and all logging is done
182in UTC.
183.El
184.Pp
185The options
186.Fl a , S , T ,
187and
188.Fl U
189can be given more than once to specify multiple input sources.
190.Pp
191When starting up,
192.Nm
193reads its configuration file,
194.Xr syslog.conf 5 ,
195and opens the configured logfiles and TCP and TLS connections.
196The logfiles already have to exist with the correct permissions.
197When receiving a
198.Dv SIGHUP
199signal, it closes all open logfiles and outgoing TCP and TLS
200connections and re-runs this initialization sequence.
201Sending this signal is required both after editing the configuration
202file and after log rotation.
203.Pp
204.Nm
205opens a UDP socket, as specified
206in
207.Pa /etc/services ,
208for sending forwarded messages.
209By default all incoming data on this socket is discarded.
210If insecure mode is switched on with
211.Fl u ,
212it will also read messages from the socket.
213.Nm
214also opens and reads messages from the
215.Ux Ns -domain
216socket
217.Pa /dev/log ,
218and from the special device
219.Pa /dev/klog
220(to read kernel messages),
221and from
222.Xr sendsyslog 2
223(to read messages from userland processes).
224.Pp
225The message sent to
226.Nm
227should consist of a single line.
228Embedded new line characters are converted to spaces;
229binary data is encoded by
230.Xr vis 3 ,
231but no backslash is inserted.
232The message can contain a priority code, which should be a preceding
233decimal number in angle braces, for example,
234.Dq <5> .
235This priority code should map into the priorities defined in the
236include file
237.In sys/syslog.h .
238.Pp
239When sending syslog messages to a remote loghost via TLS, the
240server's certificate and hostname are validated to prevent malicious
241servers from reading messages.
242If the server has a certificate with a matching hostname signed by
243a CA in
244.Pa /etc/ssl/cert.pem ,
245it is verified with that by default.
246If the server has a certificate with a matching hostname signed by
247a private CA, use the
248.Fl C
249option and put that CA into
250.Ar CAfile .
251Validation can be explicitly turned off using the
252.Fl V
253option.
254If the server is accepting messages only from clients with a trusted
255client certificate, use the
256.Fl k
257and
258.Fl c
259options to authenticate
260.Nm
261with this certificate.
262.Pp
263When receiving syslog messages from a TLS client, there must be
264a server key and certificate in
265.Pa /etc/ssl/private/host Ns Oo : Ns Ar port Oc Ns Ar .key
266and
267.Pa /etc/ssl/host Ns Oo : Ns Ar port Oc Ns Ar .crt .
268If the client uses certificates to authenticate, the CA of the
269client's certificate may be added to
270.Ar CAfile
271using the
272.Fl K
273option to protect from messages being spoofed by malicious senders.
274.Sh FILES
275.Bl -tag -width /var/run/syslog.pid -compact
276.It Pa /dev/log
277Name of the
278.Ux Ns -domain
279datagram log socket.
280.It Pa /dev/klog
281Kernel log device.
282.It Pa /etc/ssl/
283Private keys and public certificates.
284.It Pa /etc/syslog.conf
285Configuration file.
286.It Pa /var/run/syslog.pid
287Process ID of current
288.Nm .
289.El
290.Sh SEE ALSO
291.Xr logger 1 ,
292.Xr syslog 3 ,
293.Xr services 5 ,
294.Xr syslog.conf 5 ,
295.Xr newsyslog 8 ,
296.Xr syslogc 8
297.Sh HISTORY
298The
299.Nm
300command appeared in
301.Bx 4.3 .
302.Sh CAVEATS
303.Nm
304does not create files,
305it only logs to existing ones.
306