xref: /freebsd/usr.sbin/syslogd/syslogd.8 (revision 22d7dd834bc5cd189810e414701e3ad1e98102e4)
1.\" Copyright (c) 1983, 1986, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\"     @(#)syslogd.8	8.1 (Berkeley) 6/6/93
29.\"
30.Dd July 2, 2018
31.Dt SYSLOGD 8
32.Os
33.Sh NAME
34.Nm syslogd
35.Nd log systems messages
36.Sh SYNOPSIS
37.Nm
38.Op Fl 468ACcdFHkNnosTuv
39.Op Fl a Ar allowed_peer
40.Op Fl b Ar bind_address
41.Op Fl f Ar config_file
42.Op Fl l Oo Ar mode Ns \&: Oc Ns Ar path
43.Op Fl M Ar fwd_length
44.Op Fl m Ar mark_interval
45.Op Fl O Ar format
46.Op Fl P Ar pid_file
47.Op Fl p Ar log_socket
48.Op Fl S Ar logpriv_socket
49.Sh DESCRIPTION
50The
51.Nm
52utility reads and logs messages to the system console,
53log files,
54other
55machines and/or users as specified by its configuration file.
56.Pp
57The options are as follows:
58.Bl -tag -width indent
59.It Fl 4
60Force
61.Nm
62to use IPv4 addresses only.
63.It Fl 6
64Force
65.Nm
66to use IPv6 addresses only.
67.It Fl 8
68Tells
69.Nm
70not to interfere with 8-bit data.
71Normally
72.Nm
73will replace C1 control characters
74.Pq ISO 8859 and Unicode characters
75with their
76.Dq M- Ns Em x
77equivalent.
78Note, this option does not change the way
79.Nm
80alters control characters
81.Pq see Xr iscntrl 3 .
82They will always be replaced with their
83.Dq ^ Ns Em x
84equivalent.
85.It Fl A
86Ordinarily,
87.Nm
88tries to send the message to only one address
89even if the host has more than one A or AAAA record.
90If this option is specified,
91.Nm
92tries to send the message to all addresses.
93.It Fl a Ar allowed_peer
94Allow
95.Ar allowed_peer
96to log to this
97.Nm
98using UDP datagrams.
99Multiple
100.Fl a
101options may be specified.
102.Pp
103The
104.Ar allowed_peer
105option may be any of the following:
106.Bl -tag -width "ipaddr[/prefixlen][:service]XX"
107.It Xo
108.Sm off
109.Ar ipaddr
110.Op / Ar masklen
111.Op \&: Ar service
112.Pp
113.Ar ipaddr
114.Op / Ar prefixlen
115.Op \&: Ar service
116.Sm on
117.Xc
118Accept datagrams from
119.Ar ipaddr ,
120.Ar ipaddr
121can be specified as an IPv4 address or as an IPv6
122address enclosed with
123.Ql \&[
124and
125.Ql \&] .
126If specified,
127.Ar service
128is the name or number of an UDP service (see
129.Xr services 5 )
130the source packet must belong to.
131A
132.Ar service
133of
134.Ql \&*
135accepts UDP packets from any source port.
136The default
137.Ar service
138is
139.Ql syslog .
140If
141.Ar ipaddr
142is IPv4 address, a missing
143.Ar masklen
144will be substituted by the historic class A or class B netmasks if
145.Ar ipaddr
146belongs into the address range of class A or B,
147respectively,
148or by 24 otherwise.
149If
150.Ar ipaddr
151is IPv6 address,
152a missing
153.Ar masklen
154will be substituted by 128.
155.It Xo
156.Sm off
157.Ar domainname Op \&: Ar service
158.Sm on
159.Xc
160Accept datagrams where the reverse address lookup yields
161.Ar domainname
162for the sender address.
163The meaning of
164.Ar service
165is as explained above.
166.Ar domainname
167can contain special characters of a shell-style pattern such as
168.Ql Li \&* .
169.El
170.Pp
171The
172.Fl a
173options are ignored if the
174.Fl s
175option is also specified.
176.It Xo
177.Fl b
178.Sm off
179.Ar bind_address Op \&: Ar service
180.Sm on
181.Xc
182.It Xo
183.Fl b
184.Sm off
185.Li \&: Ar service
186.Sm on
187.Xc
188Bind to a specific address and/or port.
189The address can be specified as a hostname,
190and the port as a service name.
191If an IPv6 address is specified, it should be enclosed with
192.Ql \&[
193and
194.Ql \&] .
195The default
196.Ar service
197is
198.Ql syslog .
199This option can be specified multiple times to bind to
200multiple addresses and/or ports.
201.It Fl C
202Create log files that do not exist
203.Pq permission is set to Ql Li 0600 .
204.It Fl c
205Disable the compression of repeated instances of the same line
206into a single line of the form
207.Dq Li "last message repeated N times"
208when the output is a pipe to another program.
209If specified twice,
210disable this compression in all cases.
211.It Fl d
212Put
213.Nm
214into debugging mode.
215This is probably only of use to developers working on
216.Nm .
217.It Fl f Ar config_file
218Specify the pathname of an alternate configuration file;
219the default is
220.Pa /etc/syslog.conf .
221.It Fl F
222Run
223.Nm
224in the foreground,
225rather than going into daemon mode.
226This is useful if some other process uses
227.Xr fork 2
228and
229.Xr exec 3
230to run
231.Nm ,
232and wants to monitor when and how it exits.
233.It Fl H
234When logging remote messages use hostname from the message (if supplied)
235instead of using address from which the message was received.
236.It Fl k
237Disable the translation of
238messages received with facility
239.Dq kern
240to facility
241.Dq user .
242Usually the
243.Dq kern
244facility is reserved for messages read directly from
245.Pa /dev/klog .
246.It Fl M Ar fwd_length
247Set the limit on the length of forwarded messages.
248The minimum is 480 octets.
249The maximum for RFC 3164 output format is 1024 octets.
250The default is 1024 octets.
251.It Fl m Ar mark_interval
252Select the number of minutes between
253.Dq mark
254messages;
255the default is 20 minutes.
256.It Fl N
257Disable binding on UDP sockets.
258RFC 3164 recommends that outgoing
259.Nm
260messages should originate from the privileged port,
261this option
262.Em disables
263the recommended behavior.
264This option inherits
265.Fl s .
266.It Fl n
267Disable DNS query for every request.
268.It Fl O Ar format
269Select the output format of generated log messages.
270The values
271.Ar bsd
272and
273.Ar rfc3164
274are used to generate RFC 3164 log messages.
275The values
276.Ar syslog
277and
278.Ar rfc5424
279are used to generate RFC 5424 log messages,
280having RFC 3339 timestamps with microsecond precision.
281The default is to generate RFC 3164 log messages.
282.It Fl o
283Prefix kernel messages with the full kernel boot file as determined by
284.Xr getbootfile 3 .
285Without this, the kernel message prefix is always
286.Dq Li kernel: .
287.It Fl p Ar log_socket
288Specify the pathname of an alternate log socket to be used instead;
289the default is
290.Pa /var/run/log .
291When a single
292.Fl p
293option is specified,
294the default pathname is replaced with the specified one.
295When two or more
296.Fl p
297options are specified,
298the remaining pathnames are treated as additional log sockets.
299.It Fl P Ar pid_file
300Specify an alternative file in which to store the process ID.
301The default is
302.Pa /var/run/syslog.pid .
303.It Fl S Ar logpriv_socket
304Specify the pathname of an alternate log socket for privileged
305applications to be used instead;
306the default is
307.Pa /var/run/logpriv .
308When a single
309.Fl S
310option is specified,
311the default pathname is replaced with the specified one.
312When two or more
313.Fl S
314options are specified,
315the remaining pathnames are treated as additional log sockets.
316.It Fl l Oo Ar mode Ns \&: Oc Ns Ar path
317Specify a location where
318.Nm
319should place an additional log socket.
320The primary use for this is to place additional log sockets in
321.Pa /var/run/log
322of various chroot filespaces.
323File permissions for socket can be specified in octal representation in
324.Ar mode ,
325delimited with a colon.
326The socket location must be specified as an absolute pathname in
327.Ar path .
328.It Fl s
329Operate in secure mode.
330Do not log messages from remote machines.
331If specified twice,
332no network socket will be opened at all,
333which also disables logging to remote machines.
334.It Fl T
335Always use the local time and date for messages received from the network,
336instead of the timestamp field supplied in the message by the remote host.
337This is useful if some of the originating hosts cannot keep time properly
338or are unable to generate a correct timestamp.
339.It Fl u
340Unique priority logging.
341Only log messages at the specified priority.
342Without this option,
343messages at the stated priority or higher are logged.
344This option changes the default comparison from
345.Dq =>
346to
347.Dq = .
348.It Fl v
349Verbose logging.
350If specified once,
351the numeric facility and priority are
352logged with each locally-written message.
353If specified more than once,
354the names of the facility and priority are logged with each locally-written
355message.
356.Pp
357This option only affects the formatting of RFC 3164 messages.
358Messages formatted according to RFC 5424 always include a
359facility/priority number.
360.El
361.Pp
362The
363.Nm
364utility reads its configuration file when it starts up and whenever it
365receives a hangup signal.
366For information on the format of the configuration file,
367see
368.Xr syslog.conf 5 .
369.Pp
370The
371.Nm
372utility reads messages from the
373.Ux
374domain sockets
375.Pa /var/run/log
376and
377.Pa /var/run/logpriv ,
378from an Internet domain socket specified in
379.Pa /etc/services ,
380and from the special device
381.Pa /dev/klog
382.Pq to read kernel messages .
383.Pp
384The
385.Nm
386utility creates its process ID file,
387by default
388.Pa /var/run/syslog.pid ,
389and stores its process
390ID there.
391This can be used to kill or reconfigure
392.Nm .
393.Pp
394The message sent to
395.Nm
396should consist of a single line.
397The message can contain a priority code,
398which should be a preceding
399decimal number in angle braces,
400for example,
401.Sq Aq 5 .
402This priority code should map into the priorities defined in the
403include file
404.In sys/syslog.h .
405.Pp
406For security reasons,
407.Nm
408will not append to log files that do not exist
409.Po unless Fl C
410option is specified
411.Pc ;
412therefore, they must be created manually before running
413.Nm .
414.Pp
415The date and time are taken from the received message.
416If the format of the timestamp field is incorrect,
417time obtained from the local host is used instead.
418This can be overridden by the
419.Fl T
420flag.
421.Sh FILES
422.Bl -tag -width /var/run/syslog.pid -compact
423.It Pa /etc/syslog.conf
424configuration file
425.It Pa /var/run/syslog.pid
426default process ID file
427.It Pa /var/run/log
428name of the
429.Ux
430domain datagram log socket
431.It Pa /var/run/logpriv
432.Ux
433socket for privileged applications
434.It Pa /dev/klog
435kernel log device
436.El
437.Sh SEE ALSO
438.Xr logger 1 ,
439.Xr syslog 3 ,
440.Xr services 5 ,
441.Xr syslog.conf 5 ,
442.Xr newsyslog 8
443.Sh HISTORY
444The
445.Nm
446utility appeared in
447.Bx 4.3 .
448.Pp
449The
450.Fl a ,
451.Fl s ,
452.Fl u ,
453and
454.Fl v
455options are
456.Fx 2.2
457extensions.
458.Sh BUGS
459The ability to log messages received in UDP packets is equivalent to
460an unauthenticated remote disk-filling service,
461and should probably be disabled by default.
462Some sort of
463.No inter- Ns Nm syslogd
464authentication mechanism ought to be worked out.
465To prevent the worst abuse,
466use of the
467.Fl a
468option is therefore highly recommended.
469.Pp
470The
471.Fl a
472matching algorithm does not pretend to be very efficient;
473use of numeric IP addresses is faster than domain name comparison.
474Since the allowed peer list is being walked linearly,
475peer groups where frequent messages are being anticipated
476from should be put early into the
477.Fl a
478list.
479.Pp
480The log socket was moved from
481.Pa /dev
482to ease the use of a read-only root file system.
483This may confuse
484some old binaries so that a symbolic link might be used for a
485transitional period.
486