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