usr.sbin/syslogd/syslogd.8

   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. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)syslogd.8   8.1 (Berkeley) 6/6/93
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd November 24, 2001
  36 .Dt SYSLOGD 8
  37 .Os
  38 .Sh NAME
  39 .Nm syslogd
  40 .Nd log systems messages
  41 .Sh SYNOPSIS
  42 .Nm
  43 .Op Fl 46Adknosuv
  44 .Op Fl a Ar allowed_peer
  45 .Op Fl b Ar bind_address
  46 .Op Fl f Ar config_file
  47 .Op Fl m Ar mark_interval
  48 .Op Fl p Ar log_socket
  49 .Op Fl P Ar pid_file
  50 .Op Fl l Ar path
  51 .Sh DESCRIPTION
  52 The
  53 .Nm
  54 daemon reads and logs messages to the system console, log files, other
  55 machines and/or users as specified by its configuration file.
  56 .Pp
  57 The options are as follows:
  58 .Bl -tag -width indent
  59 .It Fl 4
  60 Forces
  61 .Nm
  62 to use IPv4 addresses only.
  63 .It Fl 6
  64 Forces
  65 .Nm
  66 to use IPv6 addresses only.
  67 .It Fl A
  68 Ordinarily,
  69 .Nm
  70 tries to send the message to only one address
  71 even if the host has more than one A or AAAA record.
  72 If this option is specified,
  73 .Nm
  74 tries to send the message to all addresses.
  75 .It Fl a Ar allowed_peer
  76 Allow
  77 .Ar allowed_peer
  78 to log to this
  79 .Nm
  80 using UDP datagrams.  Multiple
  81 .Fl a
  82 options may be specified.
  83 .Pp
  84 .Ar Allowed_peer
  85 can 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
  94 Accept datagrams from
  95 .Ar ipaddr
  96 (in the usual dotted quad notation) with
  97 .Ar masklen
  98 bits being taken into account when doing the address comparison.
  99 .Ar ipaddr
 100 can be also IPv6 address by enclosing the address with
 101 .Ql \&[
 102 and
 103 .Ql \&] .
 104 If specified,
 105 .Ar service
 106 is the name or number of an UDP service (see
 107 .Xr services 5 )
 108 the source packet must belong to.  A
 109 .Ar service
 110 of
 111 .Ql \&*
 112 allows packets being sent from any UDP port.  The default
 113 .Ar service
 114 is
 115 .Ql syslog .
 116 If
 117 .Ar ipaddr
 118 is IPv4 address, a missing
 119 .Ar masklen
 120 will be substituted by the historic class A or class B netmasks if
 121 .Ar ipaddr
 122 belongs into the address range of class A or B, respectively, or
 123 by 24 otherwise.  If
 124 .Ar ipaddr
 125 is IPv6 address, a missing
 126 .Ar masklen
 127 will be substituted by 128.
 128 .It Xo
 129 .Sm off
 130 .Ar domainname Op : Ar service
 131 .Sm on
 132 .Xc
 133 Accept datagrams where the reverse address lookup yields
 134 .Ar domainname
 135 for the sender address.  The meaning of
 136 .Ar service
 137 is as explained above.
 138 .It Xo
 139 .Sm off
 140 .No * Ar domainname Op : Ar service
 141 .Sm on
 142 .Xc
 143 Same as before, except that any source host whose name
 144 .Em ends
 145 in
 146 .Ar domainname
 147 will get permission.
 148 .El
 149 .Pp
 150 The
 151 .Fl a
 152 options are ignored if the
 153 .Fl s
 154 option is also specified.
 155 .It Fl b Ar bind_address
 156 Specify one specific IP address or hostname to bind to.
 157 If a hostname is specified,
 158 the IPv4 or IPv6 address which corresponds to it is used.
 159 .It Fl d
 160 Put
 161 .Nm
 162 into debugging mode.  This is probably only of use to developers working on
 163 .Nm .
 164 .It Fl f
 165 Specify the pathname of an alternate configuration file;
 166 the default is
 167 .Pa /etc/syslog.conf .
 168 .It Fl k
 169 Disable the translation of
 170 messages received with facility
 171 .Dq kern
 172 to facility
 173 .Dq user .
 174 Usually the
 175 .Dq kern
 176 facility is reserved for messages read directly from
 177 .Pa /dev/klog .
 178 .It Fl m
 179 Select the number of minutes between
 180 .Dq mark
 181 messages; the default is 20 minutes.
 182 .It Fl n
 183 Disable dns query for every request.
 184 .It Fl o
 185 Prefix kernel messages with the full kernel boot file as determined by
 186 .Xr getbootfile 3 .
 187 Without this, the kernel message prefix is always
 188 .Dq Li kernel: .
 189 .It Fl p
 190 Specify the pathname of an alternate log socket to be used instead;
 191 the default is
 192 .Pa /var/run/log .
 193 .It Fl P
 194 Specify an alternative file in which to store the process ID.
 195 The default is
 196 .Pa /var/run/syslog.pid .
 197 .It Fl l
 198 Specify a location where
 199 .Nm
 200 should place an additional log socket.
 201 Up to 19 additional logging sockets can be specified.
 202 The primary use for this is to place additional log sockets in
 203 .Pa /var/run/log
 204 of various chroot filespaces.
 205 .It Fl s
 206 Operate in secure mode.  Do not log messages from remote machines.  If
 207 specified twice, no network socket will be opened at all, which also
 208 disables logging to remote machines.
 209 .It Fl u
 210 Unique priority logging.  Only log messages at the specified priority.
 211 Without this option, messages at the stated priority or higher are logged.
 212 This option changes the default comparison from
 213 .Dq =>
 214 to
 215 .Dq = .
 216 .It Fl v
 217 Verbose logging.  If specified once, the numeric facility and priority are
 218 logged with each locally-written message.  If specified more than once,
 219 the names of the facility and priority are logged with each locally-written
 220 message.
 221 .El
 222 .Pp
 223 The
 224 .Nm
 225 daemon reads its configuration file when it starts up and whenever it
 226 receives a hangup signal.
 227 For information on the format of the configuration file,
 228 see
 229 .Xr syslog.conf 5 .
 230 .Pp
 231 The
 232 .Nm
 233 daemon reads messages from the
 234 .Tn UNIX
 235 domain socket
 236 .Pa /var/run/log ,
 237 from an Internet domain socket specified in
 238 .Pa /etc/services ,
 239 and from the special device
 240 .Pa /dev/klog
 241 (to read kernel messages).
 242 .Pp
 243 The
 244 .Nm
 245 daemon creates its process ID file,
 246 by default
 247 .Pa /var/run/syslog.pid ,
 248 and stores its process
 249 ID there.
 250 This can be used to kill or reconfigure
 251 .Nm .
 252 .Pp
 253 The message sent to
 254 .Nm
 255 should consist of a single line.
 256 The message can contain a priority code, which should be a preceding
 257 decimal number in angle braces, for example,
 258 .Sq Aq 5 .
 259 This priority code should map into the priorities defined in the
 260 include file
 261 .Aq Pa sys/syslog.h .
 262 .Pp
 263 For security reasons,
 264 .Nm
 265 will not append to log files that do not exist;
 266 therefore, they must be created manually before running
 267 .Nm .
 268 .Sh FILES
 269 .Bl -tag -width /var/run/syslog.pid -compact
 270 .It Pa /etc/syslog.conf
 271 configuration file
 272 .It Pa /var/run/syslog.pid
 273 default process ID file
 274 .It Pa /var/run/log
 275 name of the
 276 .Tn UNIX
 277 domain datagram log socket
 278 .It Pa /dev/klog
 279 kernel log device
 280 .El
 281 .Sh SEE ALSO
 282 .Xr logger 1 ,
 283 .Xr syslog 3 ,
 284 .Xr services 5 ,
 285 .Xr syslog.conf 5
 286 .Sh HISTORY
 287 The
 288 .Nm
 289 command appeared in
 290 .Bx 4.3 .
 291 .Pp
 292 The
 293 .Fl a ,
 294 .Fl s ,
 295 .Fl u ,
 296 and
 297 .Fl v
 298 options are
 299 .Fx 2.2
 300 extensions.
 301 .Sh BUGS
 302 The ability to log messages received in UDP packets is equivalent to
 303 an unauthenticated remote disk-filling service, and should probably be
 304 disabled by default.  Some sort of
 305 .No inter- Ns Nm syslogd
 306 authentication mechanism ought to be worked out.  To prevent the worst
 307 abuse, use of the
 308 .Fl a
 309 option is therefore highly recommended.
 310 .Pp
 311 The
 312 .Fl a
 313 matching algorithm doesn't pretend to be very efficient; use of numeric
 314 IP addresses is faster than domain name comparison.  Since the allowed
 315 peer list is being walked linearly, peer groups where frequent messages
 316 are being anticipated from should be put early into the
 317 .Fl a
 318 list.
 319 .Pp
 320 The log socket was moved from
 321 .Pa /dev
 322 to ease the use of a read-only root filesystem.
 323 This may confuse
 324 some old binaries so that a symbolic link might be used for a
 325 transitional period.