## Configure system logging ##

[Author](authors.html): _name_ _[[contact]]_ _[[BSD_flavour]]_

[Reviewer](technical_reviewers.html): _name_ _[[contact]]_ _[[BSD_flavour]]_

[Reviewer](technical_reviewers.html): _name_ _[[contact]]_ _[[BSD_flavour]]_

----



### Concept ###

Understand that the system automatically handles logging and has
many different logs.
Recognize the syslog configuration and be able to add or change a logging entry.
Be able to configure the syslog server to not listen to network.
Understand logging(((logging))) facilities and priorities.

### Introduction ###

Many programs use a standard interface called syslog(((syslog))) for recording system activity details,
debugging messages, server accesses, and other transactions.
These logs are useful for verifying system behavior, checking software status,
and diagnosing problems.
Analyzing and viewing log files is discussed in section
[[Review_log_files_to_troubleshoot_and_monitor_system_behavior]].

The actual logging is handled by the syslogd(((syslogd))) daemon (also known as the syslogger(((syslogger)))
or the system message logger) which is started by default.
Applications that use the syslog(3) library interface communicate with the syslogger.
In addition to appending messages to log files, this daemon can also
send messages to the console, pipe the message through another program,
write the message to logged in users, or forward to other network logging servers.

TODO: show a couple log message examples

### Configuration ###

The syslogd configuration file is located at /etc/syslog.conf(((/etc/syslog.conf))).
Comments can be placed on lines that start with a hash mark (#).
Tabs are used as field separators. TODO: do all BSDs allow spaces also?
(Some versions of syslogd also allow spaces as field separators.)

At the simplest, the format is the selector and the action:
 
""facility.level          /var/log/logfilename
 
The facilities are:
auth,
authpriv,
cron,
daemon,
ftp,
kern,
local0
through
local7,
lpr,
mail,
mark,
news,
syslog,
user,
and uucp.
TODO: don't cover mark here, so maybe say "common facilities"?
TODO: check on each BSD's syslog(3) manpage

(((syslog!facilities)))(((syslog!levels)))
 
The level is the priority or severity of the message.
By default, a level will also match higher priority messages.
This means if your configuration is for a "critical level, it will
also log "alerts" and "emergency" messages too.
The levels in order of priority from highest to lowest are:

- emerg
- alert
- crit
- err
- warning
- notice
- info
- debug

TODO: add explanation for each level above

Note that the facilities and levels of the messages sent to the syslogger are defined by the sending application.
They may be hard-coded or a configuration option may have been used.
Applications may be programmed to send at multiple priority levels, for example.

An additional level is available for the configuration called ".none" which disables the corresponding facility.
And the asterisk (*) matches all facilities or all levels.

TODO: what about same on multiple lines?
TODO: console.info?

Some common syslog.conf entries include:

""\*.err;kern.\*;auth.notice;authpriv.none;mail.crit                /dev/console
""
""*.notice;authpriv.none;kern.debug;lpr.info;mail.crit;news.err   /var/log/messages
""
""\*.emerg                                                         \*
""
""ftp.info                                                        /var/log/xferlog
""
""mail.info                                                       /var/log/maillog
""
""cron.\*                                                          /var/log/cron

The following explains these six examples:

1. Error messages for all facilities except authpriv, notice level for auth facility, and
critical mail messages are sent to /dev/console -- such as the first virtual console.
Often admins comment or tune the /dev/console configuration line, so their console doesn't get cluttered.
2. Notice messages for all facilities except authpriv, debug messages for kernel, info messages for lpr,
critical messages for mail, and "error" messages for news are appended to /var/log/messages.
3. Emergency messages for all facilities are written to all logged in users. (TODO: do we cover write/wall/mesg at all?)
4. Information messages for ftp are appended to /var/log/xferlog.
5. Information messages for mail are appended to /var/log/maillog.
6. And all cron facility messages are saved to /var/log/cron (located at /var/cron/log on OpenBSD).

(Remember that by default, the higher priority levels are also matched.)

TODO: explain these


(TODO: Footnote: Be sure to review your own /etc/syslog.conf file which may have slight differences
such as location of cron log or logging to the console commented out.)

Multiple facilities and levels can be listed for an entry.
A semicolon can be used to separate each selector (facility.level)
as seen in two examples above.
And a comma can be used to list multiple facilities for a level.
For example, the following matches all facilities for the "info" level
except for auth, authpriv, cron, ftp, kern, lpr, and mail:

""*.info;auth,authpriv,cron,ftp,kern,lpr,mail.none

This could be rewritten to be the same as:

""daemon,local0,local1,local2,local3,local4,local5,local6,local7,news,syslog,user,uucp.info

TODO: verify above example of "same"

(((syslog)))(((syslogd)))

TODO: discuss actions a little, like precreate file

TODO: about SIGHUP

TODO: discuss or point to login logs (not managed by syslog)
(TODO: Footnote: TODO briefly mention other logs not managed by syslog.)

TODO: show a couple examples with logger

TODO: show most common (and same) syslogd arguments

TODO: show how to disable networking for each BSD

TODO: discuss creation of log file (some versions of newsyslog will create? will any syslogd create?)

The syslog daemon doesn't keep track of file size, so the log files can continue to grow
and potentially use the available disk space.
The `newsyslog` program is commonly used for rotating log files.
It is covered in section [[Configure_log_rotations]].

### Examples ###


### Practice Exercises ###


### More information ###

logger(1), syslog.conf(5), syslog(3), syslogd(8)


