Product SiteDocumentation Site

Chapter 17. Log Files

17.1. Configuring rsyslog
17.2. rsyslog Performance
17.3. Locating Log Files
17.4. Viewing Log Files
17.5. Adding a Log File
17.6. Monitoring Log Files
17.7. Additional Resources
Log files are files that contain messages about the system, including the kernel, services, and applications running on it. There are different log files for different information. For example, there is a default system log file, a log file just for security messages, and a log file for cron tasks.
Log files can be very useful when trying to troubleshoot a problem with the system such as trying to load a kernel driver or when looking for unauthorized log in attempts to the system. This chapter discusses where to find log files, how to view log files, and what to look for in log files.
Some log files are controlled by a daemon called rsyslogd. A list of log messages maintained by rsyslogd can be found in the /etc/rsyslog.conf configuration file.
rsyslog replaced syslogd as the default program for forwarding syslog messages over the network. rsyslog uses the basic syslog protocol and extends its functionality with enhanced filtering, encryption protected relaying of messages, various configuration options, or support for transportation via the TCP or UDP protocols.

17.1. Configuring rsyslog

The main configuration file for rsyslog is /etc/rsyslog.conf. It is essentially divided in the following parts:
  • Modules
  • Global directives
  • Rules
  • Templates
  • Filter conditions
  • Output channels
Each of these segments of the /etc/rsyslog.conf configuration file is described in the sections below.

Note

In your /etc/rsyslog.conf configuration file, any empty lines or any text following a hash sign (#) are comments and are not processed.

17.1.1. Modules

Due to its modular design, rsyslog offers a variety of modules which provide dynamic functionality. Note that modules can be written by third parties. Essentially, modules are comprised of various configuration directives that become available when a module is loaded. To load a module, use the following syntax:
$ModLoad <MODULE> 
where <MODULE> represents your desired module. For example, if you want to load the Text File Input Module (imfile — enables rsyslog to convert any standard text files into a syslog messages), specify the following line in your /etc/rsyslog.conf configuration file:
$ModLoad imfile
rsyslog offers a number of modules which are split into these main categories:
  • Input Modules — Input modules gather messages from various sources. The name of an input module always starts with the im prefix, such as imfile, imrelp, etc.
  • Output Modules — Output modules process messages into different formats or perform various actions on them. The name of an output module always starts with the om prefix, such as omsnmp, omrelp, etc.
  • Filter Modules — Filter modules provide the ability to filter messages according to specified rules. The name of a filter module always starts with the fm prefix.
  • Parser Modules — Parser modules use the message parsers to parse message content of any received messages. The name of a parser module always starts with the pm prefix, such as pmrfc5424, pmrfc3164, etc.
  • Message Modification Modules — Message modification modules change the content of asyslog message. The message modification modules only differ in their implementation from the output and filter modules but share the same interface.
  • String Generator Modules — String generator modules generate strings based on the message content and strongly cooperate with the template feature provided by rsyslog. For more information on templates, refer to . The name of a string generator module always starts with the sm prefix, such as smfile, smtradfile, etc.
  • Library Modules — Library modules provide the ability to load and handle other loadable modules. These modules are loaded automatically by rsyslog when needed and cannot be configured by the user.
A comprehensive list of all available modules and their detailed description can be found at http://www.rsyslog.com/doc/rsyslog_conf_modules.html

Warning

Note that when rsyslog loads any modules, it provides them with access to some of its functions and data. This poses a possible security threat. To minimize security risks, use trustworthy modules only.

17.1.2. Global Directives

Global directives specify configuration options that apply to the rsyslogd daemon. All of the global directives must start with a dollar sign ($). Only one directive can be specified per line. The following is an example of a global directive that specifies the maximum size of the syslog message queue:
$MainMsgQueueSize
The default size defined for this directive (10,000 messages) can be overridden by specifying a different value.
A comprehensive list of all available configuration directives and their detailed description can be found in /usr/share/doc/rsyslog-4.4.2/rsyslog_conf_global.html or online at http://www.rsyslog.com/doc/rsyslog_conf_global.html.

17.1.3. Rules

A rule specifies the cooperation of a selector with an action. To define a rule in your /etc/rsyslog.conf configuration file, define both, a selector and an action, on one line and separate them with one or more spaces or tabs. For more information on selectors, refer to Section 17.1.3.1, “Selectors” and for information on actions, refer to Section 17.1.3.2, “Actions”.

17.1.3.1. Selectors

Selectors filter syslog messages based on two conditions: facility and priority. The following is an example of a selector:
<FACILITY>.<PRIORITY>
where:
  • <FACILITY> specifies the subsystem that produces a specific syslog message. For example, the mail subsystem handles all mail related syslog messages. <FACILITY> can be represented by one of these keywords: auth, authpriv, cron, daemon, kern, lpr, mail, news, syslog, user, uucp, and local0 through local7.
  • <PRIORITY> specifies a priority of a syslog message. <PRIORITY> can be represented by one of these keywords: debug, info, notice, warning, err, crit, alert, and emerg.
    By preceding any priority with an equal sign (=), you specify that only syslog messages with that priority will be selected. All other priorities will be ignored. Conversely, preceding a priority with an exclamation mark (!) selects all syslog messages but those with the defined priority. By not using either of these two extensions, you specify a selection of syslog messages with the defined priority and higher.
In addition to the keywords specified above, you may also use an asterisk (*) to define all facilities or priorities (depending on where you place the asterisk, before or after the dot). Specifying the keyword none serves for facilities with no given priorities.
To define multiple facilities and priorities, simply separate them with a comma (,). To define multiple selectors on one line, separate them with a semi-colon (;).
The following are a few examples of simple selectors:
kern.*    # Selects all kernel syslog messages with any priority
mail.crit    # Selects all mail syslog messages with priority crit and higher.
cron.!info,!debug    # Selects all cron syslog messages except those with the info or debug priority.

17.1.3.2. Actions

Actions specify what is to be done with the messages filtered out by the defined selector. The following are some of the actions you can define in your rule:
Syslog message placement
The majority of actions specify to which log file a syslog message is saved. This is done by specifying a file path after your already defined selector. The following is a rule comprised of a selector that selects all cron syslog messages and an action that saves them into the /var/log/cron log file:
cron.* /var/log/cron
Use a dash mark (-) as a prefix of the file path you specified if you want to omit syncing the desired log file after every syslog message is generated.
Your specified file path can be either static or dynamic. Static files are represented by a simple file path as was shown in the example above. Dynamic files are represented by a template and a question mark (?) prefix. For more information on templates, refer to Section 17.1.4, “Templates”.
Sending syslog messages over the network
rsyslog allows you to send and receive syslog messages over the network. This feature allows to administer syslog messages of multiple hosts on one machine. To forward syslog messages to a remote machine, use the following syntax:
@[(<OPTION>,<MORE OPTIONS>)]<HOST>:[<PORT>]
where:
  • The at sign (@) indicates that the syslog messages are forwarded to a host using the UDP protocol. To use the TCP protocol, use two at signs with no space between them (@@).
  • The <OPTION> and <MORE OPTIONS> attributes can be replaced with an option such as z<NUMBER>. This option enables zlib compression for syslog messages; the <NUMBER> attribute specifies the level of compression.
  • The <HOST> attribute specifies the host which receives the selected syslog messages.
  • The <PORT> attribute specifies the host machine's port.
When specifying an IPv6 address as the hoset, enclose the address in square brackets ([, ]).
The following are some examples of actions that forward syslog messages over the network (note that all actions are preceded with a selector that selects all messages with any priority):
*.* @192.168.0.1    # Forwards messages to 192.168.0.1 via the UDP protocol
*.* @@example.com:18    # Forwards messages to "example.com" using port 18 and the TCP protocol
*.* @(z9)[2001::1]    # Compresses messages with zlib (level 9 compression)
                      # and forwards them to 2001::1 using the UDP protocol
Sending syslog messages to specific users
rsyslog can send syslog messages to specific users by simply specifying a username of the user you wish to send the messages to. To specify more than one user, separate each username with a comma (,). To send messages to every user that is currently logged on, use an asterisk (*).
Discarding syslog messages
To discard your selected messages, use the tilde character (~). The following rule discards any cron syslog messages:
cron.* ~
Note that any action can be followed by a template that formats the message. To specify a template, suffix an action with a semicolon (;) and specify the name of the template.

Caution

A template must be defined before it is used in an action.
For more information on templates, refer to Section 17.1.4, “Templates”.
For more information on various rsyslog actions, refer to /usr/share/doc/rsyslog-4.4.2/rsyslog_conf_actions.html.

17.1.4. Templates

17.1.5. Filter Conditions

17.1.6. Output Channels