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: src/usr.sbin/syslogd/syslogd.8,v 1.22.2.16 2003/03/12 22:08:15 trhodes Exp $
  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 46Acdknsuv
  44 .Op Fl a Ar allowed_peer
  45 .Op Fl b Ar bind_address
  46 .Op Fl f Ar config_file
  47 .Op Fl l Ar path
  48 .Op Fl m Ar mark_interval
  49 .Op Fl P Ar pid_file
  50 .Op Fl p Ar log_socket
  51 .Sh DESCRIPTION
  52 The
  53 .Nm
  54 utility 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 Force
  61 .Nm
  62 to use IPv4 addresses only.
  63 .It Fl 6
  64 Force
  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 c
 160 Disable the compression of repeated instances of the same line
 161 into a single line of the form
 162 .Dq Li "last message repeated N times"
 163 when the output is a pipe to another program.
 164 If specified twice, disable this compression in all cases.
 165 .It Fl d
 166 Put
 167 .Nm
 168 into debugging mode.  This is probably only of use to developers working on
 169 .Nm .
 170 .It Fl f
 171 Specify the pathname of an alternate configuration file;
 172 the default is
 173 .Pa /etc/syslog.conf .
 174 .It Fl k
 175 Disable the translation of
 176 messages received with facility
 177 .Dq kern
 178 to facility
 179 .Dq user .
 180 Usually the
 181 .Dq kern
 182 facility is reserved for messages read directly from
 183 .Pa /dev/klog .
 184 .It Fl m
 185 Select the number of minutes between
 186 .Dq mark
 187 messages; the default is 20 minutes.
 188 .It Fl n
 189 Disable dns query for every request.
 190 .It Fl p
 191 Specify the pathname of an alternate log socket to be used instead;
 192 the default is
 193 .Pa /var/run/log .
 194 .It Fl P
 195 Specify an alternative file in which to store the process ID.
 196 The default is
 197 .Pa /var/run/syslog.pid .
 198 .It Fl l
 199 Specify a location where
 200 .Nm
 201 should place an additional log socket.
 202 Up to 19 additional logging sockets can be specified.
 203 The primary use for this is to place additional log sockets in
 204 .Pa /var/run/log
 205 of various chroot filespaces.
 206 .It Fl s
 207 Operate in secure mode.  Do not log messages from remote machines.  If
 208 specified twice, no network socket will be opened at all, which also
 209 disables logging to remote machines.
 210 .It Fl u
 211 Unique priority logging.  Only log messages at the specified priority.
 212 Without this option, messages at the stated priority or higher are logged.
 213 This option changes the default comparison from
 214 .Dq =>
 215 to
 216 .Dq = .
 217 .It Fl v
 218 Verbose logging.  If specified once, the numeric facility and priority are
 219 logged with each locally-written message.  If specified more than once,
 220 the names of the facility and priority are logged with each locally-written
 221 message.
 222 .El
 223 .Pp
 224 The
 225 .Nm
 226 utility reads its configuration file when it starts up and whenever it
 227 receives a hangup signal.
 228 For information on the format of the configuration file,
 229 see
 230 .Xr syslog.conf 5 .
 231 .Pp
 232 The
 233 .Nm
 234 utility reads messages from the
 235 .Ux
 236 domain socket
 237 .Pa /var/run/log ,
 238 from an Internet domain socket specified in
 239 .Pa /etc/services ,
 240 and from the special device
 241 .Pa /dev/klog
 242 (to read kernel messages).
 243 .Pp
 244 The
 245 .Nm
 246 utility creates its process ID file,
 247 by default
 248 .Pa /var/run/syslog.pid ,
 249 and stores its process
 250 ID there.
 251 This can be used to kill or reconfigure
 252 .Nm .
 253 .Pp
 254 The message sent to
 255 .Nm
 256 should consist of a single line.
 257 The message can contain a priority code, which should be a preceding
 258 decimal number in angle braces, for example,
 259 .Sq Aq 5 .
 260 This priority code should map into the priorities defined in the
 261 include file
 262 .Aq Pa sys/syslog.h .
 263 .Pp
 264 For security reasons,
 265 .Nm
 266 will not append to log files that do not exist;
 267 therefore, they must be created manually before running
 268 .Nm .
 269 .Sh FILES
 270 .Bl -tag -width /var/run/syslog.pid -compact
 271 .It Pa /etc/syslog.conf
 272 configuration file
 273 .It Pa /var/run/syslog.pid
 274 default process ID file
 275 .It Pa /var/run/log
 276 name of the
 277 .Ux
 278 domain datagram log socket
 279 .It Pa /dev/klog
 280 kernel log device
 281 .El
 282 .Sh SEE ALSO
 283 .Xr logger 1 ,
 284 .Xr syslog 3 ,
 285 .Xr services 5 ,
 286 .Xr syslog.conf 5
 287 .Sh HISTORY
 288 The
 289 .Nm
 290 utility appeared in
 291 .Bx 4.3 .
 292 .Pp
 293 The
 294 .Fl a ,
 295 .Fl s ,
 296 .Fl u ,
 297 and
 298 .Fl v
 299 options are
 300 .Fx 2.2
 301 extensions.
 302 .Sh BUGS
 303 The ability to log messages received in UDP packets is equivalent to
 304 an unauthenticated remote disk-filling service, and should probably be
 305 disabled by default.  Some sort of
 306 .No inter- Ns Nm syslogd
 307 authentication mechanism ought to be worked out.  To prevent the worst
 308 abuse, use of the
 309 .Fl a
 310 option is therefore highly recommended.
 311 .Pp
 312 The
 313 .Fl a
 314 matching algorithm doesn't pretend to be very efficient; use of numeric
 315 IP addresses is faster than domain name comparison.  Since the allowed
 316 peer list is being walked linearly, peer groups where frequent messages
 317 are being anticipated from should be put early into the
 318 .Fl a
 319 list.
 320 .Pp
 321 The log socket was moved from
 322 .Pa /dev
 323 to ease the use of a read-only root file system.
 324 This may confuse
 325 some old binaries so that a symbolic link might be used for a
 326 transitional period.