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