NAME
syslog.conf —
syslogd(8)
configuration file
DESCRIPTION
The
syslog.conf file is the configuration file for the
syslogd(8) program. It consists
of extended options (lines with one key="value" assignment) and
blocks of lines separated by
program and
hostname specifications, with each line containing two
fields: the
selector field which specifies the types of
messages and priorities to which the line applies, and an
action field which specifies the action to be taken if a
message
syslogd(8) receives
matches the selection criteria. The
selector field is
separated from the
action field by one or more tab
characters.
The
Selectors function are encoded as a
facility, a period (‘.’), an optional set of
comparison flags ([!] [<=>]), and a
level, with no
intervening white-space. Both the
facility and the
level are case insensitive.
The
facility describes the part of the system generating the
message, and is one of the following keywords: auth, authpriv, cron, ftp,
daemon, kern, lpr, mail, mark, news, syslog, user, uucp and local0 through
local7. These keywords (with the exception of mark) correspond to the similar
“
LOG_
” values specified to the
openlog(3) and
syslog(3) library routines.
The
comparison flags may be used to specify exactly what
levels are logged. If unspecified, the default comparison is
‘>=’ (greater than or equal to), or, if the
-U option is passed to
syslogd(8), ‘=’
(equal to). Comparison flags beginning with ‘!’ will have their
logical sense inverted. Thus, ‘!=info’ means all levels except
info and ‘!notice’ has the same meaning as
‘<notice’.
The
level describes the severity of the message, and is a
keyword from the following ordered list (higher to lower): emerg, alert, crit,
err, warning, notice, info and debug. These keywords correspond to the similar
(
LOG_
) values specified to the
syslog(3) library routine.
Each block of lines is separated from the previous block by a
program or
hostname specification. A block
will only log messages corresponding to the most recent
program and
hostname specifications given.
Consider the case of a block that selects
‘
pppd
’ as the
program,
directly followed by a block that selects messages from the
hostname ‘
dialhost
’. The
second block will log only messages from the
pppd(8) program from the host
‘dialhost’.
A
program specification of the form
‘
#!+prog1,prog2
’ or
‘
!+prog1,prog2
’ will cause subsequent
blocks to be applied to messages logged by the specified programs. A
program specification of the form
‘
#!-prog1,prog2
’ or
‘
!-prog1,prog2
’ will cause subsequent
blocks to be applied to messages logged by programs other than the ones
specified. A
program specification of the form
‘
#!prog1,prog2
’ or
‘
!prog1,prog2
’ is equivalent to
‘
!+prog1,prog2
’. Program selectors may
also match kernel-generated messages. For example, a program specification of
‘
!+subsys
’ will match kernel-generated
messages of the form ‘
subsys: here is a
message
’. The special specification
‘
!*
’ will cause subsequent blocks to apply
to all programs.
A
hostname specification of the form
‘
#+host1,host2
’ or
‘
+host1,host2
’ will cause subsequent
blocks to be applied to messages received from the specified hosts. A
hostname specification of the form
‘
#-host1,host2
’ or
‘
-host1,host2
’ will cause subsequent
blocks to be applied to messages from hosts other than the ones specified. If
the hostname is given as ‘
@
’, the local
hostname will be used. The special specification
‘
+*
’ will cause subsequent blocks to apply
to all hosts.
See
syslog(3) for a further
descriptions of both the
facility and
level keywords and their significance. It is preferred that
selections be made based on
facility rather than
program, since the latter can vary in a networked
environment. However, there are cases where a
facility may
be too broadly defined.
If a received message matches the specified
facility, and the
specified
level comparison is true, and the first word in
the message after the date matches the
program, the action
specified in the
action field will be taken.
Multiple
selectors may be specified for a single
action by separating them with semicolon (‘;’)
characters. It is important to note, however, that each
selector can modify the ones preceding it.
Multiple
facilities may be specified for a single
level by separating them with comma (‘,’)
characters.
An asterisk (‘*’) can be used to specify all
facilities or all
levels.
The special
facility “mark” receives a message at
priority “info” every 20 minutes (see
syslogd(8)). This is not
enabled by a
facility field containing an asterisk.
The special
level “none” disables a particular
facility.
The
action field of each line specifies the action to be taken
when the
selector field selects a message. There are five
forms:
- A pathname (beginning with a leading slash). Selected
messages are appended to the file, unless pathname points to an existing
FIFO special file.
syslogd(8) treats FIFO
specially by opening them in non-blocking mode and discarding messages
sent when no reader is listening on the other side.
To ensure that kernel messages are written to disk promptly,
syslogd(8) calls
fsync(2) after writing
messages from the kernel. Other messages are not synced explicitly. You
may disable syncing of files specified to receive kernel messages by
prefixing the pathname with a minus sign
‘
-
’. Note that use of this option may
cause the loss of log information in the event of a system crash
immediately following the write attempt. However, using this option may
prove to be useful if your system's kernel is logging many messages.
Normally the priority and version is not written to file. In order to use
syslog-sign you may prefix a pathname with the plus sign
‘+
’. If both switches are used the
order has to be ‘+-
’.
- A hostname (preceded by an at (‘@’) sign).
Selected messages are forwarded to the
syslogd(8) program on the
named host with UDP.
- A hostname preceded by an at (‘@’) sign and
enclosed in brackets (‘[]’) Selected messages are forwarded
with TLS to the syslogd(8)
program on the named host. After the closing bracket a colon
(‘:’) and a port or service name may be appended. Additional
options are configured in parentheses in the form of
key="value". Recognized keywords are
subject, fingerprint,
cert, and verify.
- A comma separated list of users. Selected messages are
written to those users if they are logged in.
- An asterisk. Selected messages are written to all
logged-in users.
- A vertical bar (‘|’) followed by a command
to which to pipe the selected messages. The command string is passed to
/bin/sh for evaluation, so the usual shell
metacharacters or input/output redirection can occur. (Note that
redirecting stdio(3) buffered
output from the invoked command can cause additional delays, or even lost
output data in case a logging subprocess exits with a signal.) The command
itself runs with stdout and stderr
redirected to /dev/null. Upon receipt of a
SIGHUP
,
syslogd(8) will close the
pipe to the process. If the process does not exit voluntarily, it will be
sent a SIGTERM
signal after a grace period of up
to 60 seconds.
The command will only be started once data arrives that should be piped to
it. If the command exits, it will be restarted as necessary.
If it is desired that the subprocess should receive exactly one line of
input, this can be achieved by exiting after reading and processing the
single line. A wrapper script can be used to achieve this effect, if
necessary. Note that this method can be very resource-intensive if many
log messages are being piped through the filter.
Unless the command is a full pipeline, it may be useful to start the command
with exec so that the invoking shell process does not
wait for the command to complete. Note that the command is started with
the UID of the syslogd(8)
process, normally the superuser.
Just like with files a plus sign ‘+
’
will leave the priority and version information intact.
Blank lines and lines whose first non-blank character is a hash
(‘#’) character are ignored.
TLS OPTIONS
Additional options are used for TLS configuration:
- tls_server
- Enables TLS server mode.
- tls_bindport
- Service name or port number to bind to. Default is
‘syslog’. As long as no official port is
assigned this option is required for TLS
servers.
- tls_bindhost
- Hostname or IP to bind to.
- tls_gen_cert
- Automatically generate a private key and
certificate.
- tls_key
- File with private key. Default is
‘/etc/openssl/default.key’
- tls_cert
- File with certificate to use. Default is
‘/etc/openssl/default.crt’
- tls_ca
- File with CA certificate to use.
- tls_cadir
- Directory containing CA certificates.
- tls_verify
- If set to ‘off’ then certificate
authentication is skipped.
- tls_allow_fingerprints
- List of fingerprints of trusted client certificates.
- tls_allow_clientcerts
- List of filenames with trusted client certificates.
TLS AUTHENTICATION
One function of TLS is mutual authentication of client and server. Unless
authentication is disabled by setting ‘tls_verify=off’ the
following rules are used:
As client:
A client can be configured not to check a server's certificate by setting the
parameter
verify to ‘off’. If the server's
certificate is signed by a trusted CA then it is checked if its hostname or IP
is given in its certificate (as a CommonName, as a DNS SubjectAltName, or as
an IP SubjectAltName). If any match is found then the server is authenticated.
If a
subject parameter is given then it is can satisfy
this test as well. This allows DNS-independent configurations using the
server's IP address in the destination and adding its hostname as
subject to authenticate the TLS connection without
having to add the IP to the X.509 certificate.
If no CA is used or no trust path between CA and server certificate exists, then
hash value of the server's certificate is compared with the hash given in
fingerprint and the hash of the certificate in
cert. If the hashes are equal then the server is
authenticated.
As server:
If using a CA and the client's certificate is signed by it then the client is
authenticated. Otherwise the hash of the client's certificate is compared with
the hashes given in
tls_allow_fingerprints and the
hashes of the certificates given in
tls_allow_clientcerts. On any match the client is
authenticated.
BUFFERING
syslogd(8) is able to buffer
temporary not writable messages in memory. To limit the memory consumed for
this buffering the following optons may be given:
- file_queue_length
- pipe_queue_length
- tls_queue_length
- The maximum number of messages buffered for one
destination of type tls, file, or pipe respectively. Defaults are
‘1024’, ‘1024’, and ‘-1’ (no
limit).
- file_queue_size
- pipe_queue_size
- tls_queue_size
- The maximum memory usage in bytes of messages buffered
for one destination. Defaults are ‘1M’, ‘1M’, and
‘16M’.
SIGNING
syslogd(8) is able to digitally
sign all processed messages. The used protocol is defined by RFC 5848
(syslog-sign): at the start of a session the signing sender sends so called
certificate blocks containing its public key; after that it periodically sends
a signed message containing hashes of previous messages.
To detect later manipulation one has to keep a copy of the key used for signing
(otherwise an attacker could alter the logs and sign them with his own key).
If TLS is used with a DSA key then the same key will be used for signing. This
is the recommended setup because it makes it easy to have copies of the
certificate (with the public key) in backups. Otherwise new keys are generated
on every restart and for certain verification it is necessary to have copies
of all used keys. So logging only to a local file is not secure; at least the
used keys should be logged to another host.
- sign_sg
- Enables signing. Set this option to enable syslog-sign
and select how to assign messages to signature groups (subsets of messages
that are signed together). To enable later signature verification and
detection of lost messages the assignment should be chosen such that all
messages of one signature group are written to the same file. Four
possible values for this option are:
- 0
- Use one global signature group for all messages.
- 1
- Use one signature group per priority.
- 2
- Use signature groups for ranges of priorities.
- 3
- Use one signature group per destination. This is a
custom strategy not defined by the standard. With this setting one
signature group is set up for every file and network action.
- sign_delim_sg2
- This option is only evaluated with
‘sign_sg=2’ and allows to configure the priority ranges for
signature groups. The parameters are numerical values used as the maximum
priority for one group. The default is to use one signature groups per
facility, which is equal to setting ‘sign_delim_sg2=7 15 23 31 39
...’.
FILES
- /etc/syslog.conf
- The
syslogd(8) configuration
file.
- /usr/share/examples/syslogd/verify.pl
- Example script to verify message signatures. (Requires Perl
and modules not part of NetBSD.)
EXAMPLES
A configuration file might appear as follows:
# Log all kernel messages, authentication messages of
# level notice or higher and anything of level err or
# higher to the console.
# Don't log private authentication messages!
*.err;kern.*;auth.notice;authpriv.none /dev/console
# Log anything (except mail) of level info or higher.
# Don't log private authentication messages!
*.info;mail.none;authpriv.none /var/log/messages
# Log daemon messages at debug level only
daemon.=debug /var/log/daemon.debug
# The authpriv file has restricted access.
# Write logs with priority for later verification with syslog-sign.
authpriv.* +/var/log/secure
# Log all the mail messages in one place.
mail.* /var/log/maillog
# Everybody gets emergency messages, plus log them on another
# machine.
*.emerg *
*.emerg @arpa.berkeley.edu
# Log all messages of level info or higher to another
# machine using TLS with an alternative portname and a
# fingerprint for authentication
*.info @[logserver]:1234(fingerprint="SHA1:01:02:...")
# Root and Eric get alert and higher messages.
*.alert root,eric
# Save mail and news errors of level err and higher in a
# special file.
mail,news.err /var/log/spoolerr
# Pipe all authentication messages to a filter.
auth.* |exec /usr/local/sbin/authfilter
# Log kernel messages to a separate file without syncing each message.
kern.* -/var/log/kernlog
# Save ftpd transactions along with mail and news.
!ftpd
*.* /var/log/spoolerr
# Send all error messages from a RAID array through a filter.
!raid0
kern.err |exec /usr/local/sbin/raidfilter
# Save pppd messages from dialhost to a separate file.
!pppd
+dialhost
*.* /var/log/dialhost-pppd
# Save non-local log messages from all programs to a separate file.
!*
-@
*.* /var/log/foreign
# Generate digital signatures for all messages
# to each file or network destination.
sign_sg=3
SEE ALSO
syslog(3),
syslogd(8)
HISTORY
The
syslog.conf file appeared in
4.3BSD, along with
syslogd(8).
BUGS
The effects of multiple selectors are sometimes not intuitive. For example
“mail.crit;*.err” will select “mail” facility messages
at the level of “err” or higher, not at the level of
“crit” or higher.