xref: /freebsd/usr.sbin/syslogd/syslogd.8 (revision c2aed5122b7eae69a9d98d7e35ad0ec3098b869d)
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.\" 4. 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.\" $FreeBSD$
30.\"
31.Dd November 8, 2004
32.Dt SYSLOGD 8
33.Os
34.Sh NAME
35.Nm syslogd
36.Nd log systems messages
37.Sh SYNOPSIS
38.Nm
39.Op Fl 46Acdknosuv
40.Op Fl a Ar allowed_peer
41.Op Fl b Ar bind_address
42.Op Fl f Ar config_file
43.Oo
44.Fl l Op Ar mode: Ns
45.Ar path
46.Oc
47.Op Fl m Ar mark_interval
48.Op Fl P Ar pid_file
49.Op Fl p Ar log_socket
50.Sh DESCRIPTION
51The
52.Nm
53utility reads and logs messages to the system console, log files, other
54machines and/or users as specified by its configuration file.
55.Pp
56The options are as follows:
57.Bl -tag -width indent
58.It Fl 4
59Force
60.Nm
61to use IPv4 addresses only.
62.It Fl 6
63Force
64.Nm
65to use IPv6 addresses only.
66.It Fl A
67Ordinarily,
68.Nm
69tries to send the message to only one address
70even if the host has more than one A or AAAA record.
71If this option is specified,
72.Nm
73tries to send the message to all addresses.
74.It Fl a Ar allowed_peer
75Allow
76.Ar allowed_peer
77to log to this
78.Nm
79using UDP datagrams.
80Multiple
81.Fl a
82options may be specified.
83.Pp
84.Ar Allowed_peer
85can be any of the following:
86.Bl -tag -width "ipaddr/masklen[:service]XX"
87.It Xo
88.Sm off
89.Ar ipaddr
90.No / Ar masklen
91.Op : Ar service
92.Sm on
93.Xc
94Accept datagrams from
95.Ar ipaddr
96(in the usual dotted quad notation) with
97.Ar masklen
98bits being taken into account when doing the address comparison.
99.Ar ipaddr
100can be also IPv6 address by enclosing the address with
101.Ql \&[
102and
103.Ql \&] .
104If specified,
105.Ar service
106is the name or number of an UDP service (see
107.Xr services 5 )
108the source packet must belong to.
109A
110.Ar service
111of
112.Ql \&*
113allows packets being sent from any UDP port.
114The default
115.Ar service
116is
117.Ql syslog .
118If
119.Ar ipaddr
120is IPv4 address, a missing
121.Ar masklen
122will be substituted by the historic class A or class B netmasks if
123.Ar ipaddr
124belongs into the address range of class A or B, respectively, or
125by 24 otherwise.
126If
127.Ar ipaddr
128is IPv6 address, a missing
129.Ar masklen
130will be substituted by 128.
131.It Xo
132.Sm off
133.Ar domainname Op : Ar service
134.Sm on
135.Xc
136Accept datagrams where the reverse address lookup yields
137.Ar domainname
138for the sender address.
139The meaning of
140.Ar service
141is as explained above.
142.It Xo
143.Sm off
144.No * Ar domainname Op : Ar service
145.Sm on
146.Xc
147Same as before, except that any source host whose name
148.Em ends
149in
150.Ar domainname
151will get permission.
152.El
153.Pp
154The
155.Fl a
156options are ignored if the
157.Fl s
158option is also specified.
159.It Fl b Ar bind_address
160Specify one specific IP address or hostname to bind to.
161If a hostname is specified,
162the IPv4 or IPv6 address which corresponds to it is used.
163.It Fl c
164Disable the compression of repeated instances of the same line
165into a single line of the form
166.Dq Li "last message repeated N times"
167when the output is a pipe to another program.
168If specified twice, disable this compression in all cases.
169.It Fl d
170Put
171.Nm
172into debugging mode.
173This is probably only of use to developers working on
174.Nm .
175.It Fl f
176Specify the pathname of an alternate configuration file;
177the default is
178.Pa /etc/syslog.conf .
179.It Fl k
180Disable the translation of
181messages received with facility
182.Dq kern
183to facility
184.Dq user .
185Usually the
186.Dq kern
187facility is reserved for messages read directly from
188.Pa /dev/klog .
189.It Fl m
190Select the number of minutes between
191.Dq mark
192messages; the default is 20 minutes.
193.It Fl n
194Disable dns query for every request.
195.It Fl o
196Prefix kernel messages with the full kernel boot file as determined by
197.Xr getbootfile 3 .
198Without this, the kernel message prefix is always
199.Dq Li kernel: .
200.It Fl p
201Specify the pathname of an alternate log socket to be used instead;
202the default is
203.Pa /var/run/log .
204.It Fl P
205Specify an alternative file in which to store the process ID.
206The default is
207.Pa /var/run/syslog.pid .
208.It Fl l
209Specify a location where
210.Nm
211should place an additional log socket.
212The primary use for this is to place additional log sockets in
213.Pa /var/run/log
214of various chroot filespaces.
215File permissions for socket can be specified in octal representation
216before socket name, delimited with a colon.
217Path to socket location must be absolute.
218.It Fl s
219Operate in secure mode.
220Do not log messages from remote machines.
221If
222specified twice, no network socket will be opened at all, which also
223disables logging to remote machines.
224.It Fl u
225Unique priority logging.
226Only log messages at the specified priority.
227Without this option, messages at the stated priority or higher are logged.
228This option changes the default comparison from
229.Dq =>
230to
231.Dq = .
232.It Fl v
233Verbose logging.
234If specified once, the numeric facility and priority are
235logged with each locally-written message.
236If specified more than once,
237the names of the facility and priority are logged with each locally-written
238message.
239.El
240.Pp
241The
242.Nm
243utility reads its configuration file when it starts up and whenever it
244receives a hangup signal.
245For information on the format of the configuration file,
246see
247.Xr syslog.conf 5 .
248.Pp
249The
250.Nm
251utility reads messages from the
252.Ux
253domain sockets
254.Pa /var/run/log
255and
256.Pa /var/run/logpriv ,
257from an Internet domain socket specified in
258.Pa /etc/services ,
259and from the special device
260.Pa /dev/klog
261(to read kernel messages).
262.Pp
263The
264.Nm
265utility creates its process ID file,
266by default
267.Pa /var/run/syslog.pid ,
268and stores its process
269ID there.
270This can be used to kill or reconfigure
271.Nm .
272.Pp
273The message sent to
274.Nm
275should consist of a single line.
276The message can contain a priority code, which should be a preceding
277decimal number in angle braces, for example,
278.Sq Aq 5 .
279This priority code should map into the priorities defined in the
280include file
281.In sys/syslog.h .
282.Pp
283For security reasons,
284.Nm
285will not append to log files that do not exist;
286therefore, they must be created manually before running
287.Nm .
288.Sh FILES
289.Bl -tag -width /var/run/syslog.pid -compact
290.It Pa /etc/syslog.conf
291configuration file
292.It Pa /var/run/syslog.pid
293default process ID file
294.It Pa /var/run/log
295name of the
296.Ux
297domain datagram log socket
298.It Pa /var/run/logpriv
299.Ux
300socket for priveleged applications
301.It Pa /dev/klog
302kernel log device
303.El
304.Sh SEE ALSO
305.Xr logger 1 ,
306.Xr syslog 3 ,
307.Xr services 5 ,
308.Xr syslog.conf 5 ,
309.Xr newsyslog 8
310.Sh HISTORY
311The
312.Nm
313utility appeared in
314.Bx 4.3 .
315.Pp
316The
317.Fl a ,
318.Fl s ,
319.Fl u ,
320and
321.Fl v
322options are
323.Fx 2.2
324extensions.
325.Sh BUGS
326The ability to log messages received in UDP packets is equivalent to
327an unauthenticated remote disk-filling service, and should probably be
328disabled by default.
329Some sort of
330.No inter- Ns Nm syslogd
331authentication mechanism ought to be worked out.
332To prevent the worst
333abuse, use of the
334.Fl a
335option is therefore highly recommended.
336.Pp
337The
338.Fl a
339matching algorithm doesn't pretend to be very efficient; use of numeric
340IP addresses is faster than domain name comparison.
341Since the allowed
342peer list is being walked linearly, peer groups where frequent messages
343are being anticipated from should be put early into the
344.Fl a
345list.
346.Pp
347The log socket was moved from
348.Pa /dev
349to ease the use of a read-only root file system.
350This may confuse
351some old binaries so that a symbolic link might be used for a
352transitional period.
353