commit 36d8225e50bd017501ca827444b4868be16911a2
Author: Stephen Wadeley <swadeley(a)redhat.com>
Date: Thu Jun 11 00:08:54 2015 +0200
Improvements from upstream version
en-US/Viewing_and_Managing_Log_Files.xml | 149 +++++++++++++++++++++---------
1 files changed, 106 insertions(+), 43 deletions(-)
---
diff --git a/en-US/Viewing_and_Managing_Log_Files.xml
b/en-US/Viewing_and_Managing_Log_Files.xml
index 9df50fe..6287d8b 100644
--- a/en-US/Viewing_and_Managing_Log_Files.xml
+++ b/en-US/Viewing_and_Managing_Log_Files.xml
@@ -11,9 +11,12 @@
<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
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>
+ <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>
<primary>log files</primary>
<secondary><command>rsyslogd daemon</command></secondary>
@@ -22,7 +25,7 @@
<primary><application>rsyslog</application></primary>
</indexterm>
<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.
+ 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>sysklogd</application>, and provides extended filtering,
encryption protected relaying of messages, various configuration options, input and output
modules, 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>.
</para>
<para>
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"/>.
@@ -36,23 +39,32 @@
<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>
+ <para>
+ 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. 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>
+ </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>
+ <indexterm>
+ <primary><application>rsyslog</application></primary>
+ <secondary>configuration</secondary>
+ </indexterm>
<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>
<section id="s2-Filters">
<title>Filters</title>
+ <indexterm>
+ <primary><application>rsyslog</application></primary>
+ <secondary>filters</secondary>
+ </indexterm>
<para>
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>
@@ -238,7 +250,7 @@ cron.!info,!debug
<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 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"/>
+ 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.
</para>
<para>
The basic syntax of expression-based filter looks as follows:
@@ -257,17 +269,17 @@ if <replaceable>EXPRESSION</replaceable> then
<replaceable>ACTION</replaceable>
</listitem>
<listitem>
<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.
+ 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.
+ 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>
<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>.
+ 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>
<example id="ex-expression-based_filters">
<title>Expression-based Filters</title>
@@ -287,9 +299,16 @@ if $programname == 'prog1' then {
</listitem>
</varlistentry>
</variablelist>
+ <para>
+ See <xref linkend="brid-Log_Files-Resources-Online"/> for more
examples of various expression-based filters. RainerScript is the basis for
<application>rsyslog</application>'s new configuration format, see
<xref linkend="sec-using_the_new_configuration_format"/>
+ </para>
</section>
<section id="s2-Actions">
<title>Actions</title>
+ <indexterm>
+ <primary><application>rsyslog</application></primary>
+ <secondary>actions</secondary>
+ </indexterm>
<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>
@@ -554,7 +573,7 @@ $ModLoad ompgsql # Output module for PostgreSQL support
</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 (&):
+ 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>
<replaceable>FILTER</replaceable>
<replaceable>ACTION</replaceable>
@@ -587,6 +606,10 @@ kern.=crit user1
</section>
<section id="s2-Templates">
<title>Templates</title>
+ <indexterm>
+ <primary><application>rsyslog</application></primary>
+ <secondary>templates</secondary>
+ </indexterm>
<para>
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>
@@ -783,6 +806,10 @@ kern.=crit user1
</section>
<section id="s2-global_directives">
<title>Global Directives</title>
+ <indexterm>
+ <primary><application>rsyslog</application></primary>
+ <secondary>global directives</secondary>
+ </indexterm>
<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>
@@ -793,11 +820,15 @@ $MainMsgQueueSize 50000
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.
+ You can 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="sec-using_the_new_configuration_format"/>). However, classic global
directives remain supported as a legacy format.
</para>
</section>
<section id="s2-log_rotation">
<title>Log Rotation</title>
+ <indexterm>
+ <primary><application>rsyslog</application></primary>
+ <secondary>log rotation</secondary>
+ </indexterm>
<para>
The following is a sample <filename>/etc/logrotate.conf</filename>
configuration file:
</para>
@@ -881,7 +912,7 @@ compress
</listitem>
<listitem>
<para>
- <parameter>compressoptions</parameter> — Lets you specify
any options that may be passed to the used compression program.
+ <parameter>compressoptions</parameter> — Specifies any
options to be passed to the compression program used.
</para>
</listitem>
<listitem>
@@ -926,16 +957,22 @@ compress
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">
+ </section>
+ <section id="sec-using_the_new_configuration_format">
<title>Using the New Configuration Format</title>
+ <indexterm>
+ <primary><application>rsyslog</application></primary>
+ <secondary>new configuration format</secondary>
+ </indexterm>
+
<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.
+ In <application>rsyslog</application> version 6, a new
configuration syntax was 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.
+ RainerScript is a scripting language designed for processing network events
and configuring event processors such as <application>rsyslog</application>.
RainerScript was first used to define expression-based filters, see <xref
linkend="ex-expression-based_filters"/>. The version of RainerScript in
rsyslog version 7 implemented 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 syntax. The new syntax differs mainly in that it is much more structured; parameters
are passed as arguments to statements, such as input, action, template, and module load.
The scope of options is limited by blocks. This enhances readability and reduces the
number of bugs caused by misconfiguration. There is also a significant performance gain.
Some functionality is exposed in both syntaxes, some only in the new one.
</para>
<para>
- In the following examples you can compare the configuration written with
legacy-style parameters:
+ Compare the configuration written with legacy-style parameters:
</para>
<screen>
$InputFileName /tmp/inputfile
@@ -944,7 +981,7 @@ $InputFileStateFile inputfile-state
$InputRunFileMonitor
</screen>
<para>
- and the same configuration with use of the new format statement:
+ and the same configuration with the use of the new format statement:
</para>
<screen>
input(type="imfile" file="/tmp/inputfile" tag="tag1:"
statefile="inputfile-state")
@@ -952,31 +989,37 @@ input(type="imfile" file="/tmp/inputfile"
tag="tag1:" statefile="inputfile-state
<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">
+
+ <section id="sec-Rulesets">
<title>Rulesets</title>
+ <indexterm>
+ <primary><application>rsyslog</application></primary>
+ <secondary>rulesets</secondary>
+ </indexterm>
+
<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:
+ 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. The legacy ruleset definition in
<filename>/etc/rsyslog.conf</filename> can look as follows:</para>
+ <screen>
+$RuleSet <replaceable>rulesetname</replaceable>
+<replaceable>rule</replaceable>
+<replaceable>rule2</replaceable></screen>
+<para>
+The rule ends when another rule is defined, or the default ruleset is called as
follows:</para>
+<screen>$RuleSet RSYSLOG_DefaultRuleset</screen>
+ <para>
+ With the new configuration format in rsyslog 7, the
<function>input()</function> and <function>ruleset()</function>
statements are reserved for this operation. The new format ruleset definition in
<filename>/etc/rsyslog.conf</filename> can look as follows:
</para>
<screen>
ruleset(name="<replaceable>rulesetname</replaceable>") {
- <replaceable>rule</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>
@@ -1016,7 +1059,7 @@ input(type="imtcp" port="10515"
ruleset="remote-10515");
<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.
+ 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.
@@ -1025,6 +1068,11 @@ input(type="imtcp" port="10515"
ruleset="remote-10515");
</section>
<section id="s1-working_with_queues_in_rsyslog">
<title>Working with Queues in Rsyslog</title>
+ <indexterm>
+ <primary><application>rsyslog</application></primary>
+ <secondary>queues</secondary>
+ </indexterm>
+
<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>
@@ -1066,6 +1114,11 @@ input(type="imtcp" port="10515"
ruleset="remote-10515");
<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>
+ <warning>
+ <para>
+ If an output plug-in is unable to deliver a message, it is stored in the
preceding message queue. If the queue fills, the inputs block until it is no longer full.
This will prevent new messages from being logged via the blocked queue. In the absence of
separate action queues this can have severe consequences, such as preventing
<systemitem class="protocol">SSH</systemitem> logging, which in turn
can prevent <systemitem class="protocol">SSH</systemitem> access.
Therefore it is advised to use dedicated action queues for outputs which are forwarded
over a network or to a database.
+ </para>
+ </warning>
<section id="s2-defining_queues">
<title>Defining Queues</title>
<para>
@@ -1081,7 +1134,7 @@ input(type="imtcp" port="10515"
ruleset="remote-10515");
</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:
+ 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>
@@ -1090,7 +1143,7 @@ input(type="imtcp" port="10515"
ruleset="remote-10515");
<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:
+ To configure 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>
@@ -1177,7 +1230,7 @@ input(type="imtcp" port="10515"
ruleset="remote-10515");
<step>
<para>
Create a working directory to store the queue files. For example:
- </para>
+ </para>
<synopsis>~]# <command>mkdir</command>
<filename
class="directory">/rsyslog/work/</filename></synopsis>
</step>
<step>
@@ -1265,7 +1318,7 @@ $ActionQueueSaveOnShutdown on
<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.
+ 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 a queue on system shutdown.
</para>
<bridgehead id="br-limiting_queue_size">Limiting Queue
Size</bridgehead>
<para>
@@ -1359,6 +1412,11 @@ $ActionQueueSaveOnShutdown on
</section>
<section id="s1-using_rsyslog_modules">
<title>Using Rsyslog Modules</title>
+ <indexterm>
+ <primary><application>rsyslog</application></primary>
+ <secondary>modules</secondary>
+ </indexterm>
+
<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>
@@ -1377,12 +1435,12 @@ $ModLoad imfile
<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.
+ 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> and
<command>imjournal</command>.
</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.
+ 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>, and so on.
</para>
</listitem>
<listitem>
@@ -1417,7 +1475,7 @@ $ModLoad imfile
<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>:
+ 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
@@ -1508,7 +1566,7 @@ $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.
+ Here, replace <replaceable>driver</replaceable> with a driver
name (mysql), <replaceable>host</replaceable> with a host name
<replaceable>user</replaceable> with user name,
<replaceable>pwd</replaceable> with a password 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>
@@ -1897,7 +1955,7 @@ $AddUnixListenSocket /run/systemd/journal/syslog
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> :
+ 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>")
@@ -1928,7 +1986,7 @@ $ModLoad mmjsonparse
<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" />):
+ 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="sec-using_the_new_configuration_format" />):
</para>
<screen>
$ModLoad ommongodb
@@ -1953,12 +2011,17 @@ $ModLoad ommongodb
</listitem>
</itemizedlist>
<para>
- 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.
+ You can shape the form of the final database output with use of templates. By
default, <application>rsyslog</application> uses a template based on standard
<application>lumberjack</application> field names.
</para>
</section>
</section>
<section id="s1-debugging_rsyslog">
<title>Debugging Rsyslog</title>
+ <indexterm>
+ <primary><application>rsyslog</application></primary>
+ <secondary>debugging</secondary>
+ </indexterm>
+
<para>
To run <systemitem
class="daemon">rsyslogd</systemitem> in debugging mode, use the
following command:
</para>
@@ -1974,7 +2037,7 @@ export RSYSLOG_DEBUG="Debug"
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>
<para>
- To check if syntax used in the
<filename>etc/rsyslog.conf</filename> file is valid use:
+ 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>