[system-administrators-guide/21] Viewing and Managing Log Files
stephenw
stephenw at fedoraproject.org
Thu Jan 15 21:26:20 UTC 2015
commit 72881f46e64d27a69231164062e749463bce8b2c
Author: Stephen Wadeley <swadeley at redhat.com>
Date: Sun Dec 14 17:13:39 2014 +0100
Viewing and Managing Log Files
Applying improvements
from upstream version, after proofreading and SME feedback
en-US/Viewing_and_Managing_Log_Files.xml | 2534 ++++++++++++++++++++------
en-US/images/redhat-filter-enable.png | Bin 0 -> 967679 bytes
en-US/images/redhat-filter-sample.png | Bin 0 -> 358405 bytes
en-US/images/redhat-filters.png | Bin 0 -> 309252 bytes
en-US/images/redhat-logviewer-add.png | Bin 0 -> 965881 bytes
en-US/images/redhat-logviewer-monitoring.png | Bin 0 -> 967679 bytes
en-US/images/redhat-logviewer.png | Bin 0 -> 965270 bytes
en-US/images/rsyslog_message_flow.png | Bin 0 -> 73315 bytes
8 files changed, 1948 insertions(+), 586 deletions(-)
---
diff --git a/en-US/Viewing_and_Managing_Log_Files.xml b/en-US/Viewing_and_Managing_Log_Files.xml
index 0264b99..7f2b5a3 100644
--- a/en-US/Viewing_and_Managing_Log_Files.xml
+++ b/en-US/Viewing_and_Managing_Log_Files.xml
@@ -3,139 +3,70 @@
]>
<chapter id="ch-Viewing_and_Managing_Log_Files">
<title>Viewing and Managing Log Files</title>
- <indexterm significance="normal">
+ <indexterm>
<primary>log files</primary>
- <seealso>
- <application>Log Viewer</application>
- </seealso>
+ <seealso><application>System Log</application></seealso>
</indexterm>
- <indexterm significance="normal">
+ <indexterm>
<primary>log files</primary>
<secondary>description</secondary>
</indexterm>
- <para>
- <firstterm>Log files</firstterm> 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.</para>
- <para>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 login 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.</para>
- <indexterm significance="normal">
+ <para>
+ <firstterm>Log files</firstterm> are files that contain messages about the system, including the kernel, services, and applications running on it. There are several types of log files for storing various 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 in many situations, for instance to troubleshoot a problem with the system, when trying to load a kernel driver, or when looking for unauthorized login attempts to the system.
+ </para>
+ <indexterm>
<primary>log files</primary>
- <secondary>
- <command>rsyslogd daemon</command>
- </secondary>
+ <secondary><command>rsyslogd daemon</command></secondary>
</indexterm>
- <indexterm significance="normal">
- <primary>
- <application>rsyslog</application>
- </primary>
+ <indexterm>
+ <primary><application>rsyslog</application></primary>
</indexterm>
- <para>Some log files are controlled by a daemon called <systemitem class="daemon">rsyslogd</systemitem>. A list of log files maintained by <systemitem class="daemon">rsyslogd</systemitem> can be found in the <filename>/etc/rsyslog.conf</filename> configuration file.</para>
+ <para>
+ Some log files are controlled by a daemon called <systemitem class="daemon">rsyslogd</systemitem>. The <systemitem class="daemon">rsyslogd</systemitem> daemon is an enhanced replacement for <application>syslogd</application>, and provides extended filtering, various configuration options, input and output modules, support for transportation via the <systemitem class="protocol">TCP</systemitem> or <systemitem class="protocol">UDP</systemitem> protocols. A list of log files maintained by <systemitem class="daemon">rsyslogd</systemitem> can be found in the <filename>/etc/rsyslog.conf</filename> configuration file. Most log files are located in the <filename>/var/log/</filename> directory.
+ </para>
<para>
- <application>rsyslog</application> is an enhanced, multi-threaded syslog daemon which replaced the <command>sysklogd</command> daemon. <application>rsyslog</application> supports the same functionality as <application>sysklogd</application> and extends it with enhanced filtering, encryption protected relaying of messages, various configuration options, or support for transportation via the <systemitem class="protocol">TCP</systemitem> or <systemitem class="protocol">UDP</systemitem> protocols. Note that <application>rsyslog</application> is compatible with <application>sysklogd</application>.
+ Log files can also be managed by the <systemitem class="daemon">journald</systemitem> daemon – a component of <systemitem class="daemon">systemd</systemitem>. The <systemitem class="daemon">journald</systemitem> daemon captures Syslog messages, kernel log messages, initial RAM disk and early boot messages as well as messages written to standard output and standard error output of all services, indexes them and makes this available to the user. The native journal file format, which is a structured and indexed binary file, improves searching and provides faster operation, and it also stores meta data information like time stamps or user IDs. Log files produced by <systemitem class="daemon">journald</systemitem> are by default not persistent, log files are stored only in memory or a small ring-buffer in the <filename class="directory">/run/log/journal/</filename> directory. The amount of logged data depends on free memory, when you reach the capacity limit, the oldes
t entries are deleted. However, this setting can be altered – see <xref linkend="s2-Enabling_Persistent_Storage"/>. For more information on Journal see <xref linkend="s1-Using_the_Journal"/>.
</para>
- <section id="s1-configuring-rsyslog">
- <title>Configuring rsyslog</title>
- <para>
- The main configuration file for <application>rsyslog</application> is <filename>/etc/rsyslog.conf</filename>. It consists of <firstterm>global directives</firstterm>, <firstterm>rules</firstterm> or comments (any empty lines or any text following a hash sign (<literal>#</literal>)). Both, global directives and rules are extensively described in the sections below.
+ <para>
+ By default, these two logging tools coexist on your system. The <systemitem class="daemon">journald</systemitem> daemon is the primary tool for troubleshooting. It also provides additional data necessary for creating structured log messages. Data acquired by <systemitem class="daemon">journald</systemitem> is forwarded into the <systemitem>/run/systemd/journal/syslog</systemitem> socket that may be used by <systemitem class="daemon">rsyslogd</systemitem> to process the data further. However, <application>rsyslog</application> does the actual integration by default via the <systemitem>imjournal</systemitem> input module, thus avoiding the aforementioned socket. You can also transfer data in the opposite direction, from <systemitem class="daemon">rsyslogd</systemitem> to <systemitem class="daemon">journald</systemitem> with use of <systemitem>omjournal</systemitem> module. See <xref linkend="s1-interaction_of_rsyslog_and_journal" /> for further information. The integration
enables maintaining text-based logs in a consistent format to ensure compatibility with possible applications or configurations dependent on <systemitem class="daemon">rsyslogd</systemitem>. Also, you can maintain rsyslog messages in a structured format (see <xref linkend="s1-structured_logging_with_rsyslog"/>).
</para>
- <section id="s2-global-directives">
- <title>Global Directives</title>
- <para>
- Global directives specify configuration options that apply to the <systemitem class="daemon">rsyslogd</systemitem> daemon. They usually specify a value for a specific pre-defined variable that affects the behavior of the <systemitem class="daemon">rsyslogd</systemitem> daemon or a rule that follows. All of the global directives must start with a dollar sign (<literal>$</literal>). 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:</para>
- <screen>
-$MainMsgQueueSize 50000
- </screen>
- <para>
- The default size defined for this directive (<constant>10,000</constant> messages) can be overridden by specifying a different value (as shown in the example above).
- </para>
- <para>
- You may define multiple directives in your <filename>/etc/rsyslog.conf</filename> configuration file. A directive affects the behavior of all configuration options until another occurrence of that same directive is detected.
+ <section id="s1-logfiles-locating">
+ <title>Locating Log Files</title>
+ <indexterm>
+ <primary>log files</primary>
+ <secondary>locating</secondary>
+ </indexterm>
+ <para>Most log files are located in the <filename>/var/log/</filename> directory. Some applications such as <command>httpd</command> and <command>samba</command> have a directory within <filename>/var/log/</filename> for their log files.</para>
+ <indexterm>
+ <primary>log files</primary>
+ <secondary>rotating</secondary>
+ </indexterm>
+ <indexterm>
+ <primary><command>logrotate</command></primary>
+ </indexterm>
+ <para>You may notice multiple files in the <filename>/var/log/</filename> directory with numbers after them (for example, <filename>cron-20100906</filename>). These numbers represent a time stamp that has been added to a rotated log file. Log files are rotated so their file sizes do not become too large. The <filename>logrotate</filename> package contains a cron task that automatically rotates log files according to the <filename>/etc/logrotate.conf</filename> configuration file and the configuration files in the <filename class="directory">/etc/logrotate.d/</filename> directory.</para>
+ </section>
+ <section id="s1-basic_configuration_of_rsyslog">
+ <title>Basic Configuration of Rsyslog</title>
+ <para>
+ The main configuration file for <application>rsyslog</application> is <filename>/etc/rsyslog.conf</filename>. Here, you can specify <firstterm>global directives</firstterm>, <firstterm>modules</firstterm>, and <firstterm>rules</firstterm> that consist of <firstterm>filter</firstterm> and <firstterm>action</firstterm> parts. Also, you can add comments in the form of text following a hash sign (<literal>#</literal>).
</para>
- <para>
- A comprehensive list of all available configuration directives and their detailed description can be found in <filename>/usr/share/doc/rsyslog/rsyslog_conf_global.html</filename>.
- </para>
- </section>
-
- <section id="s2-modules">
- <title>Modules</title>
- <para>
- Due to its modular design, <application>rsyslog</application> offers a variety of <firstterm>modules</firstterm> which provide dynamic functionality. Note that modules can be written by third parties. Most modules provide additional inputs (see <emphasis>Input Modules</emphasis> below) or outputs (see <emphasis>Output Modules</emphasis> below). Other modules provide special functionality specific to each module. The modules may provide additional configuration directives that become available after a module is loaded. To load a module, use the following syntax:
- </para>
- <screen>
-$ModLoad <replaceable><MODULE></replaceable>
- </screen>
- <para>
- where <option>$ModLoad</option> is the global directive that loads the specified module and <replaceable><MODULE></replaceable> represents your desired module. For example, if you want to load the <literal>Text File Input Module</literal> (<command>imfile</command> — enables <application>rsyslog</application> to convert any standard text files into syslog messages), specify the following line in your <filename>/etc/rsyslog.conf</filename> configuration file:
- </para>
- <screen>
-$ModLoad imfile
- </screen>
- <para>
- <application>rsyslog</application> offers a number of modules which are split into these main categories:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Input Modules — Input modules gather messages from various sources. The name of an input module always starts with the <literal>im</literal> prefix, such as <command>imfile</command>, <command>imrelp</command>, etc.
- </para>
- </listitem>
- <listitem>
- <para>
- Output Modules — Output modules provide a facility to store messages into various targets such as sending them across network, storing them in a database or encrypting them. The name of an output module always starts with the <literal>om</literal> prefix, such as <command>omsnmp</command>, <command>omrelp</command>, etc.
- </para>
- </listitem>
- <listitem>
- <para>
- Filter Modules — Filter modules provide the ability to filter messages according to specified rules. The name of a filter module always starts with the <literal>fm</literal> prefix.
- </para>
- </listitem>
- <listitem>
- <para>
- 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 <literal>pm</literal> prefix, such as <command>pmrfc5424</command>, <command>pmrfc3164</command>, etc.
- </para>
- </listitem>
- <listitem>
- <para>
- Message Modification Modules — Message modification modules change the content of a syslog message. The message modification modules only differ in their implementation from the output and filter modules but share the same interface.
- </para>
- </listitem>
- <listitem>
- <para>
- String Generator Modules — String generator modules generate strings based on the message content and strongly cooperate with the template feature provided by <application>rsyslog</application>. For more information on templates, refer to <xref linkend="s3-templates"/>. The name of a string generator module always starts with the <literal>sm</literal> prefix, such as <command>smfile</command>, <command>smtradfile</command>, etc.
- </para>
- </listitem>
- <listitem>
- <para>
- Library Modules — Library modules generally provide functionality for other loadable modules. These modules are loaded automatically by <application>rsyslog</application> when needed and cannot be configured by the user.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- A comprehensive list of all available modules and their detailed description can be found at <ulink url="http://www.rsyslog.com/doc/rsyslog_conf_modules.html/">http://www.rsyslog.com/doc/rsyslog_conf_modules.html</ulink>
- </para>
- <warning>
- <title>Make sure you use trustworthy modules only</title>
+ <section id="s2-Filters">
+ <title>Filters</title>
<para>
- Note that when <application>rsyslog</application> 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.
- </para>
- </warning>
- </section>
- <section id="s2-rules">
- <title>Rules</title>
- <para>
- A rule is specified by a <firstterm>filter</firstterm> part, which selects a subset of syslog messages, and an <firstterm>action</firstterm> part, which specifies what to do with the selected messages. To define a rule in your <filename>/etc/rsyslog.conf</filename> configuration file, define both, a filter and an action, on one line and separate them with one or more spaces or tabs. For more information on filters, refer to <xref linkend="s3-filter-conditions"/> and for information on actions, refer to <xref linkend="s3-actions"/>.
+ A rule is specified by a <emphasis>filter</emphasis> part, which selects a subset of syslog messages, and an <emphasis>action</emphasis> part, which specifies what to do with the selected messages. To define a rule in your <filename>/etc/rsyslog.conf</filename> configuration file, define both, a filter and an action, on one line and separate them with one or more spaces or tabs.
+ </para>
+ <para>
+ <application>rsyslog</application> offers various ways to filter syslog messages according to selected properties. The available filtering methods can be divided into <emphasis>Facility/Priority-based</emphasis>, <emphasis>Property-based</emphasis>, and <emphasis>Expression-based</emphasis> filters.
</para>
- <section id="s3-filter-conditions">
- <title>Filter Conditions</title>
- <para>
- <application>rsyslog</application> offers various ways how to filter syslog messages according to various properties. This sections sums up the most used filter conditions.
- </para>
<variablelist>
<varlistentry>
<term>Facility/Priority-based filters</term>
<listitem>
- <para>The most used and well-known way to filter syslog messages is to use the facility/priority-based filters which filter syslog messages based on two conditions: <firstterm>facility</firstterm> and <firstterm>priority</firstterm>. To create a selector, use the following syntax:
+ <para>The most used and well-known way to filter syslog messages is to use the facility/priority-based filters which filter syslog messages based on two conditions: <firstterm>facility</firstterm> and <firstterm>priority</firstterm> separated by a dot. To create a selector, use the following syntax:
</para>
<screen>
-<replaceable><FACILITY></replaceable>.<replaceable><PRIORITY></replaceable>
+<replaceable>FACILITY</replaceable>.<replaceable>PRIORITY</replaceable>
</screen>
<para>
where:
@@ -143,44 +74,82 @@ $ModLoad imfile
<itemizedlist>
<listitem>
<para>
- <replaceable><FACILITY></replaceable> specifies the subsystem that produces a specific syslog message. For example, the <command>mail</command> subsystem handles all mail related syslog messages. <replaceable><FACILITY></replaceable> can be represented by one of these keywords: <command>auth</command>, <command>authpriv</command>, <command>cron</command>, <command>daemon</command>, <command>kern</command>, <command>lpr</command>, <command>mail</command>, <command>news</command>, <command>syslog</command>, <command>user</command>, <command>uucp</command>, and <command>local0</command> through <command>local7</command>.
+ <replaceable>FACILITY</replaceable> specifies the subsystem that produces a specific syslog message. For example, the <command>mail</command> subsystem handles all mail-related syslog messages. <replaceable>FACILITY</replaceable> can be represented by one of the following keywords (or by a numerical code): <command>kern</command> (0), <command>user</command> (1), <command>mail</command> (2), <command>daemon</command> (3), <command>auth</command> (4), <command>syslog</command> (5), <command>lpr</command> (6), <command>news</command> (7), <command>uucp</command> (8), <command>cron</command> (9), <command>authpriv</command> (10), <command>ftp</command> (11), <command>ntp</command> (12), <command>logaudit</command> (13), <command>logalert</command> (14), <command>clock</command> (15), and <command>local0</command> through <command>local7</command> (16 - 23).
</para>
</listitem>
<listitem>
<para>
- <replaceable><PRIORITY></replaceable> specifies a priority of a syslog message. <replaceable><PRIORITY></replaceable> can be represented by one of these keywords (listed in an ascending order): <command>debug</command>, <command>info</command>, <command>notice</command>, <command>warning</command>, <command>err</command>, <command>crit</command>, <command>alert</command>, and <command>emerg</command>.
+ <replaceable>PRIORITY</replaceable> specifies a priority of a syslog message. <replaceable>PRIORITY</replaceable> can be represented by one of the following keywords (or by a number): <command>debug</command> (7), <command>info</command> (6), <command>notice</command> (5), <command>warning</command> (4), <command>err</command> (3), <command>crit</command> (2), <command>alert</command> (1), and <command>emerg</command> (0).
</para>
<para>
- By preceding any priority with an equal sign (<literal>=</literal>), 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 (<literal>!</literal>) 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 or higher priority.
+ The aforementioned syntax selects syslog messages with the defined or <emphasis>higher</emphasis> priority. By preceding any priority keyword with an equal sign (<literal>=</literal>), you specify that only syslog messages with the specified priority will be selected. All other priorities will be ignored. Conversely, preceding a priority keyword with an exclamation mark (<literal>!</literal>) selects all syslog messages except those with the defined priority.
</para>
</listitem>
</itemizedlist>
<para>
- In addition to the keywords specified above, you may also use an asterisk (<literal>*</literal>) to define all facilities or priorities (depending on where you place the asterisk, before or after the dot). Specifying the keyword <literal>none</literal> serves for facilities with no given priorities.
- </para>
- <para>
- To define multiple facilities and priorities, simply separate them with a comma (<literal>,</literal>). To define multiple filters on one line, separate them with a semi-colon (<literal>;</literal>).
+ In addition to the keywords specified above, you may also use an asterisk (<literal>*</literal>) to define all facilities or priorities (depending on where you place the asterisk, before or after the comma). Specifying the priority keyword <literal>none</literal> serves for facilities with no given priorities. Both facility and priority conditions are case-insensitive.
</para>
<para>
- The following are a few examples of simple facility/priority-based filters:
+ To define multiple facilities and priorities, separate them with a comma (<literal>,</literal>). To define multiple selectors on one line, separate them with a semi-colon (<literal>;</literal>). Note that each selector in the selector field is capable of overwriting the preceding ones, which can exclude some priorities from the pattern.
</para>
- <screen>
-kern.* # Selects all kernel syslog messages with any priority
- </screen>
- <screen>
-mail.crit # Selects all mail syslog messages with priority <command>crit</command> and higher.
- </screen>
- <screen>
-cron.!info,!debug # Selects all cron syslog messages except those with the <command>info</command> or <command>debug</command> priority.
- </screen>
+ <example id="ex-facility_priority-based_filters">
+ <title>Facility/Priority-based Filters</title>
+ <para>
+ The following are a few examples of simple facility/priority-based filters that can be specified in <filename>/etc/rsyslog.conf</filename>. To select all kernel syslog messages with any priority, add the following text into the configuration file:
+ </para>
+ <screen>
+kern.*
+ </screen>
+ <para>
+ To select all mail syslog messages with priority <command>crit</command> and higher, use this form:
+ </para>
+ <screen>
+mail.crit
+ </screen>
+ <para>
+ To select all cron syslog messages except those with the <command>info</command> or <command>debug</command> priority, set the configuration in the following form:
+ </para>
+ <screen>
+cron.!info,!debug
+ </screen>
+ </example>
</listitem>
</varlistentry>
<varlistentry>
<term>Property-based filters</term>
<listitem>
<para>
- Property-based filters let you filter syslog messages by any property, such as <parameter>timegenerated</parameter> or <parameter>syslogtag</parameter>. For more information on properties, refer to <xref linkend="s4-properties"/>. Each of the properties specified in the filters lets you compare it to a specific value using one of the compare-operations listed in <xref linkend="table-compare-operations"/>.
+ Property-based filters let you filter syslog messages by any property, such as <parameter>timegenerated</parameter> or <parameter>syslogtag</parameter>. For more information on properties, see <xref linkend="brid-properties"/>. You can compare each of the specified properties to a particular value using one of the compare-operations listed in <xref linkend="table-compare-operations"/>. Both property names and compare operations are case-sensitive.
+ </para>
+ <para>
+ Property-based filter must start with a colon (<literal>:</literal>). To define the filter, use the following syntax:
</para>
+ <screen>:<replaceable>PROPERTY</replaceable>, [!]<replaceable>COMPARE_OPERATION</replaceable>, "<replaceable>STRING</replaceable>"</screen>
+ <para>
+ where:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <replaceable>PROPERTY</replaceable> attribute specifies the desired property.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The optional exclamation point (<literal>!</literal>) negates the output of the compare-operation. Other Boolean operators are currently not supported in property-based filters.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <replaceable>COMPARE_OPERATION</replaceable> attribute specifies one of the compare-operations listed in <xref linkend="table-compare-operations"/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <replaceable>STRING</replaceable> attribute specifies the value that the text provided by the property is compared to. This value must be enclosed in quotation marks. To escape certain character inside the string (for example a quotation mark (<literal>"</literal>)), use the backslash character (<literal>\</literal>).
+ </para>
+ </listitem>
+ </itemizedlist>
<table id="table-compare-operations">
<title>Property-based compare-operations</title>
<tgroup cols="2">
@@ -202,7 +171,7 @@ cron.!info,!debug # Selects all cron syslog messages except those with the <c
<parameter>contains</parameter>
</entry>
<entry>
- Checks whether the provided string matches any part of the text provided by the property.
+ Checks whether the provided string matches any part of the text provided by the property. To perform case-insensitive comparisons, use <parameter>contains_i</parameter>.
</entry>
</row>
<row>
@@ -210,7 +179,7 @@ cron.!info,!debug # Selects all cron syslog messages except those with the <c
<parameter>isequal</parameter>
</entry>
<entry>
- Compares the provided string against all of the text provided by the property.
+ Compares the provided string against all of the text provided by the property. These two values must be exactly equal to match.
</entry>
</row>
<row>
@@ -218,7 +187,7 @@ cron.!info,!debug # Selects all cron syslog messages except those with the <c
<parameter>startswith</parameter>
</entry>
<entry>
- Checks whether the provided string matches a prefix of the text provided by the property.
+ Checks whether the provided string is found exactly at the beginning of the text provided by the property. To perform case-insensitive comparisons, use <parameter>startswith_i</parameter>.
</entry>
</row>
<row>
@@ -226,8 +195,8 @@ cron.!info,!debug # Selects all cron syslog messages except those with the <c
<parameter>regex</parameter>
</entry>
<entry>
- Compares the provided POSIX BRE (Basic Regular Expression) regular expression against the text provided by the property.
- </entry>
+ Compares the provided POSIX BRE (Basic Regular Expression) against the text provided by the property.
+ </entry>
</row>
<row>
<entry>
@@ -237,124 +206,90 @@ cron.!info,!debug # Selects all cron syslog messages except those with the <c
Compares the provided POSIX ERE (Extended Regular Expression) regular expression against the text provided by the property.
</entry>
</row>
+ <row>
+ <entry>
+ <parameter>isempty</parameter>
+ </entry>
+ <entry>
+ Checks if the property is empty. The value is discarded. This is especially useful when working with normalized data, where some fields may be populated based on normalization result.
+ </entry>
+ </row>
</tbody>
</tgroup>
</table>
- <para>
- To define a property-based filter, use the following syntax:
- </para>
- <screen>:<replaceable><PROPERTY></replaceable>, [!]<replaceable><COMPARE_OPERATION></replaceable>, "<replaceable><STRING></replaceable>"</screen>
- <para>
- where:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- The <replaceable><PROPERTY></replaceable> attribute specifies the desired property (for example, <parameter>timegenerated</parameter>, <parameter>hostname</parameter>, etc.).
- </para>
- </listitem>
- <listitem>
- <para>
- The optional exclamation point (<literal>!</literal>) negates the output of the compare-operation (if prefixing the compare-operation).
- </para>
- </listitem>
- <listitem>
- <para>
- The <replaceable><COMPARE_OPERATION></replaceable> attribute specifies one of the compare-operations listed in <xref linkend="table-compare-operations"/>.
- </para>
- </listitem>
- <listitem>
- <para>
- The <replaceable><STRING></replaceable> attribute specifies the value that the text provided by the property is compared to. To escape certain character (for example a quotation mark (<literal>"</literal>)), use the backslash character (<literal>\</literal>).
- </para>
- </listitem>
- </itemizedlist>
- <para>
- The following are few examples of property-based filters:
- </para>
- <itemizedlist>
- <listitem>
+ <example id="ex-property-based_filters">
+ <title>Property-based Filters</title>
<para>
- The following filter selects syslog messages which contain the string <literal>error</literal> in their message text:
- </para>
+ The following are a few examples of property-based filters that can be specified in <filename>/etc/rsyslog.conf</filename>. To select syslog messages which contain the string <literal>error</literal> in their message text, use:
+ </para>
<screen>:msg, contains, "error"</screen>
- </listitem>
- <listitem>
<para>
- The following filter selects syslog messages received from the hostname <literal>host1</literal>:
- </para>
+ The following filter selects syslog messages received from the host name <literal>host1</literal>:
+ </para>
<screen>:hostname, isequal, "host1"</screen>
- </listitem>
- <listitem>
<para>
- The following filter selects syslog messages which do not contain any mention of the words <literal>fatal</literal> and <literal>error</literal> with any or no text between them (for example, <literal>fatal lib error</literal>):
- </para>
+ To select syslog messages which do not contain any mention of the words <literal>fatal</literal> and <literal>error</literal> with any or no text between them (for example, <literal>fatal lib error</literal>), type:
+ </para>
<screen>:msg, !regex, "fatal .* error"</screen>
- </listitem>
- </itemizedlist>
+ </example>
</listitem>
</varlistentry>
<varlistentry>
<term>Expression-based filters</term>
<listitem>
<para>
- Expression-based filters select syslog messages according to defined arithmetic, boolean or string operations. Expression-based filters use <application>rsyslog</application>'s own scripting language. The syntax of this language is defined in <filename>/usr/share/doc/rsyslog/rscript_abnf.html</filename> along with examples of various expression-based filters.
- </para>
- <para>
- To define an expression-based filter, use the following syntax:
- </para>
- <screen>if <replaceable><EXPRESSION></replaceable> then <replaceable><ACTION></replaceable>
- </screen>
+ Expression-based filters select syslog messages according to defined arithmetic, Boolean or string operations. Expression-based filters use <application>rsyslog</application>'s own scripting language called <emphasis>RainerScript</emphasis> to build complex filters. See <xref linkend="brid-Log_Files-Resources-Online"/> for the syntax definition of this script along with examples of various expression-based filters. Also RainerScript is a basis for <application>rsyslog</application>'s new configuration format, see <xref linkend="s2-using_the_new_configuration_format"/>
+ </para>
+ <para>
+ The basic syntax of expression-based filter looks as follows:
+ </para>
+ <screen>
+if <replaceable>EXPRESSION</replaceable> then <replaceable>ACTION</replaceable> else <replaceable>ACTION</replaceable>
+ </screen>
<para>
where:
</para>
<itemizedlist>
<listitem>
<para>
- The <replaceable><EXPRESSION></replaceable> attribute represents an expression to be evaluated, for example: <literal>$msg startswith 'DEVNAME'</literal> or <literal>$syslogfacility-text == 'local0'</literal>.
- </para>
+ The <replaceable>EXPRESSION</replaceable> attribute represents an expression to be evaluated, for example: <literal>$msg startswith 'DEVNAME'</literal> or <literal>$syslogfacility-text == 'local0'</literal>. You can specify more than one expression in a single filter by using <function>and</function> and <function>or</function> operators.
+ </para>
</listitem>
<listitem>
<para>
- The <replaceable><ACTION></replaceable> attribute represents an action to be performed if the expression returns the value <literal>true</literal>.
- </para>
+ The <replaceable>action</replaceable> attribute represents an action to be performed if the expression returns the value <literal>true</literal>. this can be a single action, or an arbitrary complex script enclosed in curly braces.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Expression-based filters are indicated by the keyword <emphasis>if</emphasis> at the start of a new line. the <emphasis>then</emphasis> keyword separates the <replaceable>expression</replaceable> from the <replaceable>action</replaceable>. optionally, you can employ the <emphasis>else</emphasis> keyword to specify what action is to be performed in case the condition is not met.
+ </para>
</listitem>
</itemizedlist>
- <note>
- <title>Define an expression-based filter on a single line</title>
- <para>
- When defining an expression-based filter, it must be defined on a single line.
- </para>
- </note>
- <note>
- <title>Do not use regular expressions</title>
- <para>
- Regular expressions are currently not supported in expression-based filters.
+ <para>
+ With expression-based filters, you can nest the conditions by using a script enclosed in curly braces as in <xref linkend="ex-expression-based_filters"/>. the script allows you to use <emphasis>facility/priority-based</emphasis> filters inside the expression. on the other hand, <emphasis>property-based</emphasis> filters are not recommended here. RainerScript supports regular expressions with specialized functions <function>re_match()</function> and <function>re_extract()</function>.
</para>
- </note>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>BSD-style blocks</term>
- <listitem>
+ <example id="ex-expression-based_filters">
+ <title>Expression-based Filters</title>
<para>
- <application>rsyslog</application> supports BSD-style blocks inside the <filename>/etc/rsyslog.conf</filename> configuration file. Each block consists of rules which are preceded with a program or hostname label. Use the '!<replaceable><PROGRAM></replaceable>' or '-<replaceable><PROGRAM></replaceable>' labels to include or exclude programs, respectively. Use the '+<replaceable><HOSTNAME></replaceable> ' or '-<replaceable><HOSTNAME></replaceable> ' labels include or exclude hostnames, respectively.
+ The following expression contains two nested conditions. The log files created by a program called <emphasis>prog1</emphasis> are split into two files based on the presence of the "test" string in the message.
</para>
- <para><xref linkend="example-bsd-block1"/> shows a BSD-style block that saves all messages generated by <application>yum</application> to a file.</para>
- <example id="example-bsd-block1">
- <title>BSD-style block</title>
- <screen>
-!yum
-*.* /var/log/named.log
- </screen>
- </example>
+ <screen>
+if $programname == 'prog1' then {
+ action(type="omfile" file="/var/log/prog1.log")
+ if $msg contains 'test' then
+ action(type="omfile" file="/var/log/prog1test.log")
+ else
+ action(type="omfile" file="/var/log/prog1notest.log")
+}
+ </screen>
+ </example>
</listitem>
</varlistentry>
</variablelist>
- </section>
-
- <section id="s3-actions">
- <title>Actions</title>
+ </section>
+ <section id="s2-Actions">
+ <title>Actions</title>
<para>
Actions specify what is to be done with the messages filtered out by an already-defined selector. The following are some of the actions you can define in your rule:
</para>
@@ -363,18 +298,32 @@ cron.!info,!debug # Selects all cron syslog messages except those with the <c
<term>Saving syslog messages to log files</term>
<listitem>
<para>
- 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 <application>cron</application> syslog messages and an action that saves them into the <filename>/var/log/cron.log</filename> log file:
+ 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:
+ </para>
+ <synopsis><replaceable>FILTER</replaceable> <replaceable>PATH</replaceable></synopsis>
+ <para>
+ where <replaceable>FILTER</replaceable> stands for user-specified selector and <replaceable>PATH</replaceable> is a path of a target file.
+ </para>
+ <para>
+ For instance, the following rule is comprised of a selector that selects all <application>cron</application> syslog messages and an action that saves them into the <filename>/var/log/cron.log</filename> log file:
+ </para>
+ <synopsis>cron.* /var/log/cron.log</synopsis>
+ <para>
+ By default, the log file is synchronized every time a syslog message is generated. Use a dash mark (<literal>-</literal>) as a prefix of the file path you specified to omit syncing:
+ </para>
+ <synopsis><replaceable>FILTER</replaceable> -<replaceable>PATH</replaceable></synopsis>
+ <para>
+ Note that you might lose information if the system terminates right after a write attempt. However, this setting can improve performance, especially if you run programs that produce very verbose log messages.
</para>
- <screen>cron.* /var/log/cron.log
- </screen>
<para>
- Use a dash mark (<literal>-</literal>) 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 <emphasis>static</emphasis> or <emphasis>dynamic</emphasis>. Static files are represented by a fixed file path as shown in the example above. Dynamic file paths can differ according to the received message. Dynamic file paths are represented by a template and a question mark (<literal>?</literal>) prefix:
</para>
+ <synopsis><replaceable>FILTER</replaceable> ?<replaceable>DynamicFile</replaceable></synopsis>
<para>
- 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 (<literal>?</literal>) prefix. For more information on templates, refer to <xref linkend="s4-generating-dynamic-fnames"/>.
+ where <replaceable>DynamicFile</replaceable> is a name of a predefined template that modifies output paths. You can use the dash prefix (<literal>-</literal>) to disable syncing, also you can use multiple templates separated by a colon (<literal>;</literal>). For more information on templates, see <xref linkend="brid-generating-dynamic-fnames"/>.
</para>
<para>
- If the file you specified is an existing <application>tty</application> or <filename>/dev/console</filename> device, syslog messages are sent to standard output (using special <application>tty</application>-handling) or your console (using special <filename>/dev/console</filename>-handling) when using the X Window System, respectively.
+ If the file you specified is an existing <application>terminal</application> or <filename>/dev/console</filename> device, syslog messages are sent to standard output (using special <application>terminal</application>-handling) or your console (using special <filename>/dev/console</filename>-handling) when using the X Window System, respectively.
</para>
</listitem>
</varlistentry>
@@ -382,9 +331,9 @@ cron.!info,!debug # Selects all cron syslog messages except those with the <c
<term>Sending syslog messages over the network</term>
<listitem>
<para>
- <application>rsyslog</application> 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:
+ <application>rsyslog</application> allows you to send and receive syslog messages over the network. This feature allows you to administer syslog messages of multiple hosts on one machine. To forward syslog messages to a remote machine, use the following syntax:
</para>
- <screen>@<optional>(<replaceable><OPTION></replaceable>)</optional><replaceable><HOST></replaceable>:<optional><replaceable><PORT></replaceable></optional>
+ <screen>@<optional>(<command>z<replaceable>NUMBER</replaceable></command>)</optional><replaceable>HOST</replaceable>:<optional><replaceable>PORT</replaceable></optional>
</screen>
<para>
where:
@@ -397,91 +346,107 @@ cron.!info,!debug # Selects all cron syslog messages except those with the <c
</listitem>
<listitem>
<para>
- The <replaceable><OPTION></replaceable> attribute can be replaced with an option such as <command>z<replaceable><NUMBER></replaceable>
- </command>. This option enables <application>zlib</application> compression for syslog messages; the <replaceable><NUMBER></replaceable> attribute specifies the level of compression. To define multiple options, simply separate each one of them with a comma (<literal>,</literal>).
+ The optional <command>z<replaceable>NUMBER</replaceable></command> setting enables <application>zlib</application> compression for syslog messages. The <replaceable>NUMBER</replaceable> attribute specifies the level of compression (from 1 – lowest to 9 – maximum). Compression gain is automatically checked by <systemitem class="daemon">rsyslogd</systemitem>, messages are compressed only if there is any compression gain and messages below 60 bytes are never compressed.
</para>
</listitem>
<listitem>
<para>
- The <replaceable><HOST></replaceable> attribute specifies the host which receives the selected syslog messages.
+ The <replaceable>HOST</replaceable> attribute specifies the host which receives the selected syslog messages.
</para>
</listitem>
<listitem>
<para>
- The <replaceable><PORT></replaceable> attribute specifies the host machine's port.
+ The <replaceable>PORT</replaceable> attribute specifies the host machine's port.
</para>
</listitem>
</itemizedlist>
<para>
When specifying an <systemitem class="protocol">IPv6</systemitem> address as the host, enclose the address in square brackets (<literal>[</literal>, <literal>]</literal>).
</para>
- <para>
- 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):
- </para>
- <screen>*.* @192.168.0.1 # Forwards messages to 192.168.0.1 via the <systemitem class="protocol">UDP</systemitem> protocol</screen>
- <screen>*.* @@example.com:18 # Forwards messages to "example.com" using port 18 and the <systemitem class="protocol">TCP</systemitem> protocol</screen>
- <screen>
-*.* @(z9)[2001::1] # Compresses messages with <application>zlib</application> (level 9 compression)
- # and forwards them to 2001::1 using the <systemitem class="protocol">UDP</systemitem> protocol</screen>
+ <example id="ex-logging_over_the_network">
+ <title>Sending syslog Messages over the Network</title>
+ <para>
+ 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). To forward messages to <systemitem class="ipaddress">192.168.0.1</systemitem> via the <systemitem class="protocol">UDP</systemitem> protocol, type:
+ </para>
+ <screen>
+*.* @192.168.0.1
+ </screen>
+ <para>
+ To forward messages to "example.com" using port 18 and the <systemitem class="protocol">TCP</systemitem> protocol, use:
+ </para>
+ <screen>
+*.* @@example.com:18
+ </screen>
+ <para>
+ The following compresses messages with <application>zlib</application> (level 9 compression) and forwards them to <systemitem class="ipaddress">2001:db8::1</systemitem> using the <systemitem class="protocol">UDP</systemitem> protocol
+ </para>
+ <screen>
+*.* @(z9)[2001:db8::1]
+ </screen>
+ </example>
</listitem>
</varlistentry>
<varlistentry>
<term>Output channels</term>
<listitem>
<para>
- Output channels are primarily used for log file rotation (for more info on log file rotation, refer to <xref linkend="configuring-logrotate"/>), that is, to specify the maximum size a log file can grow to. To define an output channel, use the following syntax:
+ Output channels are primarily used to specify the maximum size a log file can grow to. This is very useful for log file rotation (for more information see <xref linkend="s2-log_rotation"/>). An output channel is basically a collection of information about the output action. Output channels are defined by the <literal>$outchannel</literal> directive. To define an output channel in <filename>/etc/rsyslog.conf</filename>, use the following syntax:
</para>
- <screen>$outchannel <replaceable><NAME></replaceable>, <replaceable><FILE_NAME></replaceable>, <replaceable><MAX_SIZE></replaceable>, <replaceable><ACTION></replaceable> </screen>
+ <screen>$outchannel <replaceable>NAME</replaceable>, <replaceable>FILE_NAME</replaceable>, <replaceable>MAX_SIZE</replaceable>, <replaceable>ACTION</replaceable> </screen>
<para>
where:
</para>
<itemizedlist>
<listitem>
<para>
- The <replaceable><NAME></replaceable> attribute specifies the name of the output channel.
+ The <replaceable>NAME</replaceable> attribute specifies the name of the output channel.
</para>
</listitem>
<listitem>
<para>
- The <replaceable><FILE_NAME></replaceable> attribute specifies the name of the output file.
+ The <replaceable>FILE_NAME</replaceable> attribute specifies the name of the output file. Output channels can write only into files, not pipes, terminal, or other kind of output.
</para>
</listitem>
<listitem>
<para>
- The <replaceable><MAX_SIZE></replaceable> attribute represents the maximum size the specified file (in <replaceable><FILE_NAME></replaceable>) can grow to. This value is specified in <emphasis>bytes</emphasis>.
+ The <replaceable>MAX_SIZE</replaceable> attribute represents the maximum size the specified file (in <replaceable>FILE_NAME</replaceable>) can grow to. This value is specified in <emphasis>bytes</emphasis>.
</para>
</listitem>
<listitem>
<para>
- The <replaceable><ACTION></replaceable> attribute specifies the action that is taken when the maximum size, defined in <replaceable><MAX_SIZE></replaceable>, is hit.
+ The <replaceable>ACTION</replaceable> attribute specifies the action that is taken when the maximum size, defined in <replaceable>MAX_SIZE</replaceable>, is hit.
</para>
</listitem>
</itemizedlist>
<para>
- <xref linkend="example-log-rotation"/> shows a simple log rotation through the use of an output channel. First, the output channel is defined via the <parameter>$outchannel</parameter> directive and then used in a rule which selects every syslog message with any priority and executes the previously-defined output channel on the acquired syslog messages. Once the limit (in the example <constant>100 MB</constant>) is hit, the <filename>/home/joe/log_rotation_script</filename> is executed. This script can contain anything from moving the file into a different folder, editing specific content out of it, or simply removing it.
- </para>
+ To use the defined output channel as an action inside a rule, type:
+ </para>
+ <synopsis><replaceable>FILTER</replaceable> :omfile:$<replaceable>NAME</replaceable></synopsis>
<example id="example-log-rotation">
<title>Output channel log rotation</title>
+ <para>
+ The following output shows a simple log rotation through the use of an output channel. First, the output channel is defined via the <parameter>$outchannel</parameter> directive:
+ </para>
+ <screen>
+ $outchannel log_rotation, /var/log/test_log.log, 104857600, /home/joe/log_rotation_script
+ </screen>
+ <para>
+ and then it is used in a rule that selects every syslog message with any priority and executes the previously-defined output channel on the acquired syslog messages:
+ </para>
<screen>
-$outchannel log_rotation,/var/log/test_log.log, 104857600, /home/joe/log_rotation_script
-
-*.* $log_rotation
- </screen>
- </example>
- <note>
- <title>Support for output channels is to be removed in the future</title>
+*.* :omfile:$log_rotation
+ </screen>
<para>
- Output channels are currently supported by <application>rsyslog</application>, however, they are planned to be removed in the nearby future.
- </para>
- </note>
+ Once the limit (in the example <constant>100 MB</constant>) is hit, the <filename>/home/joe/log_rotation_script</filename> is executed. This script can contain anything from moving the file into a different folder, editing specific content out of it, or simply removing it.
+ </para>
+ </example>
</listitem>
</varlistentry>
-
<varlistentry>
<term>Sending syslog messages to specific users</term>
<listitem>
<para>
- <application>rsyslog</application> 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 (<literal>,</literal>). To send messages to every user that is currently logged on, use an asterisk (<literal>*</literal>).
+ <application>rsyslog</application> can send syslog messages to specific users by specifying a user name of the user you want to send the messages to (as in <xref linkend="ex-multiple_actions"/>). To specify more than one user, separate each user name with a comma (<literal>,</literal>). To send messages to every user that is currently logged on, use an asterisk (<literal>*</literal>).
</para>
</listitem>
</varlistentry>
@@ -489,73 +454,83 @@ $outchannel log_rotation,/var/log/test_log.log, 104857600, /home/joe/log_rotatio
<term>Executing a program</term>
<listitem>
<para>
- <application>rsyslog</application> lets you execute a program for selected syslog messages and uses the <systemitem>system()</systemitem> call to execute the program in shell. To specify a program to be executed, prefix it with a caret character (<literal>^</literal>). Consequently, specify a template that formats the received message and passes it to the specified executable as a one line parameter (for more information on templates, refer to <xref linkend="s3-templates"/>). In the following example, any syslog message with any priority is selected, formatted with the <parameter>template</parameter> template and passed as a parameter to the <application>test-program</application> program, which is then executed with the provided parameter:
+ <application>rsyslog</application> lets you execute a program for selected syslog messages and uses the <systemitem>system()</systemitem> call to execute the program in shell. To specify a program to be executed, prefix it with a caret character (<literal>^</literal>). Consequently, specify a template that formats the received message and passes it to the specified executable as a one line parameter (for more information on templates, see <xref linkend="s2-Templates"/>).
+ </para>
+ <synopsis><replaceable>FILTER</replaceable> ^<replaceable>EXECUTABLE</replaceable>; <replaceable>TEMPLATE</replaceable></synopsis>
+ <para>
+ Here an output of the <replaceable>FILTER</replaceable> condition is processed by a program represented by <replaceable>EXECUTABLE</replaceable>. This program can be any valid executable. Replace <replaceable>TEMPLATE</replaceable> with the name of the formatting template.
+ </para>
+ <example id="ex-esecuting_a_program">
+ <title>Executing a Program</title>
+ <para>
+ In the following example, any syslog message with any priority is selected, formatted with the <parameter>template</parameter> template and passed as a parameter to the <application>test-program</application> program, which is then executed with the provided parameter:
</para>
<screen>*.* ^test-program;template</screen>
+ </example>
<warning>
<title>Be careful when using the shell execute action</title>
<para>
- When accepting messages from any host, and using the shell execute action, you may be vulnerable to command injection. An attacker may try to inject and execute commands specified by the attacker in the program you specified (in your action) to be executed. To avoid any possible security threats, thoroughly consider the use of the shell execute action.
+ When accepting messages from any host, and using the shell execute action, you may be vulnerable to command injection. An attacker may try to inject and execute commands in the program you specified to be executed in your action. To avoid any possible security threats, thoroughly consider the use of the shell execute action.
</para>
</warning>
</listitem>
</varlistentry>
<varlistentry>
- <term>Inputting syslog messages in a database</term>
+ <term>Storing syslog messages in a database</term>
<listitem>
<para>
Selected syslog messages can be directly written into a database table using the <emphasis>database writer</emphasis> action. The database writer uses the following syntax:
</para>
- <screen>:<replaceable><PLUGIN></replaceable>:<replaceable><DB_HOST></replaceable>,<replaceable><DB_NAME></replaceable>,<replaceable><DB_USER></replaceable>,<replaceable><DB_PASSWORD></replaceable>;<optional><replaceable><TEMPLATE></replaceable></optional></screen>
+ <screen>:<replaceable>PLUGIN</replaceable>:<replaceable>DB_HOST</replaceable>,<replaceable>DB_NAME</replaceable>,<replaceable>DB_USER</replaceable>,<replaceable>DB_PASSWORD</replaceable>;<optional><replaceable>TEMPLATE</replaceable></optional></screen>
<para>
where:
</para>
<itemizedlist>
<listitem>
<para>
- The <replaceable><PLUGIN></replaceable> calls the specified plug-in that handles the database writing (for example, the <systemitem>ommysql</systemitem> plug-in).
+ The <replaceable>PLUGIN</replaceable> calls the specified plug-in that handles the database writing (for example, the <systemitem>ommysql</systemitem> plug-in).
</para>
</listitem>
<listitem>
<para>
- The <replaceable><DB_HOST></replaceable> attribute specifies the database hostname.
+ The <replaceable>DB_HOST</replaceable> attribute specifies the database host name.
</para>
</listitem>
<listitem>
<para>
- The <replaceable><DB_NAME></replaceable> attribute specifies the name of the database.
+ The <replaceable>DB_NAME</replaceable> attribute specifies the name of the database.
</para>
</listitem>
<listitem>
<para>
- The <replaceable><DB_USER></replaceable> attribute specifies the database user.
+ The <replaceable>DB_USER</replaceable> attribute specifies the database user.
</para>
</listitem>
<listitem>
<para>
- The <replaceable><DB_PASSWORD></replaceable> attribute specifies the password used with the aforementioned database user.
+ The <replaceable>DB_PASSWORD</replaceable> attribute specifies the password used with the aforementioned database user.
</para>
</listitem>
<listitem>
<para>
- The <replaceable><TEMPLATE></replaceable> attribute specifies an optional use of a template that modifies the syslog message. For more information on templates, refer to <xref linkend="s3-templates"/>.
+ The <replaceable>TEMPLATE</replaceable> attribute specifies an optional use of a template that modifies the syslog message. For more information on templates, see <xref linkend="s2-Templates"/>.
</para>
</listitem>
</itemizedlist>
<important>
<title>Using MySQL and PostgreSQL</title>
<para>
- Currently, <application>rsyslog</application> provides support for <systemitem class="systemname">MySQL</systemitem> (for more information, refer to <filename>/usr/share/doc/rsyslog/rsyslog_mysql.html</filename>) and <systemitem class="systemname">PostgreSQL</systemitem> databases only.
- In order to use the <systemitem class="systemname">MySQL</systemitem> and <systemitem class="systemname">PostgreSQL</systemitem> database writer functionality, install the <package>rsyslog-mysql</package> and <package>rsyslog-pgsql</package> packages installed, respectively. Also, make sure you load the appropriate modules in your <filename>/etc/rsyslog.conf</filename> configuration file:
+ Currently, <application>rsyslog</application> provides support for <systemitem class="systemname">MySQL</systemitem> and <systemitem class="systemname">PostgreSQL</systemitem> databases only.
+ In order to use the <systemitem class="systemname">MySQL</systemitem> and <systemitem class="systemname">PostgreSQL</systemitem> database writer functionality, install the <package>rsyslog-mysql</package> and <package>rsyslog-pgsql</package> packages, respectively. Also, make sure you load the appropriate modules in your <filename>/etc/rsyslog.conf</filename> configuration file:
</para>
<screen>
$ModLoad ommysql # Output module for MySQL support
$ModLoad ompgsql # Output module for PostgreSQL support
</screen>
- <para>For more information on <application>rsyslog</application> modules, refer to <xref linkend="s2-modules"/>.
+ <para>For more information on <application>rsyslog</application> modules, see <xref linkend="s1-using_rsyslog_modules"/>.
</para>
<para>
- Alternatively, you may use a generic database interface provided by the <systemitem>omlibdb</systemitem> module. However, this module is currently not compiled.
+ Alternatively, you may use a generic database interface provided by the <systemitem>omlibdb</systemitem> module (supports: Firebird/Interbase, MS SQL, Sybase, SQLLite, Ingres, Oracle, mSQL).
</para>
</important>
</listitem>
@@ -564,45 +539,58 @@ $ModLoad ompgsql # Output module for PostgreSQL support
<term>Discarding syslog messages</term>
<listitem>
<para>
- To discard your selected messages, use the tilde character (<literal>~</literal>). The following rule discards any cron syslog messages:
+ To discard your selected messages, use the tilde character (<literal>~</literal>).
+ </para>
+ <synopsis><replaceable>FILTER</replaceable> ~</synopsis>
+ <para>
+ The discard action is mostly used to filter out messages before carrying on any further processing. It can be effective if you want to omit some repeating messages that would otherwise fill the log files. The results of discard action depend on where in the configuration file it is specified, for the best results place these actions on top of the actions list. Please note that once a message has been discarded there is no way to retrieve it in later configuration file lines.
+ </para>
+ <para>
+ For instance, the following rule discards any cron syslog messages:
</para>
<screen>cron.* ~</screen>
</listitem>
</varlistentry>
</variablelist>
+ <bridgehead>Specifying Multiple Actions</bridgehead>
<para>
- For each selector, you are allowed to specify multiple actions. To specify multiple actions for one selector, write each action on a separate line and precede it with an ampersand character (&). Only the first action is allowed to have a selector specified on its line. The following is an example of a rule with multiple actions:
+ For each selector, you are allowed to specify multiple actions. To specify multiple actions for one selector, write each action on a separate line and precede it with an ampersand character (&):
</para>
- <screen>
-kern.=crit joe
+ <screen>
+<replaceable>FILTER</replaceable> <replaceable>ACTION</replaceable>
+& <replaceable>ACTION</replaceable>
+& <replaceable>ACTION</replaceable>
+ </screen>
+ <para>
+ Specifying multiple actions improves the overall performance of the desired outcome since the specified selector has to be evaluated only once.
+ </para>
+ <example id="ex-multiple_actions">
+ <title>Specifying Multiple Actions</title>
+ <para>
+ In the following example, all kernel syslog messages with the critical priority (<parameter>crit</parameter>) are sent to user <systemitem class="username">user1</systemitem>, processed by the template <parameter>temp</parameter> and passed on to the <parameter>test-program</parameter> executable, and forwarded to <systemitem class="ipaddress">192.168.0.1</systemitem> via the <systemitem class="protocol">UDP</systemitem> protocol.
+ </para>
+ <screen>
+kern.=crit user1
& ^test-program;temp
& @192.168.0.1
- </screen>
- <para>
- In the example above, all kernel syslog messages with the critical priority (<parameter>crit</parameter>) are send to user <systemitem class="username">joe</systemitem>, processed by the template <parameter>temp</parameter> and passed on to the <parameter>test-program</parameter> executable, and forwarded to <systemitem class="ipaddress">192.168.0.1</systemitem> via the <systemitem class="protocol">UDP</systemitem> protocol.
- </para>
- <para>
- Specifying multiple actions improves the overall performance of the desired outcome since the specified selector has to be evaluated only once.
- </para>
+ </screen>
+ </example>
<para>
- Note that any action can be followed by a template that formats the message. To specify a template, suffix an action with a semicolon (<literal>;</literal>) and specify the name of the template.
+ Any action can be followed by a template that formats the message. To specify a template, suffix an action with a semicolon (<literal>;</literal>) and specify the name of the template. For more information on templates, see <xref linkend="s2-Templates"/>.
</para>
<warning>
<title>Using templates</title>
<para>
- A template must be defined before it is used in an action, otherwise, it is ignored.
+ A template must be defined before it is used in an action, otherwise it is ignored. In other words, template definitions should always precede rule definitions in <filename>/etc/rsyslog.conf</filename>.
</para>
</warning>
+ </section>
+ <section id="s2-Templates">
+ <title>Templates</title>
<para>
- For more information on templates, refer to <xref linkend="s3-templates"/>.
- </para>
- </section>
- <section id="s3-templates">
- <title>Templates</title>
- <para>
- Any output that is generated by <application>rsyslog</application> can be modified and formatted according to your needs through the use of templates. To create a template use the following syntax:
+ Any output that is generated by <application>rsyslog</application> can be modified and formatted according to your needs with the use of <emphasis>templates</emphasis>. To create a template use the following syntax in <filename>/etc/rsyslog.conf</filename>:
</para>
- <screen>$template <replaceable><TEMPLATE_NAME></replaceable>,"<replaceable>text %<PROPERTY>% more text</replaceable>", <optional><replaceable><OPTION></replaceable></optional></screen>
+ <screen>$template <replaceable>TEMPLATE_NAME</replaceable>,"<replaceable>text %PROPERTY% more text</replaceable>", <optional><replaceable>OPTION</replaceable></optional></screen>
<para>
where:
</para>
@@ -614,63 +602,68 @@ kern.=crit joe
</listitem>
<listitem>
<para>
- <parameter><TEMPLATE_NAME></parameter> is the name of the template. Use this name to refer to the template.
+ <parameter>TEMPLATE_NAME</parameter> is the name of the template. Use this name to refer to the template.
</para>
</listitem>
<listitem>
<para>
- Anything between the two quotation marks (<literal>"</literal>…<literal>"</literal>) is the actual template text. Within this text, you are allowed to escape characters in order to use their functionality, such as <literal>\n</literal> for new line or <literal>\r</literal> for carriage return. Other characters, such as <literal>%</literal> or <literal>"</literal>, have to be escaped in case you want to those characters literally.
- </para>
+ Anything between the two quotation marks (<literal>"</literal>…<literal>"</literal>) is the actual template text. Within this text, special characters, such as <literal>\n</literal> for new line or <literal>\r</literal> for carriage return, can be used. Other characters, such as <literal>%</literal> or <literal>"</literal>, have to be escaped if you want to use those characters literally.
+ </para>
+ </listitem>
+ <listitem>
<para>
- The text specified within two percent signs (<literal>%</literal>) specifies a <firstterm>property</firstterm> that is consequently replaced with the property's actual value. For more information on properties, refer to <xref linkend="s4-properties"/>
+ The text specified between two percent signs (<literal>%</literal>) specifies a <firstterm>property</firstterm> that allows you to access specific contents of a syslog message. For more information on properties, see <xref linkend="brid-properties"/>.
</para>
</listitem>
<listitem>
<para>
- The <parameter><OPTION></parameter> attribute specifies any options that modify the template functionality. Do not mistake these for property options, which are defined inside the template text (between <literal>"</literal>…<literal>"</literal>). The currently supported template options are <parameter>sql</parameter> and <parameter>stdsql</parameter> used for formatting the text as an SQL query.
- </para>
+ The <parameter>OPTION</parameter> attribute specifies any options that modify the template functionality. The currently supported template options are <parameter>sql</parameter> and <parameter>stdsql</parameter>, which are used for formatting the text as an SQL query.
+ </para>
<note>
<title>The sql and stdsql options</title>
<para>
- Note that the database writer (for more information, refer to section <citetitle>Inputting syslog messages in a database</citetitle> in <xref linkend="s3-actions"/>) checks whether the <parameter>sql</parameter> and <parameter>stdsql</parameter> options are specified in the template. If they are not, the database writer does not perform any action. This is to prevent any possible security threats, such as SQL injection.
+ Note that the database writer checks whether the <parameter>sql</parameter> or <parameter>stdsql</parameter> options are specified in the template. If they are not, the database writer does not perform any action. This is to prevent any possible security threats, such as SQL injection.
+ </para>
+ <para>
+ See section <citetitle>Storing syslog messages in a database</citetitle> in <xref linkend="s2-Actions"/> for more information.
</para>
</note>
</listitem>
</itemizedlist>
- <section id="s4-generating-dynamic-fnames">
- <title>Generating dynamic file names</title>
+ <bridgehead id="brid-generating-dynamic-fnames">Generating Dynamic File Names</bridgehead>
<para>
- Templates can be used to generate dynamic file names. By specifying a property as a part of the file path, a new file will be created for each unique property. For example, use the <parameter>timegenerated</parameter> property to generate a unique file name for each syslog message:
+ Templates can be used to generate dynamic file names. By specifying a property as a part of the file path, a new file will be created for each unique property, which is a convenient way to classify syslog messages.
+ </para>
+ <para>
+ For example, use the <parameter>timegenerated</parameter> property, which extracts a time stamp from the message, to generate a unique file name for each syslog message:
</para>
<screen>$template DynamicFile,"/var/log/test_logs/%timegenerated%-test.log"</screen>
<para>
- Keep in mind that the <parameter>$template</parameter> directive only specifies the template. You must use it inside a rule for it to take effect:
+ Keep in mind that the <parameter>$template</parameter> directive only specifies the template. You must use it inside a rule for it to take effect. In <filename>/etc/rsyslog.conf</filename>, use the question mark (<literal>?</literal>) in an action definition to mark the dynamic file name template:
</para>
<screen>*.* ?DynamicFile</screen>
- </section>
- <section id="s4-properties">
- <title>Properties</title>
+ <bridgehead id="brid-properties">Properties</bridgehead>
<para>
- Properties defined inside a template (within two percent signs (<literal>%</literal>)) allow you to access various contents of a syslog message through the use of a <firstterm>property replacer</firstterm>. To define a property inside a template (between the two quotation marks (<literal>"</literal>…<literal>"</literal>)), use the following syntax:
- </para>
- <screen>%<replaceable><PROPERTY_NAME></replaceable><optional>:<replaceable><FROM_CHAR></replaceable>:<replaceable><TO_CHAR></replaceable>:<replaceable><OPTION></replaceable></optional>%</screen>
+ Properties defined inside a template (between two percent signs (<literal>%</literal>)) enable access various contents of a syslog message through the use of a <firstterm>property replacer</firstterm>. To define a property inside a template (between the two quotation marks (<literal>"</literal>…<literal>"</literal>)), use the following syntax:
+ </para>
+ <screen>%<replaceable>PROPERTY_NAME</replaceable><optional>:<replaceable>FROM_CHAR</replaceable>:<replaceable>TO_CHAR</replaceable>:<replaceable>OPTION</replaceable></optional>%</screen>
<para>
where:
</para>
<itemizedlist>
<listitem>
<para>
- The <replaceable><PROPERTY_NAME></replaceable> attribute specifies the name of a property. A comprehensible list of all available properties and their detailed description can be found in <filename>/usr/share/doc/rsyslog/property_replacer.html</filename> under the section <emphasis>Available Properties</emphasis>.
+ The <replaceable>PROPERTY_NAME</replaceable> attribute specifies the name of a property. A list of all available properties and their detailed description can be found in the <filename>rsyslog.conf(5)</filename> manual page under the section <emphasis>Available Properties</emphasis>.
</para>
</listitem>
<listitem>
<para>
- <replaceable><FROM_CHAR></replaceable> and <replaceable><TO_CHAR></replaceable> attributes denote a range of characters that the specified property will act upon. Alternatively, regular expressions can be used to specify a range of characters. To do so, specify the letter <literal>R</literal> as the <replaceable><FROM_CHAR></replaceable> attribute and specify your desired regular expression as the <replaceable><TO_CHAR></replaceable> attribute.
+ <replaceable>FROM_CHAR</replaceable> and <replaceable>TO_CHAR</replaceable> attributes denote a range of characters that the specified property will act upon. Alternatively, regular expressions can be used to specify a range of characters. To do so, set the letter <literal>R</literal> as the <replaceable>FROM_CHAR</replaceable> attribute and specify your desired regular expression as the <replaceable>TO_CHAR</replaceable> attribute.
</para>
</listitem>
<listitem>
<para>
- The <replaceable><OPTION></replaceable> attribute specifies any property options. A comprehensible list of all available properties and their detailed description can be found in <filename>/usr/share/doc/rsyslog/property_replacer.html</filename> under the section <emphasis>Property Options</emphasis>.
+ The <replaceable>OPTION</replaceable> attribute specifies any property options, such as the <option>lowercase</option> option to convert the input to lowercase. A list of all available property options and their detailed description can be found in the <filename>rsyslog.conf(5)</filename> manual page under the section <emphasis>Property Options</emphasis>.
</para>
</listitem>
</itemizedlist>
@@ -680,7 +673,7 @@ kern.=crit joe
<itemizedlist>
<listitem>
<para>
- The following property simply obtains the whole message text of a syslog message:
+ The following property obtains the whole message text of a syslog message:
</para>
<screen>%msg%</screen>
</listitem>
@@ -698,130 +691,114 @@ kern.=crit joe
</listitem>
<listitem>
<para>
- The following property obtains the first 10 characters of the timestamp that is generated when the syslog message is received and formats it according to the RFC 3999 date standard.
+ The following property obtains the first 10 characters of the time stamp that is generated when the syslog message is received and formats it according to the <ulink url="http://www.rfc-editor.org/info/rfc3999"><citetitle pubwork="webpage">RFC 3999</citetitle></ulink> date standard.
</para>
<screen>%timegenerated:1:10:date-rfc3339%</screen>
</listitem>
</itemizedlist>
- </section>
- <section id="s4-template-examples">
- <title>Template Examples</title>
- <para>
- This section presents few examples of <application>rsyslog</application> templates.
- </para>
- <para>
- <xref linkend="example-temp1"/> shows a template that formats a syslog message so that it outputs the message's severity, facility, the timestamp of when the message was received, the hostname, the message tag, the message text, and ends with a new line.
- </para>
+ <bridgehead id="brid-template-examples">Template Examples</bridgehead>
+ <para>
+ This section presents a few examples of <application>rsyslog</application> templates.
+ </para>
+ <para>
+ <xref linkend="example-temp1"/> shows a template that formats a syslog message so that it outputs the message's severity, facility, the time stamp of when the message was received, the host name, the message tag, the message text, and ends with a new line.
+ </para>
<example id="example-temp1">
<title>A verbose syslog message template</title>
- <screen>$template verbose,"%syslogseverity%,%syslogfacility%,%timegenerated%,%HOSTNAME%,%syslogtag%,%msg%\n"</screen>
+ <screen>$template verbose, "%syslogseverity%, %syslogfacility%, %timegenerated%, %HOSTNAME%, %syslogtag%, %msg%\n"</screen>
</example>
<para>
- <xref linkend="example-temp2"/> shows a template that resembles a traditional wall message (a message that is send to every user that is logged in and has their <parameter>mesg(1)</parameter> permission set to <parameter>yes</parameter>). This template outputs the message text, along with a hostname, message tag and a timestamp, on a new line (using <literal>\r</literal> and <literal>\n</literal>) and rings the bell (using <literal>\7</literal>).
- </para>
+ <xref linkend="example-temp2"/> shows a template that resembles a traditional wall message (a message that is send to every user that is logged in and has their <parameter>mesg(1)</parameter> permission set to <parameter>yes</parameter>). This template outputs the message text, along with a host name, message tag and a time stamp, on a new line (using <literal>\r</literal> and <literal>\n</literal>) and rings the bell (using <literal>\7</literal>).
+ </para>
<example id="example-temp2">
<title>A wall message template</title>
<screen>$template wallmsg,"\r\n\7Message from syslogd@%HOSTNAME% at %timegenerated% ...\r\n %syslogtag% %msg%\n\r"</screen>
</example>
<para>
<xref linkend="example-temp3"/> shows a template that formats a syslog message so that it can be used as a database query. Notice the use of the <parameter>sql</parameter> option at the end of the template specified as the template option. It tells the database writer to format the message as an MySQL <systemitem class="systemname">SQL</systemitem> query.
- </para>
+ </para>
<example id="example-temp3">
<title>A database formatted message template</title>
- <screen>$template dbFormat,"insert into SystemEvents (Message, Facility,FromHost, Priority, DeviceReportedTime, ReceivedAt, InfoUnitID, SysLogTag) values ('%msg%', %syslogfacility%, '%HOSTNAME%',%syslogpriority%, '%timereported:::date-mysql%', '%timegenerated:::date-mysql%', %iut%, '%syslogtag%')",sql</screen>
+ <screen>$template dbFormat,"insert into SystemEvents (Message, Facility, FromHost, Priority, DeviceReportedTime, ReceivedAt, InfoUnitID, SysLogTag) values ('%msg%', %syslogfacility%, '%HOSTNAME%', %syslogpriority%, '%timereported:::date-mysql%', '%timegenerated:::date-mysql%', %iut%, '%syslogtag%')", sql</screen>
</example>
<para>
- <application>rsyslog</application> also contains a set of predefined templates identified by the <literal>RSYSLOG_</literal> prefix. It is advisable to not create a template using this prefix to avoid any conflicts. The following list shows these predefined templates along with their definitions.
+ <application>rsyslog</application> also contains a set of predefined templates identified by the <literal>RSYSLOG_</literal> prefix. These are reserved for the syslog's use and it is advisable to not create a template using this prefix to avoid conflicts. The following list shows these predefined templates along with their definitions.
</para>
<variablelist>
<varlistentry>
<term><parameter>RSYSLOG_DebugFormat</parameter></term>
<listitem>
+ <para>
+ A special format used for troubleshooting property problems.
+ </para>
<screen>"Debug line with all properties:\nFROMHOST: '%FROMHOST%', fromhost-ip: '%fromhost-ip%', HOSTNAME: '%HOSTNAME%', PRI: %PRI%,\nsyslogtag '%syslogtag%', programname: '%programname%', APP-NAME: '%APP-NAME%', PROCID: '%PROCID%', MSGID: '%MSGID%',\nTIMESTAMP: '%TIMESTAMP%', STRUCTURED-DATA: '%STRUCTURED-DATA%',\nmsg: '%msg%'\nescaped msg: '%msg:::drop-cc%'\nrawmsg: '%rawmsg%'\n\n\"</screen>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>RSYSLOG_SyslogProtocol23Format</parameter></term>
<listitem>
- <screen>"<%PRI%>1 %TIMESTAMP:::date-rfc3339% %HOSTNAME% %APP-NAME% %PROCID% %MSGID% %STRUCTURED-DATA% %msg%\n\"</screen>
+ <para>
+ The format specified in IETF's internet-draft ietf-syslog-protocol-23, which is assumed to become the new syslog standard RFC.
+ </para>
+ <screen>"%PRI%1 %TIMESTAMP:::date-rfc3339% %HOSTNAME% %APP-NAME% %PROCID% %MSGID% %STRUCTURED-DATA% %msg%\n\"</screen>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>RSYSLOG_FileFormat</parameter></term>
<listitem>
+ <para>
+ A modern-style logfile format similar to TraditionalFileFormat, but with high-precision time stamps and time zone information.
+ </para>
<screen>"%TIMESTAMP:::date-rfc3339% %HOSTNAME% %syslogtag%%msg:::sp-if-no-1st-sp%%msg:::drop-last-lf%\n\"</screen>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>RSYSLOG_TraditionalFileFormat</parameter></term>
<listitem>
+ <para>
+ The older default log file format with low-precision time stamps.
+ </para>
<screen>"%TIMESTAMP% %HOSTNAME% %syslogtag%%msg:::sp-if-no-1st-sp%%msg:::drop-last-lf%\n\"</screen>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>RSYSLOG_ForwardFormat</parameter></term>
<listitem>
- <screen>"<%PRI%>%TIMESTAMP:::date-rfc3339% %HOSTNAME% %syslogtag:1:32%%msg:::sp-if-no-1st-sp%%msg%\"</screen>
+ <para>
+ A forwarding format with high-precision time stamps and time zone information.
+ </para>
+ <screen>"%PRI%%TIMESTAMP:::date-rfc3339% %HOSTNAME% %syslogtag:1:32%%msg:::sp-if-no-1st-sp%%msg%\"</screen>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>RSYSLOG_TraditionalForwardFormat</parameter></term>
<listitem>
- <screen>"<%PRI%>%TIMESTAMP% %HOSTNAME% %syslogtag:1:32%%msg:::sp-if-no-1st-sp%%msg%\"</screen>
- </listitem>
+ <para>
+ The traditional forwarding format with low-precision time stamps.
+ </para>
+ <screen>"%PRI%%TIMESTAMP% %HOSTNAME% %syslogtag:1:32%%msg:::sp-if-no-1st-sp%%msg%\"</screen>
+ </listitem>
</varlistentry>
</variablelist>
- </section>
- </section>
</section>
- <section id="s2-rsyslog-cmd-options">
- <title><application>rsyslog</application> Command Line Configuration</title>
- <para>
- Some of <application>rsyslog</application>'s functionality can be configured through the command line options, as <application>sysklogd</application>'s can. Note that as of version 3 of <application>rsyslog</application>, this method was deprecated. To enable some of these option, you must specify the compatibility mode <application>rsyslog</application> should run in. However, configuring <application>rsyslog</application> through the command line options should be avoided.
- </para>
- <para>
- To specify the compatibility mode <application>rsyslog</application> should run in, use the <option>-c</option> option. When no parameter is specified, <application>rsyslog</application> tries to be compatible with <application>sysklogd</application>. This is partially achieved by activating configuration directives that modify your configuration accordingly. Therefore, it is advisable to supply this option with a number that matches the major version of <application>rsyslog</application> that is in use and update your <filename>/etc/rsyslog.conf</filename> configuration file accordingly. If you want to, for example, use <application>sysklogd</application> options (which were deprecated in version 3 of <application>rsyslog</application>), you can specify so by executing the following command:
- </para>
- <screen>~]# rsyslogd -c 2</screen>
- <para>
- Options that are passed to the <systemitem class="daemon">rsyslogd</systemitem> daemon, including the backward compatibility mode, can be specified in the <filename>/etc/sysconfig/rsyslog</filename> configuration file.
- </para>
- <para>
- For more information on various <command>rsyslogd</command> options, refer to <command>man rsyslogd</command>.
- </para>
+ <section id="s2-global_directives">
+ <title>Global Directives</title>
+ <para>
+ Global directives are configuration options that apply to the <systemitem class="daemon">rsyslogd</systemitem> daemon. They usually specify a value for a specific predefined variable that affects the behavior of the <systemitem class="daemon">rsyslogd</systemitem> daemon or a rule that follows. All of the global directives must start with a dollar sign (<literal>$</literal>). 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:
+ </para>
+ <screen>
+$MainMsgQueueSize 50000
+ </screen>
+ <para>
+ The default size defined for this directive (<constant>10,000</constant> messages) can be overridden by specifying a different value (as shown in the example above).
+ </para>
+ <para>
+ You may define multiple directives in your <filename>/etc/rsyslog.conf</filename> configuration file. A directive affects the behavior of all configuration options until another occurrence of that same directive is detected. Global directives can be used to configure actions, queues and for debugging. A comprehensive list of all available configuration directives can be found in <xref linkend="brid-Log_Files-Resources-Online"/>. Currently, a new configuration format has been developed that replaces the $-based syntax (see <xref linkend="s2-using_the_new_configuration_format"/>). However, classic global directives remain supported as a legacy format.
+ </para>
</section>
- </section>
-
- <!-- TBD! filed bug: https://bugzilla.redhat.com/show_bug.cgi?id=672563
-
- <section id="s1-rsyslog-performance">
- <title><application>rsyslog</application> Performance</title>
- <para>
-
- </para>
-
- </section> -->
-
- <section id="s1-logfiles-locating">
- <title>Locating Log Files</title>
- <indexterm significance="normal">
- <primary>log files</primary>
- <secondary>locating</secondary>
- </indexterm>
- <para>Most log files are located in the <filename>/var/log/</filename> directory. Some applications such as <command>httpd</command> and <command>samba</command> have a directory within <filename>/var/log/</filename> for their log files.</para>
- <indexterm significance="normal">
- <primary>log files</primary>
- <secondary>rotating</secondary>
- </indexterm>
- <indexterm significance="normal">
- <primary>
- <command>logrotate</command>
- </primary>
- </indexterm>
- <para>You may notice multiple files in the <filename>/var/log/</filename> directory with numbers after them (for example, <filename>cron-20100906</filename>). These numbers represent a timestamp that has been added to a rotated log file. Log files are rotated so their file sizes do not become too large. The <filename>logrotate</filename> package contains a cron task that automatically rotates log files according to the <filename>/etc/logrotate.conf</filename> configuration file and the configuration files in the <filename>/etc/logrotate.d/</filename> directory.</para>
- <section id="configuring-logrotate">
- <title>Configuring logrotate</title>
- <para>
+ <section id="s2-log_rotation">
+ <title>Log Rotation</title>
+ <para>
The following is a sample <filename>/etc/logrotate.conf</filename> configuration file:
</para>
<screen>
@@ -833,12 +810,12 @@ rotate 4
compress
</screen>
<para>
- All of the lines in the sample configuration file define global options that apply to every log file. In our example, log files are rotated weekly, rotated log files are kept for the duration of 4 weeks, and all rotated log files are compressed by <application>gzip</application> into the <literal>.gz</literal> format. Any lines that begin with a hash sign (#) are comments and are not processed</para>
+ All of the lines in the sample configuration file define global options that apply to every log file. In our example, log files are rotated weekly, rotated log files are kept for four weeks, and all rotated log files are compressed by <application>gzip</application> into the <literal>.gz</literal> format. Any lines that begin with a hash sign (#) are comments and are not processed.</para>
<para>
- You may define configuration options for a specific log file and place it under the global options. However, it is advisable to create a separate configuration file for any specific log file in the <filename>/etc/logrotate.d/</filename> directory and define any configuration options there.
+ You may define configuration options for a specific log file and place it under the global options. However, it is advisable to create a separate configuration file for any specific log file in the <filename class="directory">/etc/logrotate.d/</filename> directory and define any configuration options there.
</para>
<para>
- The following is an example of a configuration file placed in the <filename>/etc/logrotate.d/</filename> directory:
+ The following is an example of a configuration file placed in the <filename class="directory">/etc/logrotate.d/</filename> directory:
</para>
<screen>
/var/log/messages {
@@ -850,193 +827,1547 @@ compress
}
</screen>
<para>
- The configuration options in this file are specific for the <filename>/var/log/messages</filename> log file only. The settings specified here override the global settings where possible. Thus the rotated <filename>/var/log/messages</filename> log file will be kept for five weeks instead of four weeks as was defined in the global options.
+ The configuration options in this file are specific for the <filename>/var/log/messages</filename> log file only. The settings specified here override the global settings where possible. Thus the rotated <filename>/var/log/messages</filename> log file will be kept for five weeks instead of four weeks as was defined in the global options.
+ </para>
+ <para>
+ The following is a list of some of the directives you can specify in your <application>logrotate</application> configuration file:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <parameter>weekly</parameter> — Specifies the rotation of log files to be done weekly. Similar directives include:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <parameter>daily</parameter>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>monthly</parameter>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>yearly</parameter>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>compress</parameter> — Enables compression of rotated log files. Similar directives include:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <parameter>nocompress</parameter>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>compresscmd</parameter> — Specifies the command to be used for compressing.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>uncompresscmd</parameter>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>compressext</parameter> — Specifies what extension is to be used for compressing.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>compressoptions</parameter> — Lets you specify any options that may be passed to the used compression program.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>delaycompress</parameter> — Postpones the compression of log files to the next rotation of log files.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>rotate <replaceable>INTEGER</replaceable>
+ </parameter> — Specifies the number of rotations a log file undergoes before it is removed or mailed to a specific address. If the value <constant>0</constant> is specified, old log files are removed instead of rotated.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>mail <replaceable>ADDRESS</replaceable>
+ </parameter> — This option enables mailing of log files that have been rotated as many times as is defined by the <parameter>rotate</parameter> directive to the specified address. Similar directives include:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <parameter>nomail</parameter>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>mailfirst</parameter> — Specifies that the just-rotated log files are to be mailed, instead of the about-to-expire log files.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>maillast</parameter> — Specifies that the about-to-expire log files are to be mailed, instead of the just-rotated log files. This is the default option when <parameter>mail</parameter> is enabled.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ <para>
+ For the full list of directives and various configuration options, see the <filename>logrotate(5)</filename> manual page.
+ </para>
+ </section>
+ <section id="s2-using_the_new_configuration_format">
+ <title>Using the New Configuration Format</title>
+ <para>
+ In <application>rsyslog</application> version 6, a new configuration syntax has been introduced. This new configuration format aims to be more powerful, more intuitive, and to prevent common mistakes by not permitting certain invalid constructs. The syntax enhancement is enabled by the new configuration processor that relies on RainerScript. The legacy format is still fully supported and it is used by default in the <filename>/etc/rsyslog.conf</filename> configuration file.
+ </para>
+ <para>
+ RainerScript is a scripting language designed for processing network events and configuring event processors such as <application>rsyslog</application>. RainerScript was primarily used to define expression-based filters, see <xref linkend="ex-expression-based_filters"/>. The newest version of RainerScript implements the <function>input()</function> and <function>ruleset()</function> statements, which permit the <filename>/etc/rsyslog.conf</filename> configuration file to be written in the new style only.
+ </para>
+ <para>
+ In the following examples you can compare the configuration written with legacy-style parameters:
+ </para>
+ <screen>
+$InputFileName /tmp/inputfile
+$InputFileTag tag1:
+$InputFileStateFile inputfile-state
+$InputRunFileMonitor
+ </screen>
+ <para>
+ and the same configuration with use of the new format statement:
+ </para>
+ <screen>
+input(type="imfile" file="/tmp/inputfile" tag="tag1:" statefile="inputfile-state")
+ </screen>
+ <para>
+ This significantly reduces the number of parameters used in configuration, improves readability, and also provides higher execution speed. For more information on RainerScript statements and parameters see <xref linkend="brid-Log_Files-Resources-Online"/>.
+ </para>
+ </section>
+ <section id="s2-Rulesets">
+ <title>Rulesets</title>
+ <para>
+ Leaving special directives aside, <application>rsyslog</application> handles messages as defined by <emphasis>rules</emphasis> that consist of a filter condition and an action to be performed if the condition is true. With a traditionally written <filename>/etc/rsyslog.conf</filename> file, all rules are evaluated in order of appearance for every input message. This process starts with the first rule and continues until all rules have been processed or until the message is discarded by one of the rules.
+ </para>
+ <para>
+ However, rules can be grouped into sequences called <firstterm>rulesets</firstterm>. With rulesets, you can limit the effect of certain rules only to selected inputs or enhance the performance of <application>rsyslog</application> by defining a distinct set of actions bound to a specific input. In other words, filter conditions that will be inevitably evaluated as false for certain types of messages can be skipped. With the new configuration format, the <function>input()</function> and <function>ruleset()</function> statements are reserved for this operation. The ruleset definition in <filename>/etc/rsyslog.conf</filename> can look as follows:
+ </para>
+ <screen>
+ruleset(name="<replaceable>rulesetname</replaceable>") {
+ <replaceable>rule</replaceable>
+ <replaceable>rule2</replaceable>
+ call <replaceable>rulesetname2</replaceable>
+ …
+}
+ </screen>
+ <!--
+ <screen>
+$RuleSet <replaceable>rulesetname</replaceable>
+<replaceable>rule</replaceable>
+<replaceable>rule2</replaceable>
+call <replaceable>rulesetname2</replaceable>
+…
+ </screen>-->
+ <para>
+ Replace <replaceable>rulesetname</replaceable> with an identifier for your ruleset. The ruleset name cannot start with <literal>RSYSLOG_</literal> since this namespace is reserved for use by <application>rsyslog</application>. <literal>RSYSLOG_DefaultRuleset</literal> then defines the default set of rules to be performed if the message has no other ruleset assigned. With <replaceable>rule</replaceable> and <replaceable>rule2</replaceable> you can define rules in filter-action format mentioned above. With the <parameter>call</parameter> parameter, you can nest rulesets by calling them from inside other ruleset blocks.
+ </para>
+ <para>
+ After creating a ruleset, you need to specify what input it will apply to:
+ </para>
+ <synopsis>input(type="<replaceable>input_type</replaceable>" port="<replaceable>port_num</replaceable>" ruleset="<replaceable>rulesetname</replaceable>");</synopsis>
+ <para>
+ Here you can identify an input message by <replaceable>input_type</replaceable>, which is an input module that gathered the message, or by <replaceable>port_num</replaceable> – the port number. Other parameters such as <emphasis>file</emphasis> or <emphasis>tag</emphasis> can be specified for <function>input()</function>. Replace <replaceable>rulesetname</replaceable> with a name of the ruleset to be evaluated against the message. In case an input message is not explicitly bound to a ruleset, the default ruleset is triggered.
+ </para>
+ <para>
+ You can also use the legacy format to define rulesets, for more information see <xref linkend="brid-Log_Files-Resources-Online"/>.
+ </para>
+ <example id="ex-using_rulesets">
+ <title>Using rulesets</title>
+ <para>
+ The following rulesets ensure different handling of remote messages coming from different ports. Add the following into <filename>/etc/rsyslog.conf</filename>:
+ </para>
+ <screen>
+ruleset(name="remote-10514") {
+ action(type="omfile" file="/var/log/remote-10514")
+}
+
+ruleset(name="remote-10515") {
+ cron.* action(type="omfile" file="/var/log/remote-10515-cron")
+ mail.* action(type="omfile" file="/var/log/remote-10515-mail")
+}
+
+input(type="imtcp" port="10514" ruleset="remote-10514");
+input(type="imtcp" port="10515" ruleset="remote-10515");
+ </screen>
+ <para>
+ Rulesets shown in the above example define log destinations for the remote input from two ports, in case of 10515, messages are sorted according to the facility. Then, the TCP input is enabled and bound to rulesets. Note that you must load the required modules (imtcp) for this configuration to work.
+ </para>
+ </example>
+ </section>
+ <section id="s2-compatibility_with_syslogd">
+ <title>Compatibility with syslogd</title>
+ <para>
+ From <application>rsyslog</application> version 6, compatibility mode specified via the <option>-c</option> option has been removed. Also, the syslogd-style command line options are deprecated and configuring <application>rsyslog</application> through these command line options should be avoided. However, you can use several templates and directives to configure <systemitem class="daemon">rsyslogd</systemitem> to emulate syslogd-like behavior.
+ </para>
+ <para>
+ For more information on various <systemitem class="daemon">rsyslogd</systemitem> options, see the <filename>rsyslogd(8)</filename>manual page.
+ </para>
+ </section>
+ </section>
+ <section id="s1-working_with_queues_in_rsyslog">
+ <title>Working with Queues in Rsyslog</title>
+ <para>
+ Queues are used to pass content, mostly syslog messages, between components of <application>rsyslog</application>. With queues, rsyslog is capable of processing multiple messages simultaneously and to apply several actions to a single message at once. The data flow inside <application>rsyslog</application> can be illustrated as follows:
+ </para>
+ <figure id="fig-message_flow_in_rsyslog">
+ <title>Message Flow in Rsyslog</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/rsyslog_message_flow.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <para>Message Flow in Rsyslog</para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ <para>
+ Whenever <application>rsyslog</application> receives a message, it passes this message to the preprocessor and then places it into the <firstterm>main message queue</firstterm>. Messages wait there to be dequeued and passed to the <firstterm>rule processor</firstterm>.
+ </para>
+ <para>
+ The <emphasis>rule processor</emphasis> is a parsing and filtering engine. Here, the rules defined in <filename>/etc/rsyslog.conf</filename> are applied. Based on these rules, the rule processor evaluates which actions are to be performed. Each action has its own action queue. Messages are passed through this queue to the respective action processor which creates the final output. Note that at this point, several actions can run simultaneously on one message. For this purpose, a message is duplicated and passed to multiple action processors.
+ </para>
+ <para>
+ Only one queue per action is possible. Depending on configuration, the messages can be sent right to the action processor without action queuing. This is the behavior of <emphasis>direct queues</emphasis> (see below). In case the output action fails, the action processor notifies the action queue, which then takes an unprocessed element back and after some time interval, the action is attempted again.
+ </para>
+ <para>
+ To sum up, there are two positions where queues stand in <application>rsyslog</application>: either in front of the rule processor as a single <emphasis>main message queue</emphasis> or in front of various types of output actions as <emphasis>action queues</emphasis>. Queues provide two main advantages that both lead to increased performance of message processing:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ they serve as buffers that <emphasis>decouple</emphasis> producers and consumers in the structure of <application>rsyslog</application>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ they allow for <emphasis>parallelization</emphasis> of actions performed on messages
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Apart from this, queues can be configured with several directives to provide optimal performance for your system. These configuration options are covered in the following sections.
+ </para>
+ <section id="s2-defining_queues">
+ <title>Defining Queues</title>
+ <para>
+ Based on where the messages are stored, there are several types of queues: <emphasis>direct</emphasis>, <emphasis>in-memory</emphasis>, <emphasis>disk</emphasis>, and <emphasis>disk-assisted in-memory</emphasis> queues that are most widely used. You can choose one of these types for the main message queue and also for action queues. Add the following into <filename>/etc/rsyslog.conf</filename>:
+ </para>
+ <synopsis>$<replaceable>object</replaceable>QueueType <replaceable>queue_type</replaceable></synopsis>
+ <para>
+ Here, you can apply the setting for the main message queue (replace <replaceable>object</replaceable> with <option>MainMsg</option>) or for an action queue (replace <replaceable>object</replaceable> with <option>Action</option>). Replace <replaceable>queue_type</replaceable> with one of <literal>direct</literal>, <literal>linkedlist</literal> or <literal>fixedarray</literal> (which are in-memory queues), or <literal>disk</literal>.
+
+ </para>
+ <para>
+ The default setting for a main message queue is the FixedArray queue with a limit of 10,000 messages. Action queues are by default set as Direct queues.
+ </para>
+ <!-- about action queues in new fmt
+ <para>
+ Queues are defined inside the <function>action()</function> object that can stand both separately or inside a ruleset in <filename>etc/rsyslog.conf</filename> . To configure an action queue, type:
+ </para>
+ <synopsis>action(type="<replaceable>action_type</replaceable>" queue.size="<replaceable>queue_size</replaceable>" queue.type="<replaceable>queue_type</replaceable>" file="<replaceable>path</replaceable>")</synopsis>
+ <para>
+ The <replaceable>action_type</replaceable> attribute stands for the name of the module that performs the action. Replace <replaceable>queue_size</replaceable> with a maximum number of messages the queue can contain. with <replaceable>queue_type</replaceable>, you can define a queue type, which is one of <literal>direct</literal>, <literal>linkedlist</literal> or <literal>fixedarray</literal> (which are in-memory queues), and <literal>disk</literal>. See table for list of queue-related parameters applicable to both action queues and the main message queue.
+ </para>
+ <example id="ex-defining_an_action_queue">
+ <title>Defining an Action Queue</title>
+ <para>
+ To configures the output action with an (asynchronous) linked-list based action queue which can hold a maximum of 10,000 messages, use the following syntax:
+ </para>
+ <synopsis>action(type="omfile" queue.size="10000" queue.type="linkedlist" file="/var/log/logfile")</synopsis>
+ </example>
+ <para>
+ Tabulka...queue.mode, sync.. http://www.rsyslog.com/doc/node32.html There are various types of queues: LinkedList, Direct... queue type - default - LinkedList for ruleset queues, Direct for action queues
+ </para>
+ -->
+ <bridgehead id="br-direct_queues">Direct Queues</bridgehead>
+ <para>
+ For many simple operations, such as when writing output to a local file, building a queue in front of an action is not needed. To avoid queuing, use:
+ </para>
+ <synopsis>$<replaceable>object</replaceable>QueueType Direct</synopsis>
+ <para>
+ Replace <replaceable>object</replaceable> with <option>MainMsg</option> or with <option>Action</option> to use this option to the main message queue or for an action queue respectively. With direct queue, messages are passed directly and immediately from the producer to the consumer.
+ </para>
+ <bridgehead id="br-disk_queues">Disk Queues</bridgehead>
+ <para>
+ Disk queues store messages strictly on a hard drive, which makes them highly reliable but also the slowest of all possible queuing modes. This mode can be used to prevent the loss of highly important log data. However, disk queues are not recommended in most use cases. To set a disk queue, type the following into <filename>/etc/rsyslog.conf</filename>:
+ </para>
+ <synopsis>$<replaceable>object</replaceable>QueueType Disk</synopsis>
+ <para>
+ Replace <replaceable>object</replaceable> with <option>MainMsg</option> or with <option>Action</option> to use this option to the main message queue or for an action queue respectively. Disk queues are written in parts, with a default size 10 Mb. This default size can be modified with the following configuration directive:
+ </para>
+ <synopsis>$<replaceable>object</replaceable>QueueMaxFileSize <replaceable>size</replaceable></synopsis>
+ <para>
+ where <replaceable>size</replaceable> represents the specified size of disk queue part. The defined size limit is not restrictive, <application>rsyslog</application> always writes one complete queue entry, even if it violates the size limit. Each part of a disk queue matches with an individual file. The naming directive for these files looks as follows:
+ </para>
+ <synopsis>$<replaceable>object</replaceable>QueueFilename <replaceable>name</replaceable></synopsis>
+ <para>
+ This sets a <replaceable>name</replaceable> prefix for the file followed by a 7-digit number starting at one and incremented for each file.
+ </para>
+ <bridgehead id="br-in-memory_queues">In-memory Queues</bridgehead>
+ <para>
+ With in-memory queue, the enqueued messages are held in memory which makes the process very fast. The queued data is lost if the computer is power cycled or shut down. However, you can use the <option>$ActionQueueSaveOnShutdown</option> setting to save the data before shutdown. There are two types of in-memory queues:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>FixedArray</emphasis> queue — the default mode for the main message queue, with a limit of 10,000 elements. This type of queue uses a fixed, pre-allocated array that holds pointers to queue elements. Due to these pointers, even if the queue is empty a certain amount of memory is consumed. However, FixedArray offers the best run time performance and is optimal when you expect a relatively low number of queued messages and high performance.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>LinkedList</emphasis> queue — here, all structures are dynamically allocated in a linked list, thus the memory is allocated only when needed. LinkedList queues handle occasional message bursts very well.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ In general, use LinkedList queues when in doubt. Compared to FixedArray, it consumes less memory and lowers the processing overhead.
+ </para>
+ <para>
+ Use the following syntax to configure in-memory queues:
+ </para>
+ <synopsis>$<replaceable>object</replaceable>QueueType LinkedList</synopsis>
+ <synopsis>$<replaceable>object</replaceable>QueueType FixedArray</synopsis>
+ <para>
+ Replace <replaceable>object</replaceable> with <option>MainMsg</option> or with <option>Action</option> to use this option to the main message queue or for an action queue respectively.
+ </para>
+ <bridgehead id="br-disk-assisted_in-memory_queues">Disk-Assisted In-memory Queues</bridgehead>
+ <para>
+ Both disk and in-memory queues have their advantages and <application>rsyslog</application> lets you combine them in <emphasis>disk-assisted in-memory queues</emphasis>. To do so, configure a normal in-memory queue and then add the <option>$objectQueueFileName</option> directive to define a file name for disk assistance. This queue then becomes <emphasis>disk-assisted</emphasis>, which means it couples an in-memory queue with a disk queue to work in tandem.
+ </para>
+ <para>
+ The disk queue is activated if the in-memory queue is full or needs to persist after shutdown. With a disk-assisted queue, you can set both disk-specific and in-memory specific configuration parameters. This type of queue is probably the most commonly used, it is especially useful for potentially long-running and unreliable actions.
+ </para>
+ <para>
+ To specify the functioning of a disk-assisted in-memory queue, use the so-called <emphasis>watermarks</emphasis>:
+ </para>
+ <synopsis>$<replaceable>object</replaceable>QueueHighWatermark <replaceable>number</replaceable></synopsis>
+ <synopsis>$<replaceable>object</replaceable>QueueLowWatermark <replaceable>number</replaceable></synopsis>
+ <para>
+ Replace <replaceable>object</replaceable> with <option>MainMsg</option> or with <option>Action</option> to use this option to the main message queue or for an action queue respectively. Replace <replaceable>number</replaceable> with a number of enqueued messages. When an in-memory queue reaches the number defined by the high watermark, it starts writing messages to disk and continues until the in-memory queue size drops to the number defined with the low watermark. Correctly set watermarks minimize unnecessary disk writes, but also leave memory space for message bursts since writing to disk files is rather lengthy. Therefore, the high watermark must be lower than the whole queue capacity set with <emphasis>$objectQueueSize</emphasis>. The difference between the high watermark and the overall queue size is a spare memory buffer reserved for message bursts. On the other hand, setting the high watermark too low will turn on disk assistance unnecessarily ofte
n.
+ </para>
+ <example id="ex-net_forwarding_with_queue">
+ <title>Reliable Forwarding of Log Messages to a Server</title>
+ <para>
+ Rsyslog is often used to maintain a centralized logging system, where log messages are forwarded to a server over the network. To avoid message loss when the server is not available, it is advisable to configure an action queue for the forwarding action. This way, messages that failed to be sent are stored locally until the server is reachable again. Note that such queues are not configurable for connections using the <systemitem class="protocol">UDP</systemitem> protocol. To establish a fully reliable connection, for example when your logging server is outside of your private network, consider using the RELP protocol described in <xref linkend="s2-using_RELP" />.
+ </para>
+ <procedure id="proc-net_forwarding_with_queue">
+ <title>Forwarding To a Single Server</title>
+ <para>
+ Suppose the task is to forward log messages from the system to a server with host name <emphasis>example.com</emphasis>, and to configure an action queue to buffer the messages in case of a server outage. To do so, perform the following steps:
+ </para>
+ <step>
+ <para>
+ Create a working directory to store the queue files. For example:
+ </para>
+ <synopsis>~]# <command>mkdir</command> <filename class="directory">/rsyslog/work/</filename></synopsis>
+ </step>
+ <step>
+ <para>
+ Use the following configuration in <filename>/etc/rsyslog.conf</filename> or create a file with the following content in the <filename class="directory">/etc/rsyslog.d/</filename> directory:
+ </para>
+ <screen>$WorkDirectory /rsyslog/work
+
+$ActionQueueType LinkedList
+$ActionQueueFileName example_fwd
+$ActionResumeRetryCount -1
+$ActionQueueSaveOnShutdown on
+*.* @@example.com:18</screen>
+ <itemizedlist>
+ <para>
+ Where:
+ </para>
+ <listitem>
+ <para>
+ the <filename class="directory">/rsyslog/work/</filename> directory created in the previous step is marked as a working directory,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>$ActionQueueType</option> enables a LinkedList in-memory queue,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>$ActionFileName</option> defines a disk storage, in this case the backup files are created in the <filename class="directory">/rsyslog/work/</filename> directory with the <emphasis>example_fwd</emphasis> prefix,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the <option>$ActionResumeRetryCount -1</option> setting prevents rsyslog form dropping messages when retrying to connect if server is not responding,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ enabled <option>$ActionQueueSaveOnShutdown</option> saves in-memory data if rsyslog shuts down,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the last line forwards all received messages to the logging server, port specification is optional.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ With the above configuration, rsyslog keeps messages in memory if the remote server is not reachable. A file on disk is created only if rsyslog runs out of the configured memory queue space or needs to shut down, which benefits the system performance.</para>
+ </step>
+ </procedure>
+ <procedure id="proc-net_forwarding_two_servers">
+ <title>Forwarding To Multiple Servers</title>
+ <para>
+ The process of forwarding log messages to multiple servers is similar to the previous procedure:
+ </para>
+ <step>
+ <para>
+ Create a working directory for rsyslog to store the queue files. For example:
+ </para>
+ <synopsis>~]# <command>mkdir</command> <filename class="directory">/rsyslog/work/</filename></synopsis>
+ </step>
+ <step>
+ <para>
+ Each destination server requires a separate forwarding rule, action queue specification, and backup file on disk. For example, use the following configuration in <filename>/etc/rsyslog.conf</filename> or create a file with the following content in the <filename class="directory">/etc/rsyslog.d/</filename> directory:
+ </para>
+ <screen>$WorkDirectory /rsyslog/work
+
+$ActionQueueType LinkedList
+$ActionQueueFileName example_fwd1
+$ActionResumeRetryCount -1
+$ActionQueueSaveOnShutdown on
+*.* @@example1.com
+
+$ActionQueueType LinkedList
+$ActionQueueFileName example_fwd2
+$ActionResumeRetryCount -1
+$ActionQueueSaveOnShutdown on
+*.* @@example2.com</screen>
+ </step>
+ </procedure>
+ </example>
+ </section>
+ <section id="s2-managing_queues">
+ <title>Managing Queues</title>
+ <para>
+ All types of queues can be further configured to match your requirements. You can use several directives to modify both action queues and the main message queue. Currently, there are more than 20 queue parameters available, see <xref linkend="brid-Log_Files-Resources-Online"/>. Some of these settings are used commonly, others, such as worker thread management, provide closer control over the queue behavior and are reserved for advanced users. With advanced settings, you can optimize <application>rsyslog</application>'s performance, schedule queuing, or modify the behavior of queue on system shutdown.
+ </para>
+ <bridgehead id="br-limiting_queue_size">Limiting Queue Size</bridgehead>
+ <para>
+ You can limit the number of messages that queue can contain with the following setting:
+ </para>
+ <synopsis>$<replaceable>object</replaceable>QueueHighWatermark <replaceable>number</replaceable></synopsis>
+ <para>
+ Replace <replaceable>object</replaceable> with <option>MainMsg</option> or with <option>Action</option> to use this option to the main message queue or for an action queue respectively. Replace <replaceable>number</replaceable> with a number of enqueued messages. You can set the queue size only as the number of messages, not as their actual memory size. The default queue size is 10,000 messages for the main message queue and ruleset queues, and 1000 for action queues.
+ </para>
+ <para>
+ Disk assisted queues are unlimited by default and can not be restricted with this directive, but you can reserve them physical disk space in bytes with the following settings:
+ </para>
+ <synopsis>$<replaceable>object</replaceable>QueueMaxDiscSpace <replaceable>number</replaceable></synopsis>
+ <para>
+ Replace <replaceable>object</replaceable> with <option>MainMsg</option> or with <option>Action</option>. When the size limit specified by <replaceable>number</replaceable> is hit, messages are discarded until sufficient amount of space is freed by dequeued messages.
+ </para>
+ <bridgehead id="br-discarding_messages">Discarding Messages</bridgehead>
+ <para>
+ When a queue reaches a certain number of messages, you can discard less important messages in order to save space in the queue for entries of higher priority. The threshold that launches the discarding process can be set with the so-called <emphasis>discard mark</emphasis>:
+ </para>
+ <synopsis>$<replaceable>object</replaceable>QueueDiscardMark <replaceable>number</replaceable></synopsis>
+ <para>
+ Replace <replaceable>object</replaceable> with <option>MainMsg</option> or with <option>Action</option> to use this option to the main message queue or for an action queue respectively. Here, <replaceable>number</replaceable> stands for a number of messages that have to be in the queue to start the discarding process. To define which messages to discard, use:
+ </para>
+ <synopsis>$<replaceable>object</replaceable>QueueDiscardSeverity <replaceable>priority</replaceable></synopsis>
+ <para>
+ Replace <replaceable>priority</replaceable> with one of the following keywords (or with a number): <command>debug</command> (7), <command>info</command> (6), <command>notice</command> (5), <command>warning</command> (4), <command>err</command> (3), <command>crit</command> (2), <command>alert</command> (1), and <command>emerg</command> (0). With this setting, both newly incoming and already queued messages with lower than defined priority are erased from the queue immediately after the discard mark is reached.
+ </para>
+ <bridgehead id="br-using_timeframes">Using Timeframes</bridgehead>
+ <para>
+ You can configure <application>rsyslog</application> to process queues during a specific time period. With this option you can, for example, transfer some processing into off-peak hours. To define a time frame, use the following syntax:
+ </para>
+ <synopsis>$<replaceable>object</replaceable>QueueDequeueTimeBegin <replaceable>hour</replaceable></synopsis>
+ <synopsis>$<replaceable>object</replaceable>QueueDequeueTimeEnd <replaceable>hour</replaceable></synopsis>
+ <para>
+ With <replaceable>hour</replaceable> you can specify hours that bound your time frame. Use the 24-hour format without minutes.
+ </para>
+ <bridgehead id="br-configuring_worker_threads">Configuring Worker Threads</bridgehead>
+ <para>
+ A <firstterm>worker thread</firstterm> performs a specified action on the enqueued message. For example, in the main message queue, a worker task is to apply filter logic to each incoming message and enqueue them to the relevant action queues. When a message arrives, a worker thread is started automatically. When the number of messages reaches a certain number, another worker thread is turned on. To specify this number, use:
+ </para>
+ <synopsis>$<replaceable>object</replaceable>QueueWorkerThreadMinimumMessages <replaceable>number</replaceable></synopsis>
+ <para>
+ Replace <replaceable>number</replaceable> with a number of messages that will trigger a supplemental worker thread. For example, with <replaceable>number</replaceable> set to 100, a new worker thread is started when more than 100 messages arrive. When more than 200 messages arrive, the third worker thread starts and so on. However, too many working threads running in parallel becomes ineffective, so you can limit the maximum number of them by using:
+ </para>
+ <synopsis>$<replaceable>object</replaceable>QueueWorkerThreads <replaceable>number</replaceable></synopsis>
+ <para>
+ where <replaceable>number</replaceable> stands for a maximum number of working threads that can run in parallel. For the main message queue, the default limit is 1 thread. Once a working thread has been started, it keeps running until an inactivity timeout appears. To set the length of timeout, type:
+ </para>
+ <synopsis>$<replaceable>object</replaceable>QueueWorkerTimeoutThreadShutdown <replaceable>time</replaceable></synopsis>
+ <para>
+ Replace <replaceable>time</replaceable> with the duration set in milliseconds. Without this setting, a zero timeout is applied and a worker thread is terminated immediately when it runs out of messages. If you specify <replaceable>time</replaceable> as <literal>-1</literal>, no thread will be closed.
+ </para>
+ <bridgehead id="br-batch_dequeuing">Batch Dequeuing</bridgehead>
+ <para>
+ To increase performance, you can configure <application>rsyslog</application> to dequeue multiple messages at once. To set the upper limit for such dequeueing, use:
+ </para>
+ <synopsis>$<replaceable>object</replaceable>QueueDequeueBatchSize <replaceable>number</replaceable></synopsis>
+ <para>
+ Replace <replaceable>number</replaceable> with the maximum number of messages that can be dequeued at once. Note that a higher setting combined with a higher number of permitted working threads results in greater memory consumption.
+ </para>
+ <bridgehead id="br-terminating_queues">Terminating Queues</bridgehead>
+ <para>
+ When terminating a queue that still contains messages, you can try to minimize the data loss by specifying a time interval for worker threads to finish the queue processing:
+ </para>
+ <synopsis>$<replaceable>object</replaceable>QueueTimeoutShutdown <replaceable>time</replaceable></synopsis>
+ <para>
+ Specify <replaceable>time</replaceable> in milliseconds. If after that period there are still some enqueued messages, workers finish the current data element and then terminate. Unprocessed messages are therefore lost. Another time interval can be set for workers to finish the final element:
+ </para>
+ <synopsis>$<replaceable>object</replaceable>QueueTimeoutActionCompletion <replaceable>time</replaceable></synopsis>
+ <para>
+ In case this timeout expires, any remaining workers are shut down. To save data at shutdown, use:
+ </para>
+ <synopsis>$<replaceable>object</replaceable>QueueTimeoutSaveOnShutdown <replaceable>time</replaceable></synopsis>
+ <para>
+ If set, all queue elements are saved to disk before <application>rsyslog</application> terminates.
+ </para>
+ </section> <!--
+ <section id="s2-examples_of_usage">
+ <title>Examples of Usage</title>
+ <para>
+ Generic Act Queue Example ........priklad na frontu...
+ </para>
+ <para>
+ New_Fwd_Spool - priklad - posielanie na server, tcp forwarding , TCP forwarding syntax (@@)
+ http://www.rsyslog.com/doc/rsyslog_reliable_forwarding.html
+ http://www.arix.com/docs/rsyslog-3.22.1/log_rotation_fix_size.html
+ mentioned already? Sending syslog Messages over the Network
+ </para>
+ </section> -->
+ </section>
+ <section id="s1-using_rsyslog_modules">
+ <title>Using Rsyslog Modules</title>
+ <para>
+ Due to its modular design, <application>rsyslog</application> offers a variety of <firstterm>modules</firstterm> which provide additional functionality. Note that modules can be written by third parties. Most modules provide additional inputs (see <emphasis>Input Modules</emphasis> below) or outputs (see <emphasis>Output Modules</emphasis> below). Other modules provide special functionality specific to each module. The modules may provide additional configuration directives that become available after a module is loaded. To load a module, use the following syntax:
+ </para>
+ <screen>
+$ModLoad <replaceable>MODULE</replaceable>
+ </screen>
+ <para>
+ where <option>$ModLoad</option> is the global directive that loads the specified module and <replaceable>MODULE</replaceable> represents your desired module. For example, if you want to load the Text File Input Module (<command>imfile</command>) that enables <application>rsyslog</application> to convert any standard text files into syslog messages, specify the following line in the <filename>/etc/rsyslog.conf</filename> configuration file:
+ </para>
+ <screen>
+$ModLoad imfile
+ </screen>
+ <para>
+ <application>rsyslog</application> offers a number of modules which are split into the following main categories:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Input Modules — Input modules gather messages from various sources. The name of an input module always starts with the <literal>im</literal> prefix, such as <command>imfile</command>, <command>imjournal</command>, etc.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Output Modules — Output modules provide a facility to issue message to various targets such as sending across a network, storing in a database, or encrypting. The name of an output module always starts with the <literal>om</literal> prefix, such as <command>omsnmp</command>, <command>omrelp</command>, etc.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Parser Modules — These modules are useful in creating custom parsing rules or to parse malformed messages. With moderate knowledge of the C programming language, you can create your own message parser. The name of a parser module always starts with the <literal>pm</literal> prefix, such as <command>pmrfc5424</command>, <command>pmrfc3164</command>, and so on.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Message Modification Modules — Message modification modules change content of syslog messages. Names of these modules start with the <literal>mm</literal> prefix. Message Modification Modules such as <command>mmanon</command>, <command>mmnormalize</command>, or <command>mmjsonparse</command> are used for anonymization or normalization of messages.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ String Generator Modules — String generator modules generate strings based on the message content and strongly cooperate with the template feature provided by <application>rsyslog</application>. For more information on templates, see <xref linkend="s2-Templates"/>. The name of a string generator module always starts with the <literal>sm</literal> prefix, such as <command>smfile</command> or <command>smtradfile</command>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Library Modules — Library modules provide functionality for other loadable modules. These modules are loaded automatically by <application>rsyslog</application> when needed and cannot be configured by the user.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ A comprehensive list of all available modules and their detailed description can be found at <ulink url="http://www.rsyslog.com/doc/rsyslog_conf_modules.html/">http://www.rsyslog.com/doc/rsyslog_conf_modules.html</ulink>.
+ </para>
+ <warning>
+ <para>
+ Note that when <application>rsyslog</application> 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.
+ </para>
+ </warning>
+ <section id="s2-importing_text_files">
+ <title>Importing Text Files</title>
+ <para>
+ The Text File Input Module, abbreviated as <command>imfile</command>, enables <application>rsyslog</application> to convert any text file into a stream of syslog messages. You can use <command>imfile</command> to import log messages from applications that create their own text file logs. To load <command>imfile</command>, add the following into <filename>etc/rsyslog.conf</filename>:
+ </para>
+ <screen>
+$ModLoad imfile
+$InputFilePollInterval <replaceable>int</replaceable>
+ </screen>
+ <para>
+ It is sufficient to load <command>imfile</command> once, even when importing multiple files. The <emphasis>$InputFilePollInterval</emphasis> global directive specifies how often <application>rsyslog</application> checks for changes in connected text files. The default interval is 10 seconds, to change it, replace <replaceable>int</replaceable> with a time interval specified in seconds.
+ </para>
+ <para>
+ To identify the text files to import, use the following syntax in <filename>/etc/rsyslog.conf</filename>:
+ </para>
+ <screen>
+# File 1
+$InputFileName <replaceable>path_to_file</replaceable>
+$InputFileTag <replaceable>tag:</replaceable>
+$InputFileStateFile <replaceable>state_file_name</replaceable>
+$InputFileSeverity <replaceable>severity</replaceable>
+$InputFileFacility <replaceable>facility</replaceable>
+$InputRunFileMonitor
+
+# File 2
+$InputFileName <replaceable>path_to_file2</replaceable>
+...
+ </screen>
+ <para>
+ Four settings are required to specify an input text file:
+ </para>
+ <itemizedlist >
+ <listitem>
+ <para>
+ replace <replaceable>path_to_file</replaceable> with a path to the text file.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ replace <replaceable>tag:</replaceable> with a tag name for this message.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ replace <replaceable>state_file_name</replaceable> with a unique name for the <emphasis>state file</emphasis>. <emphasis>State files</emphasis>, which are stored in the rsyslog working directory, keep cursors for the monitored files, marking what partition has already been processed. If you delete them, whole files will be read in again. Make sure that you specify a name that does not already exist.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ add the <emphasis>$InputRunFileMonitor</emphasis> directive that enables the file monitoring. Without this setting, the text file will be ignored.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Apart from the required directives, there are several other settings that can be applied on the text input. Set the severity of imported messages by replacing <replaceable>severity</replaceable> with an appropriate keyword. Replace <replaceable>facility</replaceable> with a keyword to define the subsystem that produced the message. The keywords for severity and facility are the same as those used in facility/priority-based filters, see <xref linkend="s2-Filters" />.
+ </para>
+ <example id="ex-importing_text_files">
+ <title>Importing Text Files</title>
+ <para>
+ The Apache HTTP server creates log files in text format. To apply the processing capabilities of <application>rsyslog</application> to apache error messages, first use the <command>imfile</command> module to import the messages. Add the following into <filename>/etc/rsyslog.conf</filename>:
+ </para>
+ <screen>
+$ModLoad imfile
+
+$InputFileName /var/log/httpd/error_log
+$InputFileTag apache-error:
+$InputFileStateFile state-apache-error
+$InputRunFileMonitor
+ </screen>
+ </example>
+ </section>
+ <section id="s2-exporting_messages_to_a_database">
+ <title>Exporting Messages to a Database</title>
+ <para>
+ Processing of log data can be faster and more convenient when performed in a database rather than with text files. Based on the type of DBMS used, choose from various output modules such as <command>ommysql</command>, <command>ompgsql</command>, <command>omoracle</command>, or <command>ommongodb</command>. As an alternative, use the generic <command>omlibdbi</command> output module that relies on the <systemitem class="library">libdbi</systemitem> library. The <command>omlibdbi</command> module supports database systems Firebird/Interbase, MS SQL, Sybase, SQLite, Ingres, Oracle, mSQL, MySQL, and PostgreSQL.
+ </para> <!--
+ <para>
+ To load the module, type the following into <filename>/etc/rsyslog.conf</filename>:
+ </para>
+ <screen>
+$ModLoad omlibdbi
+ </screen>
+ <para>
+ Then use the following directives to set the database connection:
+ </para>
+ <screen>
+$ActionLibdbiDriver <replaceable>driver</replaceable>
+$ActionLibdbiHost <replaceable>host</replaceable>
+$ActionLibdbiUserName <replaceable>user</replaceable>
+$ActionLibdbiPassword <replaceable>pwd</replaceable>
+$ActionLibdbiDBName <replaceable>db_name</replaceable>
+*.* :omlibdbi:
+ </screen>
+ <para>
+ Here, replace <replaceable>driver</replaceable> with a driver name (mysql), <replaceable>host</replaceable> with a hostname <replaceable>user</replaceable> with username, <replaceable>pwd</replaceable> with a pasword for your database, <replaceable>db_name</replaceable> with a unique name for your database.
+ </para> -->
+ <example id="ex-exporting_rsyslog_messages_to_a_database">
+ <title>Exporting Rsyslog Messages to a Database</title>
+ <para>
+ To store the rsyslog messages in a MySQL database, add the following into <filename>/etc/rsyslog.conf</filename>:
+ </para>
+ <screen>
+$ModLoad ommysql
+
+$ActionOmmysqlServerPort 1234
+*.* :ommysql:database-server,database-name,database-userid,database-password
+ </screen>
+ <para>
+ First, the output module is loaded, then the communication port is specified. Additional information, such as name of the server and the database, and authentication data, is specified on the last line of the above example.
+ </para>
+ <!--
+ <screen>
+$ModLoad omlibdbi
+
+$ActionLibdbiDriver mysql
+$ActionLibdbiHost mysqlserver.example.com
+$ActionLibdbiUserName user
+$ActionLibdbiPassword mypassword
+$ActionLibdbiDBName mysyslogdb
+*.* :omlibdbi:
+ </screen> -->
+ </example>
+ </section>
+ <section id="s2-enabling_encrypted_transport">
+ <title>Enabling Encrypted Transport</title>
+ <para>
+ Confidentiality and integrity in network transmissions can be provided by either the <emphasis>TLS</emphasis> or <emphasis>GSSAPI</emphasis> encryption protocol.
+ </para>
+ <para>
+ <emphasis>Transport Layer Security</emphasis> (TLS) is a cryptographic protocol designed to provide communication security over the network. When using TLS, rsyslog messages are encrypted before sending, and mutual authentication exists between the sender and receiver.
+ </para>
+ <para>
+ <emphasis>Generic Security Service API</emphasis> (GSSAPI) is an application programming interface for programs to access security services. To use it in connection with <application>rsyslog</application> you must have a functioning <application>Kerberos</application> environment.
+ </para>
+ <!--
+ <bridgehead id="br-using_TLS">Using TLS</bridgehead>
+ <para>
+ To facilitate the encrypted transport through TLS, you need to configure both the server and client. First, create public key, private key and certificate file, see <xref linkend="s3-apache-mod_ssl-genkey"/>
+ </para>
+ <para>
+ On the <emphasis>server</emphasis> side, configure the following options:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Set the gtls netstream driver as the default driver:
+ </para>
+ <screen>
+$DefaultNetstreamDriver gtls
+ </screen>
+ </listitem>
+ <listitem>
+ <para>
+ Provide paths to certificate files:
+ </para>
+ <screen>
+$DefaultNetstreamDriverCAFile <replaceable>path_ca.pem</replaceable>
+$DefaultNetstreamDriverCertFile <replaceable>path_cert.pem</replaceable>
+$DefaultNetstreamDriverKeyFile <replaceable>path_key.pem</replaceable>
+ </screen>
+ <para>
+ Replace <replaceable>path_ca.pem</replaceable> with a path to your public key, <replaceable>path_cert.pem</replaceable> with a path to the certificate file and <replaceable>path_key.pem</replaceable> with a path to the private key.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Load the imtcp module:
+ </para>
+ <screen>
+$ModLoad imtcp
+ </screen>
+ </listitem>
+ <listitem>
+ <para>
+ Start the server and set driver options:
+ </para>
+ <screen>
+$InputTCPServerStreamDriverMode <replaceable>number</replaceable>
+$InputTCPServerStreamDriverAuthMode <replaceable>anon</replaceable>
+$InputTCPServerRun <replaceable>port</replaceable>
+ </screen>
+ <para>
+ Here, you can set the driver mode by replacing <replaceable>number</replaceable>, write <literal>1</literal> to enable TCP-only mode. The <replaceable>anon</replaceable> setting means that the client is not authenticated. Replace <replaceable>port</replaceable> to start a listener at the required port.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ On the <emphasis>client</emphasis> side, use the following configuration:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Load the public key:
+ </para>
+ <screen>
+$DefaultNetstreamDriverCAFile <replaceable>path_ca.pem</replaceable>
+ </screen>
+ <para>
+ Replace <replaceable>path_ca.pem</replaceable> with a path to the public key.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Set the gtls netstream driver as the default driver:
+ </para>
+ <screen>
+$DefaultNetstreamDriver gtls
+ </screen>
+ </listitem>
+ <listitem>
+ <para>
+ Configure the driver and specify what action will be performed:
+ </para>
+ <screen>
+$InputTCPServerStreamDriverMode <replaceable>number</replaceable>
+$InputTCPServerStreamDriverAuthMode <replaceable>anon</replaceable>
+*.* @@server.net:10514
+ </screen>
+ <para>
+ Replace <replaceable>number</replaceable> and <replaceable>anon</replaceable> according to the corresponding server settings. On the last line, an example action forwards messages from the server to the specified TCP port.
+ </para>
+ </listitem>
+ </orderedlist>
+ <bridgehead id="s3-using_GSSAPI">Using GSSAPI</bridgehead>
+ <para>
+ In <application>rsyslog</application>, interaction with GSSAPI is provided by the <emphasis>imgssapi</emphasis> module. To turn on the GSSAPI transfer mode, use the following configuration in <filename>/etc/rsyslog.conf</filename>:
+ </para>
+ <screen>
+$ModLoad imgssapi
+ </screen>
+ <para>
+ This directive loads the imgssapi module. After doing so, you can specify the input as follows:
+ </para>
+ <screen>
+$InputGSSServerServiceName <replaceable>name</replaceable>
+$InputGSSServerPermitPlainTCP <literal>on/off</literal>
+$InputGSSServerMaxSessions <replaceable>number</replaceable>
+$InputGSSServerRun <replaceable>port</replaceable>
+ </screen>
+ <para>
+ You can set a name for the GSS server by replacing <replaceable>name</replaceable>. Turn on the <emphasis>$InputGSSServerPermitPlainTCP</emphasis> setting to permit the server to receive also plain TCP messages on the same port. This is not permitted by default. Replace <replaceable>number</replaceable> to set the maximum number of sessions supported, by default, this number is not limited. Replace <replaceable>port</replaceable> with a selected port on which you want to start a GSS server.
+ </para>
+ <note>
+ <para>
+ The <systemitem>imgssapi</systemitem> module is initialized as soon as the configuration file reader encounters the $InputGSSServerRun directive in the <filename>/etc/rsyslog.conf</filename> configuration file. The supplementary options configured after $InputGSSServerRun are therefore ignored. For configuration to take effect, all imgssapi configuration options must be placed before $InputGSSServerRun.
+ </para>
+ </note>
+ <example id="ex-using_GSSAPI">
+ <title>Using GSSAPI</title>
+ <para>
+ The following configuration enables a GSS server on the port 1514 that also permits to receive plain tcp syslog messages on the same port.
+ </para>
+ <screen>
+$ModLoad imgssapi
+$InputGSSServerPermitPlainTCP on
+$InputGSSServerRun 1514
+ </screen>
+ </example>
+ -->
+ </section>
+ <section id="s2-using_RELP">
+ <title>Using RELP</title>
+ <para>
+ <emphasis>Reliable Event Logging Protocol</emphasis> (RELP) is a networking protocol for data logging in computer networks. It is designed to provide reliable delivery of event messages, which makes it useful in environments where message loss is not acceptable.
+ </para>
+ <!--
+ <para>
+ Similarly to basic TLS configuration, you need to perform tree steps: create certificates, configure the server and the client.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ First, create public key, private key and certificate file, see <xref linkend="s3-apache-mod_ssl-genkey"/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ To configure the client, load the required modules:
+ </para>
+ <screen>
+module(load="imuxsock")
+module(load="omrelp")
+module(load="imtcp")
+ </screen>
+ <para>
+ Configure the TCP input as follows:
+ </para>
+ <screen>
+input(type="imtcp" port="<replaceable>port</replaceable>″)
+ </screen>
+ <para>
+ Replace <replaceable>port</replaceable> to start a listener at the required port.
+ </para>
+ <para>
+ With new configuration format, all transport settings are defined as parameters of one action:
+ </para>
+ <screen>
+action(type="omrelp" target="<replaceable>target_IP</replaceable>″ port="<replaceable>target_port</replaceable>″ tls="on"
+tls.caCert="<replaceable>path_ca.pem</replaceable>"
+tls.myCert="<replaceable>path_cert.pem</replaceable>"
+tls.myPrivKey="<replaceable>path_key.pem</replaceable>"
+tls.authmode="<replaceable>mode</replaceable>"
+tls.permittedpeer=["<replaceable>peer_name</replaceable>"]
+)
+ </screen>
+ <para>
+ Here, <replaceable>target_IP</replaceable> and <replaceable>target_port</replaceable> are used to identify the target server, the <emphasis>tls="on"</emphasis> setting enables the TLS protocol. Pass paths to your certification files with <replaceable>path_ca.pem</replaceable>, <replaceable>path_cert.pem</replaceable>, and <replaceable>path_key.pem</replaceable>. To set authentication mode for the transaction, replace <replaceable>mode</replaceable> with ether <emphasis>"name"</emphasis> or <emphasis>"fingerprint"</emphasis>. With <emphasis>tls.permittedpeer</emphasis>, you can restrict connection to selected group of peers. Replace <replaceable>peer_name</replaceable> with a certificate fingerprint of the permitted peer.
+
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The server configuration starts with module loading:
+ </para>
+ <screen>
+module(load="imuxsock")
+module(load="imrelp" ruleset="relp")
+ </screen>
+ <para>
+ Configure the TCP input similarly to the client configuration:
+ </para>
+ <screen>
+input(type="imrelp" port="<replaceable>target_port</replaceable>″ tls="on"
+tls.caCert="<replaceable>path_ca.pem</replaceable>"
+tls.myCert="<replaceable>path_cert.pem</replaceable>"
+tls.myPrivKey="<replaceable>path_key.pem</replaceable>"
+tls.authmode="<replaceable>name</replaceable>"
+tls.permittedpeer=["<replaceable>peer_name</replaceable>","<replaceable>peer_name1</replaceable>","<replaceable>peer_name2</replaceable>"]
+)
+ </screen>
+ <para>
+ These input parameters have the same meaning as the client configuration options explained in the step two. In the final step, configure the rulese and choose an action to be performed. In the following example, messages are stored in the location:
+ </para>
+ <screen>
+ruleset (name="relp") {
+action(type="omfile" file="<replaceable>log_path</replaceable>")
+}
+ </screen>
+ <para>
+ Here, replace <replaceable>log_path</replaceable> with a path to a directory, where you want to store your log files.
+ </para>
+ </listitem>
+ </orderedlist> -->
+ </section>
+ </section>
+ <section id="s1-interaction_of_rsyslog_and_journal">
+ <title>Interaction of Rsyslog and Journal</title>
+ <para>
+ As mentioned above, <application>Rsyslog</application> and <application>Journal</application>, the two logging applications present on your system, have several distinctive features that make them suitable for specific use cases. In many situations it is useful to combine their capabilities, for example to create structured messages and store them in a file database (see <xref linkend="s1-structured_logging_with_rsyslog" />). A communication interface needed for this cooperation is provided by input and output modules on the side of <application>Rsyslog</application> and by the <application>Journal</application>'s communication socket.
+ </para>
+ <para>
+ By default, <systemitem class="daemon">rsyslogd</systemitem> uses the <systemitem>imjournal</systemitem> module as a default input mode for journal files. With this module, you import not only the messages but also the structured data provided by <systemitem class="daemon">journald</systemitem>. Also, older data can be imported from <systemitem class="daemon">journald</systemitem> (unless forbidden with the <option>$ImjournalIgnorePreviousMessages</option> directive). See <xref linkend="s2-importing_data_from_journal" /> for basic configuration of <systemitem>imjournal</systemitem>.
+ </para>
+ <para>
+ As an alternative, configure <systemitem class="daemon">rsyslogd</systemitem> to read from the socket provided by <systemitem class="daemon">journal</systemitem> as an output for syslog-based applications. The path to the socket is <filename>/run/systemd/journal/syslog</filename>. Use this option when you want to maintain plain rsyslog messages. Compared to <systemitem>imjournal</systemitem> the socket input currently offers more features, such as ruleset binding or filtering. To import <application>Journal</application> data trough the socket, use the following configuration in <filename>/etc/rsyslog.conf</filename>:
+ </para>
+ <screen>
+$ModLoad imuxsock
+$OmitLocalLogging off
+ </screen>
+ <para>
+ The above syntax loads the <systemitem>imuxsock</systemitem> module and turns off the <option>$OmitLocalLogging</option> directive, which enables the import trough the system socket. The path to this socket is specified separately in <filename>/etc/rsyslog.d/listen.conf</filename> as follows:
+ </para>
+ <screen>
+$SystemLogSocketName /run/systemd/journal/syslog
+ </screen>
+ <para>
+ You can also output messages from <application>Rsyslog</application> to <application>Journal</application> with the <systemitem>omjournal</systemitem> module. Configure the output in <filename>/etc/rsyslog.conf</filename> as follows:
+ </para>
+ <screen>
+$ModLoad omjournal
+
+*.* :omjournal:
+ </screen>
+ <para>
+ For instance, the following configuration forwards all received messages on tcp port 10514 to the Journal:
+ </para>
+ <screen>
+$ModLoad imtcp
+$ModLoad omjournal
+
+$RuleSet remote
+*.* :omjournal:
+
+$InputTCPServerBindRuleset remote
+$InputTCPServerRun 10514
+ </screen>
+ </section>
+ <section id="s1-structured_logging_with_rsyslog">
+ <title>Structured Logging with Rsyslog</title>
+ <para>
+ On systems that produce large amounts of log data, it can be convenient to maintain log messages in a <emphasis>structured format</emphasis>. With structured messages, it is easier to search for particular information, to produce statistics and to cope with changes and inconsistencies in message structure. <application>Rsyslog</application> uses the <emphasis>JSON</emphasis> (JavaScript Object Notation) format to provide structure for log messages.
+ </para>
+ <para>
+ Compare the following unstructured log message:
+ </para>
+ <synopsis>Oct 25 10:20:37 localhost anacron[1395]: Jobs will be executed sequentially</synopsis>
+ <para>
+ with a structured one:
+ </para>
+ <synopsis>{"timestamp":"2013-10-25T10:20:37", "host":"localhost", "program":"anacron", "pid":"1395", "msg":"Jobs will be executed sequentially"}</synopsis>
+ <para>
+ Searching structured data with use of key-value pairs is faster and more precise than searching text files with regular expressions. The structure also lets you to search for the same entry in messages produced by various applications. Also, JSON files can be stored in a document database such as <database class="name">MongoDB</database>, which provides additional performance and analysis capabilities. On the other hand, a structured message requires more disk space than the unstructured one.
+ </para>
+ <para>
+ In <application>rsyslog</application>, log messages with meta data are pulled from <application>Journal</application> with use of the <systemitem>imjournal</systemitem> module. With the <systemitem>mmjsonparse</systemitem> module, you can parse data imported from <application>Journal</application> and from other sources and process them further, for example as a database output. For parsing to be successful, <systemitem>mmjsonparse</systemitem> requires input messages to be structured in a way that is defined by the <emphasis role="bold">Lumberjack</emphasis> project.
+ </para>
+ <para>
+ The <emphasis role="bold">Lumberjack</emphasis> project aims to add structured logging to <application>rsyslog</application> in a backward-compatible way. To identify a structured message, <emphasis role="bold">Lumberjack</emphasis> specifies the <emphasis role="bold">@cee:</emphasis> string that prepends the actual JSON structure. Also, <emphasis role="bold">Lumberjack</emphasis> defines the list of standard field names that should be used for entities in the JSON string. For more information on <emphasis role="bold">Lumberjack</emphasis>, see <xref linkend="brid-Log_Files-Resources-Online"/>.
+ </para>
+ <para>
+ The following is an example of a lumberjack-formatted message:
+ </para>
+ <synopsis>
+ @cee: {"pid":17055, "uid":1000, "gid":1000, "appname":"logger", "msg":"Message text."}
+ </synopsis>
+ <para>
+ To build this structure inside <application>Rsyslog</application>, a template is used, see <xref linkend="s2-filtering_structured_messages" />. Applications and servers can employ the <systemitem class="library">libumberlog</systemitem> library to generate messages in the lumberjack-compliant form. For more information on <systemitem class="library">libumberlog</systemitem>, see <xref linkend="brid-Log_Files-Resources-Online"/>.
+ </para>
+ <section id="s2-importing_data_from_journal">
+ <title>Importing Data from Journal</title>
+ <para>
+ The <command>imjournal</command> module is <application>Rsyslog</application>'s input module to natively read the journal files (see <xref linkend="s1-interaction_of_rsyslog_and_journal" />). Journal messages are then logged in text format as other rsyslog messages. However, with further processing, it is possible to translate meta data provided by <application>Journal</application> into a structured message.
+ </para>
+ <para>
+ To import data from <application>Journal</application> to <application>Rsyslog</application>, use the following configuration in <filename>/etc/rsyslog.conf</filename>:
+ </para>
+ <screen>
+$ModLoad imjournal
+
+$imjournalPersistStateInterval <replaceable>number_of_messages</replaceable>
+$imjournalStateFile <replaceable>path</replaceable>
+$imjournalRatelimitInterval <replaceable>seconds</replaceable>
+$imjournalRatelimitBurst <replaceable>burst_number</replaceable>
+$ImjournalIgnorePreviousMessages <replaceable>off/on</replaceable>
+ </screen>
+ <itemizedlist>
+ <listitem>
+ <para>
+ With <replaceable>number_of_messages</replaceable>, you can specify how often the journal data must be saved. This will happen each time the specified number of messages is reached.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Replace <replaceable>path</replaceable> with a path to the state file. This file tracks the journal entry that was the last one processed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ With <replaceable>seconds</replaceable>, you set the length of the rate limit interval. The number of messages processed during this interval can not exceed the value specified in <replaceable>burst_number</replaceable>. The default setting is 20,000 messages per 600 seconds. Rsyslog discards messages that come after the maximum burst within the time frame specified.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ With <option>$ImjournalIgnorePreviousMessages</option> you can ignore messages that are currently in Journal and import only new messages, which is used when there is no state file specified. The default setting is <literal>off</literal>. Please note that if this setting is off and there is no state file, all messages in the Journal are processed, even if they were already processed in a previous rsyslog session.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <note>
+ <para>
+ You can use <systemitem>imjournal</systemitem> simultaneously with <systemitem>imuxsock</systemitem> module that is the traditional system log input. However, to avoid message duplication, you must prevent <systemitem>imuxsock</systemitem> from reading the Journal's system socket. To do so, use the <option>$OmitLocalLogging</option> directive:
+ </para>
+ <screen>
+$ModLoad imuxsock
+$ModLoad imjournal
+
+$OmitLocalLogging on
+$AddUnixListenSocket /run/systemd/journal/syslog
+ </screen>
+ </note>
+ <para>
+ You can translate all data and meta data stored by <application>Journal</application> into structured messages. Some of these meta data entries are listed in <xref linkend="ex-verbose_journalctl_output" />, for a complete list of journal fields see the <filename>systemd.journal-fields(7)</filename> manual page. For example, it is possible to focus on <emphasis>kernel journal fields</emphasis>, that are used by messages originating in the kernel.
+ </para>
+ </section>
+ <section id="s2-filtering_structured_messages">
+ <title>Filtering Structured Messages</title>
+ <para>
+ To create a lumberjack-formatted message that is required by <application>rsyslog</application>'s parsing module, use the following template:
+ </para>
+ <screen>
+template(name="CEETemplate" type="string" string="%TIMESTAMP% %HOSTNAME% %syslogtag% @cee: %$!all-json%\n")
+ </screen>
+ <para>
+ This template prepends the <literal>@cee:</literal> string to the JSON string and can be applied, for example, when creating an output file with <systemitem>omfile</systemitem> module. To access JSON field names, use the <emphasis role="bold">$!</emphasis> prefix. For example, the following filter condition searches for messages with specific <emphasis>hostname</emphasis> and <emphasis>UID</emphasis> :
+ </para>
+ <screen>
+($!hostname == "<replaceable>hostname</replaceable>" && $!UID== "<replaceable>UID</replaceable>")
+ </screen>
+ </section>
+ <section id="s2-parsing_JSON">
+ <title>Parsing JSON</title>
+ <para>
+ The <systemitem>mmjsonparse</systemitem> module is used for parsing structured messages.
+
+ These messages can come from <application>Journal</application> or from other input sources, and must be formatted in a way defined by the <emphasis role="bold">Lumberjack</emphasis> project. These messages are identified by the presence of the <emphasis role="bold">@cee:</emphasis> string. Then, <systemitem>mmjsonparse</systemitem> checks if the JSON structure is valid and then the message is parsed.
+ </para>
+ <para>
+ To parse lumberjack-formatted JSON messages with <systemitem>mmjsonparse</systemitem>, use the following configuration in the <filename>/etc/rsyslog.conf</filename>:
+ </para>
+ <screen>
+$ModLoad mmjsonparse
+
+*.* :mmjsonparse:
+ </screen>
+ <para>
+ In this example, the <systemitem>mmjsonparse</systemitem> module is loaded on the first line, then all messages are forwarded to it. Currently, there are no configuration parameters available for <systemitem>mmjsonparse</systemitem>.
+ </para>
+ </section>
+ <section id="s2-storing_messages_in_the_mongodb">
+ <title>Storing Messages in the MongoDB</title>
+ <para>
+ <application>Rsyslog</application> supports storing JSON logs in the <database class="name">MongoDB</database> document database through the <emphasis>ommongodb</emphasis> output module.
+ </para>
+ <para>
+ To forward log messages into <database class="name">MongoDB</database>, use the following syntax in the <filename>/etc/rsyslog.conf</filename> (configuration parameters for <emphasis>ommongodb</emphasis> are available only in the new configuration format; see <xref linkend="s2-using_the_new_configuration_format" />):
</para>
+ <screen>
+$ModLoad ommongodb
+
+*.* action(type="ommongodb" server="<replaceable>DB_server</replaceable>" serverport="<replaceable>port</replaceable>" db="<replaceable>DB_name</replaceable>" collection="<replaceable>collection_name</replaceable>" uid="<replaceable>UID</replaceable>" pwd="<replaceable>password</replaceable>")
+ </screen>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Replace <replaceable>DB_server</replaceable> with the name or address of the MongoDB server. Specify <replaceable>port</replaceable> to select a non-standard port from the MongoDB server. The default <replaceable>port</replaceable> value is <literal>0</literal> and usually there is no need to change this parameter.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ With <replaceable>DB_name</replaceable>, you identify to which database on the MongoDB server you want to direct the output. Replace <replaceable>collection_name</replaceable> with the name of a collection in this database. In <database class="name">MongoDB</database>, collection is a group of documents, the equivalent of an RDBMS table.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ You can set your login details by replacing <replaceable>UID</replaceable> and <replaceable>password</replaceable>.
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- The following is a list of some of the directives you can specify in your <application>logrotate</application> configuration file:
+ You can shape the form of the final database output with use of templates. By default, <application>ryslog</application> uses a template based on standard <application>lumberjack</application> field names.
</para>
- <itemizedlist>
- <listitem>
+ </section>
+ </section>
+ <section id="s1-debugging_rsyslog">
+ <title>Debugging Rsyslog</title>
+ <para>
+ To run <systemitem class="daemon">rsyslogd</systemitem> in debugging mode, use the following command:
+ </para>
+ <synopsis><systemitem class="daemon">rsyslogd</systemitem> <option>-dn</option></synopsis>
+ <para>
+ With this command, <systemitem class="daemon">rsyslogd</systemitem> produces debugging information and prints it to the standard output. The <option>-n</option> stands for "no fork". You can modify debugging with environmental variables, for example, you can store the debug output in a log file. Before starting <systemitem class="daemon">rsyslogd</systemitem>, type the following on the command line:
+ </para>
+ <screen>
+export RSYSLOG_DEBUGLOG="<replaceable>path</replaceable>"
+export RSYSLOG_DEBUG="Debug"
+ </screen>
<para>
- <parameter>weekly</parameter> — Specifies the rotation of log files on a weekly basis. Similar directives include:
- <itemizedlist>
- <listitem>
- <para>
- <parameter>daily</parameter>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>monthly</parameter>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>yearly</parameter>
- </para>
- </listitem>
- </itemizedlist>
+ Replace <replaceable>path</replaceable> with a desired location for the file where the debugging information will be logged. For a complete list of options available for the RSYSLOG_DEBUG variable, see the related section in the <filename>rsyslogd(8)</filename> manual page.
</para>
- </listitem>
- <listitem>
<para>
- <parameter>compress</parameter> — Enables compression of rotated log files. Similar directives include:
- <itemizedlist>
- <listitem>
- <para>
- <parameter>nocompress</parameter>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>compresscmd</parameter> — Specifies the command to be used for compressing.
- </para>
- </listitem>
- <listitem>
+ To check if syntax used in the <filename>etc/rsyslog.conf</filename> file is valid use:
+ </para>
+ <synopsis><systemitem class="daemon">rsyslogd</systemitem> <option>-N</option> <literal>1</literal></synopsis>
+ <para>
+ Where <literal>1</literal> represents level of verbosity of the output message. This is a forward compatibility option because currently, only one level is provided. However, you must add this argument to run the validation.
+ </para>
+ </section>
+ <section id="s1-Using_the_Journal">
+ <title>Using the Journal</title>
+ <para>
+ The Journal is a component of <application>systemd</application> that is responsible for viewing and management of log files. It can be used in parallel, or in place of a traditional syslog daemon, such as <systemitem class="daemon">rsyslogd</systemitem>. The Journal was developed to address problems connected with traditional logging. It is closely integrated with the rest of the system, supports various logging technologies and access management for the log files.
+ </para>
+ <para>
+ Logging data is collected, stored, and processed by the Journal's <systemitem class="daemon">journald</systemitem> service. It creates and maintains binary files called <emphasis>journals</emphasis> based on logging information that is received from the kernel, from user processes, from standard output, and standard error output of system services or via its native API. These journals are structured and indexed, which provides relatively fast seek times. Journal entries can carry a unique identifier. The <systemitem class="daemon">journald</systemitem> service collects numerous meta data fields for each log message. The actual journal files are secured, and therefore cannot be manually edited.
+ </para>
+ <section id="s2-Viewing_Log_Files">
+ <title>Viewing Log Files</title>
+ <para>
+ To access the journal logs, use the <application>journalctl</application> tool. For a basic view of the logs type as <systemitem class="username">root</systemitem>:
+ </para>
+ <synopsis><command>journalctl</command></synopsis>
+ <para>
+ An output of this command is a list of all log files generated on the system including messages generated by system components and by users. The structure of this output is similar to one used in <filename>/var/log/messages/</filename> but with certain improvements:
+ </para>
+ <itemizedlist>
+ <listitem>
<para>
- <parameter>uncompresscmd</parameter>
+ the priority of entries is marked visually. Lines of error priority and higher are highlighted with red color and a bold font is used for lines with notice and warning priority
</para>
- </listitem>
- <listitem>
+ </listitem>
+ <listitem>
<para>
- <parameter>compressext</parameter> — Specifies what extension is to be used for compressing.
+ the time stamps are converted for the local time zone of your system
</para>
- </listitem>
- <listitem>
+ </listitem>
+ <listitem>
<para>
- <parameter>compressoptions</parameter> — Lets you specify any options that may be passed to the used compression program.
+ all logged data is shown, including rotated logs
</para>
- </listitem>
- <listitem>
+ </listitem>
+ <listitem>
<para>
- <parameter>delaycompress</parameter> — Postpones the compression of log files to the next rotation of log files.
+ the beginning of a boot is tagged with a special line
</para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
+ </listitem>
+ </itemizedlist>
+ <example id="ex-Example_Output_of_journalctl">
+ <title>Example Output of journalctl</title>
+ <para>
+ The following is an example output provided by the <application>journalctl</application> tool. When called without parameters, the listed entries begin with a time stamp, then the host name and application that performed the operation is mentioned followed by the actual message. This example shows the first three entries in the journal log:
+ </para>
+ <screen>
+# <command>journalctl</command>
+-- Logs begin at Thu 2013-08-01 15:42:12 CEST, end at Thu 2013-08-01 15:48:48 CEST. --
+Aug 01 15:42:12 localhost systemd-journal[54]: Allowing runtime journal files to grow to 49.7M.
+Aug 01 15:42:12 localhost kernel: Initializing cgroup subsys cpuset
+Aug 01 15:42:12 localhost kernel: Initializing cgroup subsys cpu
+
+[...]
+ </screen>
+ </example>
+ <para>
+ In many cases, only the latest entries in the journal log are relevant. The simplest way to reduce <command>journalctl</command> output is to use the <option>-n</option> option that lists only the specified number of most recent log entries:
+ </para>
+ <synopsis><command>journalctl</command> <option>-n</option> <replaceable>Number</replaceable></synopsis>
+ <para>
+ Replace <replaceable>Number</replaceable> with the number of lines to be shown. When no number is specified, <command>journalctl</command> displays the ten most recent entries.
+ </para>
+ <para>
+ The <command>journalctl</command> command allows controlling the form of the output with the following syntax:
+ </para>
+ <synopsis><command>journalctl</command> <option>-o</option> <replaceable>form</replaceable></synopsis>
+ <para>
+ Replace <replaceable>form</replaceable> with a keyword specifying a desired form of output. There are several options, such as <option>verbose</option>, which returns full-structured entry items with all fields, <option>export</option>, which creates a binary stream suitable for backups and network transfer, and <option>json</option>, which formats entries as JSON data structures. For the full list of keywords, see the <filename>journalctl(1)</filename> manual page.
+ </para>
+ <example id="ex-verbose_journalctl_output">
+ <title>Verbose journalctl Output</title>
+ <para>
+ To view full meta data about all entries, type:
+ </para>
+ <screen>
+# <command>journalctl</command> <option>-o verbose</option>
+[...]
+
+Fri 2013-08-02 14:41:22 CEST [s=e1021ca1b81e4fc688fad6a3ea21d35b;i=55c;b=78c81449c920439da57da7bd5c56a770;m=27cc
+ _BOOT_ID=78c81449c920439da57da7bd5c56a770
+ PRIORITY=5
+ SYSLOG_FACILITY=3
+ _TRANSPORT=syslog
+ _MACHINE_ID=69d27b356a94476da859461d3a3bc6fd
+ _HOSTNAME=localhost.localdomain
+ _PID=562
+ _COMM=dbus-daemon
+ _EXE=/usr/bin/dbus-daemon
+ _CMDLINE=/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation
+ _SYSTEMD_CGROUP=/system/dbus.service
+ _SYSTEMD_UNIT=dbus.service
+ SYSLOG_IDENTIFIER=dbus
+ SYSLOG_PID=562
+ _UID=81
+ _GID=81
+ _SELINUX_CONTEXT=system_u:system_r:system_dbusd_t:s0-s0:c0.c1023
+ MESSAGE=[system] Successfully activated service 'net.reactivated.Fprint'
+ _SOURCE_REALTIME_TIMESTAMP=1375447282839181
+
+[...]
+ </screen>
+ <para>
+ This example lists fields that identify a single log entry. These meta data can be used for message filtering as shown in <xref linkend="advanced_filtering"/>. For a complete description of all possible fields see the <filename>systemd.journal-fields(7)</filename> manual page.
+ </para>
+ </example>
+ </section>
+ <section id="s2-Access_Control">
+ <title>Access Control</title>
+ <para>
+ By default, <application>Journal</application> users without <systemitem class="username">root</systemitem> privileges can only see log files generated by them. The system administrator can add selected users to the <emphasis>adm</emphasis> group, which grants them access to complete log files. To do so, type as <systemitem class="username">root</systemitem>:
+ </para>
+ <synopsis><command>usermod</command> <option>-a</option> <option>-G</option> <emphasis>adm</emphasis> <replaceable>username</replaceable></synopsis>
+ <para>
+ Here, replace <replaceable>username</replaceable> with a name of the user to be added to the <emphasis>adm</emphasis> group. This user then receives the same output of the <command>journalctl</command> command as the root user. Note that access control only works when persistent storage is enabled for <application>Journal</application>.
+ </para>
+ </section>
+ <section id="s2-Using_The_Live_View">
+ <title>Using The Live View</title>
+ <para>
+ When called without parameters, <command>journalctl</command> shows the full list of entries, starting with the oldest entry collected. With the live view, you can supervise the log messages in real time as new entries are continuously printed as they appear. To start <application>journalctl</application> in live view mode, type:
+ </para>
+ <synopsis><command>journalctl</command> <option>-f</option></synopsis>
+ <para>
+ This command returns a list of the ten most current log lines. The <application>journalctl</application> utility then stays running and waits for new changes to show them immediately.
+ </para>
+ </section>
+ <section id="s2-Filtering_Messages">
+ <title>Filtering Messages</title>
+ <para>
+ The output of the <command>journalctl</command> command executed without parameters is often extensive, therefore you can use various filtering methods to extract information to meet your needs.
+ </para>
+ <bridgehead id="filtering_by_priority">Filtering by Priority</bridgehead>
+ <para>
+ Log messages are often used to track erroneous behavior on the system. To view only entries with a selected or higher priority, use the following syntax:
+ </para>
+ <synopsis><command>journalctl</command> <option>-p</option> <replaceable>priority</replaceable></synopsis>
+ <para>
+ Here, replace <replaceable>priority</replaceable> with one of the following keywords (or with a number): <command>debug</command> (7), <command>info</command> (6), <command>notice</command> (5), <command>warning</command> (4), <command>err</command> (3), <command>crit</command> (2), <command>alert</command> (1), and <command>emerg</command> (0).
+ </para>
+ <example id="ex-filtering_by_priority">
+ <title>Filtering by Priority</title>
<para>
- <parameter>rotate <replaceable><INTEGER></replaceable>
- </parameter> — Specifies the number of rotations a log file undergoes before it is removed or mailed to a specific address. If the value <constant>0</constant> is specified, old log files are removed instead of rotated.
+ To view only entries with <emphasis>error</emphasis> or higher priority, use:
</para>
- </listitem>
- <listitem>
+ <synopsis><command>journalctl</command> <option>-p err</option></synopsis>
+ </example>
+ <bridgehead id="filtering_by_time">Filtering by Time</bridgehead>
+ <para>
+ To view log entries only from the current boot, type:
+ </para>
+ <synopsis><command>journalctl</command> <option>-b</option></synopsis>
+ <para>
+ If you reboot your system just occasionally, the <option>-b</option> will not significantly reduce the output of <command>journalctl</command>. In such cases, time-based filtering is more helpful:
+ </para>
+ <synopsis><command>journalctl</command> <option>--since</option>=<replaceable>value</replaceable> <option>--until</option>=<replaceable>value</replaceable></synopsis>
<para>
- <parameter>mail <replaceable><ADDRESS></replaceable>
- </parameter> — This option enables mailing of log files that have been rotated as many times as is defined by the <parameter>rotate</parameter> directive to the specified address. Similar directives include:
+ With <option>--since</option> and <option>--until</option>, you can view only log messages created within a specified time range. You can pass <replaceable>values</replaceable> to these options in form of date or time or both as shown in the following example.
</para>
- <itemizedlist>
- <listitem>
- <para>
- <parameter>nomail</parameter>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>mailfirst</parameter> — Specifies that the just-rotated log files are to be mailed, instead of the about-to-expire log files.
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>maillast</parameter> — Specifies that the just-rotated log files are to be mailed, instead of the about-to-expire log files. This is the default option when <parameter>mail</parameter> is enabled.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
+ <example id="ex-filtering_by_time_and_priority">
+ <title>Filtering by Time and Priority</title>
+ <para>
+ Filtering options can be combined to reduce the set of results according to specific requests. For example, to view the <emphasis>warning</emphasis> or higher priority messages from a certain point in time, type:
+ </para>
+ <synopsis><command>journalctl</command> <option>-p warning</option> <option>--since="2013-3-16 23:59:59"</option></synopsis>
+ </example>
+ <bridgehead id="advanced_filtering">Advanced Filtering</bridgehead>
+ <para>
+ <xref linkend="ex-verbose_journalctl_output"/> lists a set of fields that specify a log entry and can all be used for filtering. For a complete description of meta data that <systemitem>systemd</systemitem> can store, see the <filename>systemd.journal-fields(7)</filename> manual page. This meta data is collected for each log message, without user intervention. Values are usually text-based, but can take binary and large values; fields can have multiple values assigned though it is not very common.
+ </para>
+ <para>
+ To view a list of unique values that occur in a specified field, use the following syntax:
+ </para>
+ <synopsis><command>journalctl</command> <option>-F</option> <replaceable>fieldname</replaceable></synopsis>
+ <para>
+ Replace <replaceable>fieldname</replaceable> with a name of a field you are interested in.
+ </para>
+ <para>
+ To show only log entries that fit a specific condition, use the following syntax:
+ </para>
+ <synopsis><command>journalctl</command> <replaceable>fieldname</replaceable>=<replaceable>value</replaceable></synopsis>
+ <para>
+ Replace <replaceable>fieldname</replaceable> with a name of a field and <replaceable>value</replaceable> with a specific value contained in that field. As a result, only lines that match this condition are returned.
+ </para>
+ <note>
+ <title><keycap>Tab</keycap> Completion on Field Names</title>
+ <para>
+ As the number of meta data fields stored by <systemitem>systemd</systemitem> is quite large, it is easy to forget the exact name of the field of interest. When unsure, type:
+ </para>
+ <synopsis><command>journalctl</command></synopsis>
+ <para>
+ and press the <keycap>Tab</keycap> key two times. This shows a list of available field names. <keycap>Tab</keycap> completion based on context works on field names, so you can type a distinctive set of letters from a field name and then press <keycap>Tab</keycap> to complete the name automatically. Similarly, you can list unique values from a field. Type:
+ </para>
+ <synopsis><command>journalctl</command> <replaceable>fieldname</replaceable>=</synopsis>
+ <para>
+ and press <keycap>Tab</keycap> two times. This serves as an alternative to <command>journalctl</command> <option>-F</option> <replaceable>fieldname</replaceable>.
+ </para>
+ </note>
+ <para>
+ You can specify multiple values for one field:
+ </para>
+ <synopsis><command>journalctl</command> <replaceable>fieldname</replaceable>=<replaceable>value1</replaceable> <replaceable>fieldname</replaceable>=<replaceable>value2</replaceable> ...</synopsis>
+ <para>
+ Specifying two matches for the same field results in a logical <function>OR</function> combination of the matches. Entries matching <replaceable>value1</replaceable> or <replaceable>value2</replaceable> are displayed.
+ </para>
+ <para>
+ Also, you can specify multiple field-value pairs to further reduce the output set:
+ </para>
+ <synopsis><command>journalctl</command> <replaceable>fieldname1</replaceable>=<replaceable>value</replaceable> <replaceable>fieldname2</replaceable>=<replaceable>value</replaceable> ...</synopsis>
+ <para>
+ If two matches for different field names are specified, they will be combined with a logical <function>AND</function>. Entries have to match both conditions to be shown.
+ </para>
+ <para>
+ With use of the <emphasis>+</emphasis> symbol, you can set a logical <function>OR</function> combination of matches for multiple fields:
+ </para>
+ <synopsis><command>journalctl</command> <replaceable>fieldname1</replaceable>=<replaceable>value</replaceable> + <replaceable>fieldname2</replaceable>=<replaceable>value</replaceable> ...</synopsis>
+ <para>
+ This command returns entries that match at least one of the conditions, not only those that match both of them.
+ </para>
+ <example id="ex-advanced_filtering">
+ <title>Advanced filtering</title>
+ <para>
+ To display entries created by <systemitem class="daemon">avahi-daemon.service</systemitem> or <systemitem class="daemon">crond.service</systemitem> under user with UID 70, use the following command:
+ </para>
+ <synopsis><command>journalctl</command> <literal>_UID=70</literal> <literal>_SYSTEMD_UNIT=avahi-daemon.service</literal> <literal>_SYSTEMD_UNIT=crond.service</literal></synopsis>
+ <para>
+ Since there are two values set for the <literal>_SYSTEMD_UNIT</literal> field, both results will be displayed, but only when matching the <literal>_UID=70</literal> condition. This can be expressed simply as: (UID=70 and (avahi or cron)).
+ </para>
+ </example>
+ <para>
+ You can apply the aforementioned filtering also in the live-view mode to keep track of the latest changes in the selected group of log entries:
+ </para>
+ <synopsis><command>journalctl</command> <option>-f</option> <replaceable>fieldname</replaceable>=<replaceable>value</replaceable> ...</synopsis>
+ <!--
+ <para>
+ To view messages from services of a current user type:
+ </para>
+ <synopsis><command>journalctl</command> <option>-user-unit=</option></synopsis>
+ <para>
+ To view messages from system services and the kernel type:
+ </para>
+ <synopsis><command>journalctl</command> <option>-service</option></synopsis>
+ <para>
+ You can also specify a directory path as an argument to view log entries connected with that directory:
+ </para>
+ <synopsis><command>journalctl</command> <option>-D</option> <replaceable>path</replaceable></synopsis>
+ <para>
+ Replace <replaceable>path</replaceable> with a path to the directory you want to inspect.
+ </para>
+
+ -->
+ </section>
+ <section id="s2-Enabling_Persistent_Storage">
+ <title>Enabling Persistent Storage</title>
+ <para>By default, <application>Journal</application> stores log files only in memory or a small ring-buffer in the <filename class="directory">/run/log/journal/</filename> directory. This is sufficient to show recent log history with <command>journalctl</command>. This directory is volatile, log data is not saved permanently. With the default configuration, syslog reads the journal logs and stores them in the <filename class="directory">/var/log/</filename> directory. With persistent logging enabled, journal files are stored in <filename>/var/log/journal</filename> which means they persist after reboot. Journal can then replace <application>rsyslog</application> for some users (but see the chapter introduction).
+ </para>
+ <para>
+ Enabled persistent storage has the following advantages
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Richer data is recorded for troubleshooting in a longer period of time
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ For immediate troubleshooting, richer data is available after a reboot
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Server console currently reads data from journal, not log files
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Persistent storage has also certain disadvantages:
+ </para>
+ <itemizedlist >
+ <listitem>
+ <para>
+ Even with persistent storage the amount of data stored depends on free memory, there is no guarantee to cover a specific time span
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ More disk space is needed for logs
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ To enable persistent storage for Journal, create the journal directory manually as shown in the following example. As <systemitem class="username">root</systemitem> type:
+ </para>
+ <synopsis><command>mkdir</command> <option>-p</option> <filename class="directory">/var/log/journal</filename></synopsis>
+ <para>
+ Then, restart <systemitem class="daemon">journald</systemitem> to apply the change:
+ </para>
+ <synopsis><command>systemctl</command> <option>restart</option> <systemitem class="daemon">systemd-journald</systemitem></synopsis>
+ </section>
+ <!--
+ <section id="s2-journald_conf">
+ <title>Configuring journald</title>
<para>
- For the full list of directives and various configuration options, refer to the <command>logrotate</command> man page (<command>man logrotate</command>).
+ You can configure <systemitem class="daemon">journald</systemitem> with use of the <filename>/etc/systemd/journald.conf</filename>. Much of the configuration options are related to data storage
+ </para>
+ <para>
+ To view the full list of configuration options see the <filename>journald.conf</filename> manual page.
</para>
+ </section> -->
</section>
- </section>
- <section id="s1-logfiles-viewing">
+ <section id="s1-managing_log_files_in_a_graphical_environment">
+ <title>Managing Log Files in a Graphical Environment</title>
+ <para>
+ As an alternative to the aforementioned command-line utilities, Red Hat Enterprise Linux 7 provides an accessible GUI for managing log messages.
+ </para>
+ <section id="s2-logfiles-viewing">
<title>Viewing Log Files</title>
- <indexterm significance="normal">
+ <indexterm>
<primary>log files</primary>
<secondary>viewing</secondary>
</indexterm>
- <para>Most log files are in plain text format. You can view them with any text editor such as <command>Vi</command> or <application>Emacs</application>. Some log files are readable by all users on the system; however, <systemitem class="username">root</systemitem> privileges are required to read most log files.</para>
- <indexterm significance="normal">
- <primary>
- <command>gnome-system-log</command>
- </primary>
- <see>
- <application>Log File Viewer</application>
- </see>
+ <para>Most log files are stored in plain text format. You can view them with any text editor such as <command>Vi</command> or <application>Emacs</application>. Some log files are readable by all users on the system; however, root privileges are required to read most log files.</para>
+ <indexterm>
+ <primary><command>gnome-system-log</command></primary>
+ <see><application>System Log</application></see>
</indexterm>
- <para>To view system log files in an interactive, real-time application, use the <application>Log File Viewer</application>.
+ <para>To view system log files in an interactive, real-time application, use the <application>System Log</application>.
</para>
<note>
<title>Installing the gnome-system-log package</title>
- <para>In order to use the <application>Log File Viewer</application>, first ensure the <package>gnome-system-log</package> package is installed on your system by running, as <systemitem class="username">root</systemitem>:</para>
- <screen><command>yum install gnome-system-log</command></screen>
- <para>For more information on installing packages with Yum, refer to <xref linkend="sec-Installing"/>.</para>
+ <para>In order to use the <application>System Log</application>, first ensure the <package>gnome-system-log</package> package is installed on your system by running, as <systemitem class="username">root</systemitem>:</para>
+ <screen>~]# <command>yum install gnome-system-log</command>
+ </screen>
+ <para>For more information on installing packages with Yum, see <xref linkend="sec-Installing"/>.</para>
</note>
- <para>After you have installed the <package>gnome-system-log</package> package, you can open the <application>Log File Viewer</application> by selecting <menuchoice><guimenu>Applications</guimenu><guisubmenu>System Tools</guisubmenu><guimenuitem>Log File Viewer</guimenuitem></menuchoice> from the <guimenu>Activities</guimenu> menu, or type the following command at a shell prompt:</para>
- <screen><command>gnome-system-log</command></screen>
+ <para>After you have installed the <package>gnome-system-log</package> package, open the <application>System Log</application> by clicking <menuchoice><guimenu>Applications</guimenu><guimenuitem>System Tools</guimenuitem><guimenuitem>System Log</guimenuitem></menuchoice>, or type the following command at a shell prompt:</para>
+ <screen>~]$ <command>gnome-system-log</command>
+ </screen>
<para>The application only displays log files that exist; thus, the list might differ from the one shown in <xref linkend="fig-redhat-logviewer"/>.</para>
- <indexterm significance="normal">
- <primary>
- <application>Log File Viewer</application>
- </primary>
+ <indexterm>
+ <primary><application>System Log</application></primary>
<secondary>searching</secondary>
</indexterm>
- <indexterm significance="normal">
- <primary>
- <application>Log File Viewer</application>
- </primary>
+ <indexterm>
+ <primary><application>System Log</application></primary>
<secondary>filtering</secondary>
</indexterm>
<figure id="fig-redhat-logviewer">
- <title>
- Log File Viewer
- </title>
+ <title>System Log</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/system-log-viewer.png" format="PNG" scalefit="0" />
+ <imagedata fileref="images/redhat-logviewer.png" format="PNG"/>
</imageobject>
<textobject>
- <para>Log File Viewer</para>
+ <para>System Log</para>
</textobject>
</mediaobject>
</figure>
- <indexterm significance="normal">
- <primary>
- <application>Log Viewer</application>
- </primary>
+ <indexterm>
+ <primary><application>System Log</application></primary>
<secondary>refresh rate</secondary>
</indexterm>
- <para>The <application>Log File Viewer</application> application lets you filter any existing log file. Click on <guimenuitem>Filters</guimenuitem> from the menu and select <guimenuitem>Manage Filters</guimenuitem> to define or edit your desired filter.</para>
+ <para>The <application>System Log</application> application lets you filter any existing log file. Click on the button marked with the gear symbol to view the menu, select <menuchoice><guimenuitem>Filters</guimenuitem> <guimenuitem>Manage Filters</guimenuitem></menuchoice> to define or edit the desired filter.</para>
<figure id="fig-redhat-filters">
- <title>
- Log File Viewer — filters
- </title>
+ <title>System Log - Filters</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/system-log-viewer-filters-manage.png" format="PNG" scalefit="0" />
+ <imagedata fileref="images/redhat-filters.png" format="PNG"/>
</imageobject>
<textobject>
- <para>Log File Viewer — filters</para>
+ <para>System Log - Filters</para>
</textobject>
</mediaobject>
</figure>
<para>Adding or editing a filter lets you define its parameters as is shown in <xref linkend="fig-redhat-filter-sample"/>.</para>
<figure id="fig-redhat-filter-sample">
- <title>
- Log File Viewer — defining a filter
- </title>
+ <title>System Log - defining a filter</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/system-log-viewer-filters-define.png" format="PNG" scalefit="0" />
+ <imagedata fileref="images/redhat-filter-sample.png" format="PNG" />
</imageobject>
<textobject>
- <para>Log File Viewer — defining a filter</para>
+ <para>System Log - Defining a Filter</para>
</textobject>
</mediaobject>
</figure>
<para>
- When defining a filter, you can edit the following parameters:
+ When defining a filter, the following parameters can be edited:
</para>
<itemizedlist>
<listitem>
@@ -1068,38 +2399,36 @@ compress
</listitem>
</itemizedlist>
<para>
- When you have at least one filter defined, you may select it from the <guilabel>Filters</guilabel> menu and it will automatically search for the strings you have defined in the filter and highlight/hide every successful match in the log file you are currently viewing.
+ When you have at least one filter defined, it can be selected from the <guilabel>Filters</guilabel> menu and it will automatically search for the strings you have defined in the filter and highlight or hide every successful match in the log file you are currently viewing.
</para>
<figure id="fig-redhat-filter-enable">
- <title>
- Log File Viewer — enabling a filter
- </title>
+ <title>System Log - enabled filter</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/system-log-viewer-filters-enable.png" format="PNG" scalefit="0" />
+ <imagedata fileref="images/redhat-filter-enable.png" format="PNG"/>
</imageobject>
<textobject>
- <para>Log File Viewer — enabling a filter</para>
+ <para>System Log - Enabling a Filter</para>
</textobject>
</mediaobject>
</figure>
<para>
- When you check the <guilabel>Show matches only</guilabel> option, only the matched strings will be shown in the log file you are currently viewing.
+ When you select the <guilabel>Show matches only</guilabel> option, only the matched strings will be shown in the log file you are currently viewing.
</para>
</section>
- <section id="s1-logfiles-adding">
+ <section id="s2-logfiles-adding">
<title>Adding a Log File</title>
- <para>To add a log file you wish to view in the list, select <menuchoice><guimenu>File</guimenu>
+ <para>To add a log file you want to view in the list, select <menuchoice><guimenu>File</guimenu>
<guimenuitem>Open</guimenuitem>
- </menuchoice>. This will display the <guilabel>Open Log</guilabel> window where you can select the directory and file name of the log file you wish to view.<xref linkend="fig-redhat-logviewer-add"/> illustrates the <guimenu>Open Log</guimenu> window.</para>
+ </menuchoice>. This will display the <guilabel>Open Log</guilabel> window where you can select the directory and file name of the log file you want to view. <xref linkend="fig-redhat-logviewer-add"/> illustrates the <guimenu>Open Log</guimenu> window.</para>
<figure id="fig-redhat-logviewer-add">
- <title>Log File Viewer — adding a log file</title>
+ <title>System Log - adding a log file</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/system-log-viewer-add.png" format="PNG" scalefit="0" />
+ <imagedata fileref="images/redhat-logviewer-add.png" format="PNG" />
</imageobject>
<textobject>
- <para>Log File Viewer — adding a log file</para>
+ <para>System Log - Adding a Log File</para>
</textobject>
</mediaobject>
</figure>
@@ -1107,86 +2436,119 @@ compress
<note>
<title>Reading zipped log files</title>
<para>
- The <application>Log File Viewer</application> also allows you to open log files zipped in the <literal>.gz</literal> format.
+ The <application>System Log</application> also allows you to open log files zipped in the <literal>.gz</literal> format.
</para>
</note>
</section>
- <section id="s1-logfiles-examining">
+ <section id="s2-logfiles-examining">
<title>Monitoring Log Files</title>
- <indexterm significance="normal">
+ <indexterm>
<primary>log files</primary>
<secondary>monitoring</secondary>
</indexterm>
- <indexterm significance="normal">
- <primary>
- <application>Log File Viewer</application>
- </primary>
+ <indexterm>
+ <primary><application>System Log</application></primary>
<secondary>monitoring</secondary>
</indexterm>
<para>
- <application>Log File Viewer</application> monitors all opened logs by default. If a new line is added to a monitored log file, the log name appears in bold in the log list. If the log file is selected or displayed, the new lines appear in bold at the bottom of the log file. <xref linkend="fig-redhat-logviewer-monitoring"/> illustrates a new alert in the <guilabel>yum.log</guilabel> log file and in the <guilabel>messages</guilabel> log file. Clicking on the <guimenuitem>messages</guimenuitem> log file displays the logs in the file with the new lines in bold.</para>
+ <application>System Log</application> monitors all opened logs by default. If a new line is added to a monitored log file, the log name appears in bold in the log list. If the log file is selected or displayed, the new lines appear in bold at the bottom of the log file. <xref linkend="fig-redhat-logviewer-monitoring"/> illustrates a new alert in the <guilabel>cron</guilabel> log file and in the <guilabel>messages</guilabel> log file. Clicking on the <guimenuitem>messages</guimenuitem> log file displays the logs in the file with the new lines in bold.</para>
<figure id="fig-redhat-logviewer-monitoring">
- <title>Log File Viewer — new log alert</title>
+ <title>System Log - new log alert</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/system-log-viewer-alerts.png" format="PNG" scalefit="0" />
+ <imagedata fileref="images/redhat-logviewer-monitoring.png" format="PNG" />
</imageobject>
<textobject>
- <para>Log File Viewer — new log alert</para>
+ <para>System Log - New Log Alert</para>
</textobject>
</mediaobject>
</figure>
+ </section>
</section>
<section id="s1-log-files-additional-resources">
<title>Additional Resources</title>
- <para>To learn more about <application>rsyslog</application>, <application>logrotate</application>, and log files in general, refer to the following resources.</para>
- <section id="s2-log-files-installed-docs">
- <title>Installed Documentation</title>
- <indexterm significance="normal">
- <primary>log files</primary>
- <secondary>additional resources</secondary>
- <tertiary>installed documentation</tertiary>
- </indexterm>
- <itemizedlist>
- <listitem>
- <para>
- <command>rsyslogd</command> manual page — Type <command>man rsyslogd</command> to learn more about <command>rsyslogd</command> and its many options.</para>
- </listitem>
- <listitem>
- <para>
- <command>rsyslog.conf</command> manual page — Type <command>man rsyslog.conf</command> to learn more about the <command>/etc/rsyslog.conf</command> configuration file and its many options.</para>
- </listitem>
- <listitem>
- <para>
- <filename>/usr/share/doc/rsyslog/
- </filename> — After installing the <package>rsyslog</package> package, this directory contains extensive documentation in the <systemitem class="protocol">html</systemitem> format.</para>
- </listitem>
- <listitem>
- <para>
- <command>logrotate</command> manual page — Type <command>man logrotate</command> to learn more about <command>logrotate</command> and its many options.</para>
- </listitem>
- </itemizedlist>
- </section>
- <section id="s2-log-files-useful-websites">
- <title>Useful Websites</title>
- <indexterm significance="normal">
- <primary>log files</primary>
- <secondary>additional resources</secondary>
- <tertiary>useful websites</tertiary>
- </indexterm>
- <itemizedlist>
- <listitem>
- <para>
- <ulink url="http://www.rsyslog.com/">http://www.rsyslog.com/</ulink> — Offers a thorough technical breakdown of <package>rsyslog</package> features, documentation, configuration examples, and video tutorials.</para>
- </listitem>
- <listitem>
+ <para>
+ For more information on how to configure the <systemitem class="service">rsyslog</systemitem> daemon and how to locate, view, and monitor log files, see the resources listed below.
+ </para>
+ <bridgehead id="brid-Log_Files-Resources-Installed">Installed Documentation</bridgehead>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <systemitem>rsyslogd</systemitem>(8) — The manual page for the <systemitem class="service">rsyslogd</systemitem> daemon documents its usage.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <systemitem>rsyslog.conf</systemitem>(5) — The manual page named <systemitem>rsyslog.conf</systemitem> documents available configuration options.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <systemitem>logrotate</systemitem>(8) — The manual page for the <application>logrotate</application> utility explains in greater detail how to configure and use it.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <systemitem>journalctl</systemitem>(1) — The manual page for the <command>journalctl</command> daemon documents its usage.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <systemitem>journald.conf</systemitem>(5) — This manual page documents available configuration options.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <systemitem>systemd.journal-fields</systemitem>(7) — This manual page lists special <application>Journal</application> fields.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <bridgehead id="brid-Log_Files-Resources-Online">Online Documentation</bridgehead>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="http://www.rsyslog.com/">rsyslog Home Page</ulink> — The <application>rsyslog</application> home page offers a thorough technical breakdown of its features, documentation, configuration examples, and video tutorials.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://www.rsyslog.com/doc/rainerscript.html"><emphasis>RainerScript</emphasis> documentation on the rsyslog Home Page</ulink> — Commented summary of data types, expressions, and functions available in <emphasis>RainerScript</emphasis>.
+ </para>
+ </listitem>
+ <listitem>
<para>
- <ulink url="http://wiki.rsyslog.com/index.php/Main_Page">http://wiki.rsyslog.com/index.php/Main_Page</ulink> — Contains useful <filename>/etc/rsyslog.conf</filename> configuration examples.</para>
- </listitem>
- </itemizedlist>
+ <ulink url="http://www.rsyslog.com/doc/queues.html">Description of <emphasis>queues</emphasis> on the rsyslog Home Page</ulink> — General information on various types of message queues and their usage.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://wiki.rsyslog.com/index.php/Main_Page">rsyslog Wiki</ulink> — <citetitle pubwork="webpage">The rsyslog Wiki</citetitle> contains useful configuration examples.
+ </para>
+ </listitem>
+ <!-- <listitem>
+ <para>
+ <ulink url="https://fedorahosted.org/lumberjack/">Lumberjack Home Page</ulink> — <citetitle pubwork="webpage">Lumberjack Home Page</citetitle> provides an overview of the Lumberjack project.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://deirf.github.io/libumberlog/umberlog.html">libumberlog Home Page</ulink> — <citetitle pubwork="webpage">libumberlog Home Page</citetitle> provides an overview of the <systemitem class="library">libumberlog</systemitem> library.
+ </para>
+ </listitem>-->
+
+ </itemizedlist>
+ <!--<bridgehead id="brid-Log_Files-Resources-See">See Also</bridgehead>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <xref linkend="chap-Gaining_Privileges" /> documents how to gain administrative privileges by using the <command>su</command> and <command>sudo</command> commands.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref linkend="chap-Managing_Services_with_systemd" /> provides more information on systemd and documents how to use the <command>systemctl</command> command to manage system services.
+ </para>
+ </listitem>
+ </itemizedlist>-->
</section>
- </section>
</chapter>
-
-
-
diff --git a/en-US/images/redhat-filter-enable.png b/en-US/images/redhat-filter-enable.png
new file mode 100644
index 0000000..e0e4051
Binary files /dev/null and b/en-US/images/redhat-filter-enable.png differ
diff --git a/en-US/images/redhat-filter-sample.png b/en-US/images/redhat-filter-sample.png
new file mode 100644
index 0000000..66ce188
Binary files /dev/null and b/en-US/images/redhat-filter-sample.png differ
diff --git a/en-US/images/redhat-filters.png b/en-US/images/redhat-filters.png
new file mode 100644
index 0000000..40dd5f8
Binary files /dev/null and b/en-US/images/redhat-filters.png differ
diff --git a/en-US/images/redhat-logviewer-add.png b/en-US/images/redhat-logviewer-add.png
new file mode 100644
index 0000000..f2cf04d
Binary files /dev/null and b/en-US/images/redhat-logviewer-add.png differ
diff --git a/en-US/images/redhat-logviewer-monitoring.png b/en-US/images/redhat-logviewer-monitoring.png
new file mode 100644
index 0000000..5f66789
Binary files /dev/null and b/en-US/images/redhat-logviewer-monitoring.png differ
diff --git a/en-US/images/redhat-logviewer.png b/en-US/images/redhat-logviewer.png
new file mode 100644
index 0000000..365d52c
Binary files /dev/null and b/en-US/images/redhat-logviewer.png differ
diff --git a/en-US/images/rsyslog_message_flow.png b/en-US/images/rsyslog_message_flow.png
new file mode 100644
index 0000000..7503f4a
Binary files /dev/null and b/en-US/images/rsyslog_message_flow.png differ
More information about the docs-commits
mailing list