Skip to content

New task: Configure a central syslog server #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

New task: Configure a central syslog server #28

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d6cb81b
New task: Configure a central syslog server
cwickert Sep 15, 2021
dabade5
Apply suggestions from code review
cwickert Oct 8, 2021
4cd654d
Final fixes after review
cwickert Oct 8, 2021
6467d90
Fix screens and consistently use term 'syslog server'
cwickert Nov 10, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions DC-task-configure-syslog-server
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# This file originates from the project https://github.com/openSUSE/doc-kit
# This file can be edited downstream.

MAIN="task-configure-syslog-server.xml"
ROOTID="task-configure-central-syslog-server"

PROFCONDITION="suse-product"
#PROFCONDITION="suse-product;beta"
#PROFCONDITION="community-project"

STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2021-ns"
FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse-ns"
364 changes: 364 additions & 0 deletions xml/task-configure-syslog-server.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,364 @@
<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet href="urn:x-suse:xslt:profiling:docbook51-profile.xsl"
type="text/xml"
title="Profiling step"?>
<!DOCTYPE article
[
<!ENTITY % entities SYSTEM "generic-entities.ent">
%entities;
]>

<!--metadata
* product(s): SLES, SLED, SLE-HA, SLES-SAP, SLE-HPC, SLE-RT
* product version(s): 15 SP3, 15 SP2, 15 GA
* topic category/ies: system administration, networking
* target group(s): system operators
* initially published: ?
* last modified: ?-->

<article xml:id="task-configure-central-syslog-server" xml:lang="en"
role="task"
xmlns="http://docbook.org/ns/docbook" version="5.1"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink">

<info>
<title>Forwarding log messages to a central syslog server</title>
<dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
<dm:bugtracker>
<dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url>
<dm:component>Documentation</dm:component>
<dm:product>Product Name</dm:product>
<dm:assignee>cwickert@suse.com</dm:assignee>
</dm:bugtracker>
<dm:translation>no</dm:translation>
</dm:docmanager>
</info>

<section xml:id="environment-configure-central-syslog-server">
<title>Environment</title>
<para>This document applies to the following products and product versions:</para>
<itemizedlist>
<listitem>
<para>&sles;&nbsp;15&nbsp;SP3, 15&nbsp;SP2, 15&nbsp;SP1, 15&nbsp;GA, 12&nbsp;SP5, 12&nbsp;SP4, 12&nbsp;SP3</para>
</listitem>
<listitem>
<para>&sles4sap;&nbsp;15&nbsp;SP3, 15&nbsp;SP2, 15&nbsp;SP1, 15&nbsp;GA, 12&nbsp;SP5, 12&nbsp;SP4, 12&nbsp;SP3</para>
</listitem>
<listitem>
<para>&sleha;&nbsp;15&nbsp;SP3, 15&nbsp;SP2, 15&nbsp;SP1, 15&nbsp;GA, 12&nbsp;SP5, 12&nbsp;SP4, 12&nbsp;SP3</para>
</listitem>
<listitem>
<para>&slehpc;&nbsp;15&nbsp;SP3, 15&nbsp;SP2, 15&nbsp;SP1, 15&nbsp;GA</para>
</listitem>
<listitem>
<para>&sled;&nbsp;15&nbsp;SP3, 15&nbsp;SP2, 15&nbsp;SP1, 15&nbsp;GA, 12&nbsp;SP5, 12&nbsp;SP4, 12&nbsp;SP3</para>
</listitem>
<listitem>
<para>&slert;&nbsp;15&nbsp;SP3, 15&nbsp;SP2, 15&nbsp;SP1, 15&nbsp;GA, 12&nbsp;SP5, 12&nbsp;SP4, 12&nbsp;SP3</para>
</listitem>
</itemizedlist>
</section>

<section xml:id="introduction-configure-central-syslog-server">
<title>Introduction</title>
<para>
System log data can be forwarded from individual systems to a central syslog
server on the network. This allows administrators to get an overview of
events on all hosts, and prevents attackers that succeed in taking over a
system from manipulating system logs to cover their tracks.
</para>
</section>

<section xml:id="requirements-configure-central-syslog-server">
<title>Requirements</title>
<itemizedlist>
<listitem>
<para>
You have installed your product and your system is up and running.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What product? What system? It's the first time you mention them.

</para>
</listitem>
<listitem>
<para>
The system is connected to the network.
</para>
</listitem>
<!-- FIXME cwickert 2021-10-08: uncomment once we have NTP instructions.
<listitem>
<para>
You have set up <literal>NTP</literal> on all machines. Refer to <xref
linkend="FIXME"/> for configuration instructions.
</para>
</listitem>
-->
<listitem>
<para>
The <package>rsyslog</package> package is installed on all machines.
If not, run <command>zypper in yast2-mail</command> to install it.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If not, run <command>zypper in yast2-mail</command> to install it.
Otherwise, run <command>zypper in yast2-mail</command> to install it.

</para>
<!-- <screen>&prompt.root;<command>zypper in rsyslog</command></screen> -->
Comment on lines +97 to +100
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am confused by these installation instructions. My own system with Leap has yast2-mail installed, but the rsyslog package is missing. The paragraph also does a bad job at explaining cause & effect here -- is rsyslog a package required by YaST somehow?

> zypper se yast2-mail

S  | Name       | Summary                    | Type
 --+------------+----------------------------+-----------
i+ | yast2-mail | YaST2 - Mail Configuration | package
   | yast2-mail | YaST2 - Mail Configuration | srcpackage


> zypper se rsyslog

S | Name                         | Summary                          | Type
 -+------------------------------+----------------------------------+-----------
  | pcp-pmda-rsyslog             | Performance Co-Pilot (PCP) met-> | package
  | rsyslog                      | The enhanced syslogd for Linux-> | package
  | rsyslog                      | The enhanced syslogd for Linux-> | srcpackage
[...]

</listitem>
</itemizedlist>
</section>

<section xml:id="configure-configure-central-syslog-server">
<title>Setting up the central syslog server</title>
<para>
Setting up a central syslog server consists of two parts. First you configure
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Setting up a central syslog server consists of two parts. First you configure
Setting up a central syslog server consists of two parts. First, configure

the central log server, then the clients for remote logging.
Comment on lines +108 to +109
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An (imo) more accurate way to describe the task that also avoids the awkwardness you mentioned about repeating the word "syslog server":

Suggested change
Setting up a central syslog server consists of two parts. First you configure
the central log server, then the clients for remote logging.
Setting up central logging with <systemitem class="daemon">rsyslog</systemitem>
consists of two parts: Configuring a central syslog server and configuring
clients to log remotely.

</para>
<section xml:id="sec-configure-configure-central-syslog-server">
<title>Setting up the central syslog server</title>
<!--
<para>
This section describes a basic syslog forwarding setup on &sle;.
</para>
-->
<procedure xml:id="pro-configure-central-syslog-server">
<title>Configure the central <systemitem>rsyslog</systemitem> server</title>
<para>
To set up a central syslog server, perform the following steps:
</para>
Comment on lines +119 to +122
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why create a procedure with title and a preamble in a section that contains nothing but this one procedure anyway? Suggestion: delete the procedure's title tag, move the preamble para above the procedure, and integrate or delete the commented para that already exists in between section title and begin of the procedure.
(And maybe remove the xml:id from the procedure.)

<step>
<para>
Edit the configuration file
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This step does not tell you anything about editing things, soo... maybe reword like this:

Suggested change
Edit the configuration file
In an editor, open the configuration file

<filename>/etc/rsyslog.d/remote.conf</filename>.
</para>
</step>
<step>
<para>
Uncomment the following lines in the <literal>UDP Syslog Server</literal>
or <literal>TCP Syslog Server</literal> section of the configuration file.
Assign an IP address and port for <systemitem
class="daemon">rsyslogd</systemitem>.
</para>
<para>
TCP example:
</para>
<screen>$ModLoad imtcp.so
$UDPServerAddress <replaceable>IP</replaceable><co xml:id="co-tuning-syslog-server-ip"/>
$InputTCPServerRun <replaceable>PORT</replaceable><co xml:id="co-tuning-syslog-server-port"/></screen>
<para>
UDP example:
</para>
<screen>$ModLoad imudp.so
$UDPServerAddress <replaceable>IP</replaceable><xref linkend="co-tuning-syslog-server-ip" xrefstyle="select:label nopage"/>
$UDPServerRun <replaceable>PORT</replaceable><xref linkend="co-tuning-syslog-server-port" xrefstyle="select:label nopage"/></screen>
<calloutlist>
<callout arearefs="co-tuning-syslog-server-ip">
<para>
IP address of the interface for <systemitem
class="daemon">rsyslogd</systemitem> to listen on. If no address is
given, the daemon listens on all interfaces.
</para>
</callout>
<callout arearefs="co-tuning-syslog-server-port">
<para>
Port for <systemitem class="daemon">rsyslogd</systemitem> to listen on.
Select a privileged port below 1024. The default is 514.
Copy link

@ghost ghost Nov 10, 2021 •
edited by ghost
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am a moderate fan of putting port numbers into literals. I won't be offended if you disagree though.

Suggested change
Select a privileged port below 1024. The default is 514.
Select a privileged port below <literal>1024</literal>. The default port
is <literal>514</literal>.

</para>
</callout>
</calloutlist>
<important>
<title>TCP versus UDP protocol</title>
<para>
Traditionally syslog uses the UDP protocol to transmit log messages over
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Traditionally? Not the word you'd use in a tech doc. Perhaps by default?

the network. This involves less overhead, but lacks reliability. Log
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Improve wording:

Suggested change
the network. This involves less overhead, but lacks reliability. Log
the network. This creates less overhead, but is less reliable. Log

messages can get lost under high load.
Copy link

@ghost ghost Nov 10, 2021 •
edited by ghost
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the old wording below is actually more correct (as is suggested by the accompanying comment), the new wording should continue to include "constant" imo, as that seems important.

Suggested change
messages can get lost under high load.
messages can get lost under constant high load.

<!-- cwickert 2021-03-02 Original text before shortening -->
<!-- The TCP protocol is more
reliable. Messages will only get lost under
<emphasis>constant</emphasis> high load, which should not occur under
normal circumstances.
</para>
<para>
Since the advantages of centralized logging could suffer from
unreliability, using TCP recommended. -->
Comment on lines +169 to +177
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not a huge fan of keeping every possible prior wording in the file itself. Most likely, three years down the road, someone will just cut it anyway.

Suggested change
<!-- cwickert 2021-03-02 Original text before shortening -->
<!-- The TCP protocol is more
reliable. Messages will only get lost under
<emphasis>constant</emphasis> high load, which should not occur under
normal circumstances.
</para>
<para>
Since the advantages of centralized logging could suffer from
unreliability, using TCP recommended. -->

</para>
<para>
The TCP protocol is more reliable and should be preferred over UDP.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The TCP protocol is more reliable and should be preferred over UDP.
The TCP protocol is more reliable and it should be used instead of UDP.

</para>
</important>
<note>
<title><literal>UDPServerAddress</literal> with TCP</title>
<para>
The <literal>$UDPServerAddress</literal> configuration parameter in the
TCP example is no error. Despite its name it is used for both TCP and
Copy link

@ghost ghost Nov 10, 2021 •
edited by ghost
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this works better. The comma before "run" is conventional in our docs, and I think also grammatically necessary (but am happy to be disproved on that front).

Suggested change
TCP example is no error. Despite its name it is used for both TCP and
TCP example is not an error. Despite its name, it is used for both TCP and

UDP.
</para>
</note>
</step>
<step>
<para>
Save the file.
</para>
</step>
<step>
<para>
Restart the <systemitem class="daemon">rsyslog</systemitem> service:
</para>
<screen>&prompt.sudo;<command>systemctl restart rsyslog.service</command></screen>
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As far as I know, it was never started, it was only installed. Does running systemctl restart for a service that is not yet running work as expected?

</step>
<step>
<para>Open the respective port in the firewall. For <systemitem
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Respective to what?

class="daemon">firewalld</systemitem> with TCP on port 514 run:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comma me:

Suggested change
class="daemon">firewalld</systemitem> with TCP on port 514 run:
class="daemon">firewalld</systemitem> with TCP on port 514, run:

</para>
<screen>&prompt.sudo;<command>firewall-cmd --add-port <replaceable>514/tcp</replaceable> --permanent</command>
&prompt.sudo;<command>firewall-cmd --reload</command></screen>
</step>
</procedure>
<para>
You have now configured the central syslog server. Next, configure clients
for remote logging.
</para>
</section>
<section >
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section has no xml:id.

<title>Set up the client machines</title>
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gerund:

Suggested change
<title>Set up the client machines</title>
<title>Setting up the client machines</title>

<procedure xml:id="pro-configure-syslog-client">
<title>Configure a <guimenu>rsyslog</guimenu> instance for remote logging</title>
<para>
To configure a system for remote logging on a central syslog server,
perform the following steps:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
perform the following steps:
follow the procedure below.

</para>
Comment on lines +219 to +223
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment as before -- this is another section that only has a single procedure in it, it would make more sense to delete the procedure title and move the procedure preamble up.

<step>
<para>
Edit the configuration file
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as above.

Suggested change
Edit the configuration file
In an editor, open the configuration file

<filename>/etc/rsyslog.d/remote.conf</filename>.
</para>
</step>
<step>
<para>
Uncomment the appropriate line (TCP or UDP) and replace
<literal>remote-host</literal> with the address of the central syslog
server set up in <xref
linkend="sec-configure-configure-central-syslog-server"/>.
</para>
<para>
TCP example:
</para>
<screen># Remote Logging using TCP for reliable delivery
# remote host is: name/ip:port, e.g. 192.168.0.1:514, port optional
*.* <replaceable>@@remote-host</replaceable></screen>
<para>
UDP example:
</para>
<screen># Remote Logging using UDP
# remote host is: name/ip:port, e.g. 192.168.0.1:514, port optional
*.* <replaceable>@remote-host</replaceable></screen>
</step>
<step>
<para>
Save the file.
</para>
</step>
<step>
<para>
Restart the <systemitem class="daemon">rsyslog</systemitem> service:
</para>
<screen>&prompt.sudo;<command>systemctl restart rsyslog.service</command></screen>
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The issue of restarting a service that may not be running applies here as well.

</step>
<step>
<para>
Verify the proper function of the syslog forwarding:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not much shorter but imo easier to understand:

Suggested change
Verify the proper function of the syslog forwarding:
Make sure that syslog forwarding works:

</para>
<screen>&prompt.user;<command>logger "hello world"</command></screen>
<para>
The log message <literal>hello world</literal> should now appear on the
central syslog server.
</para>
</step>
</procedure>
<para>
You have now configured a system for remote logging to your central syslog
server. Repeat this procedure for all systems that should log remotely.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"for" -> "on"? To me, it seems like it would make sense (because you're changing a config file on that machine).

Suggested change
server. Repeat this procedure for all systems that should log remotely.
server. Repeat this procedure on all systems that should log remotely.

</para>
</section>
</section>

<section xml:id="summary-configure-central-syslog-server">
<title>Summary</title>
<para>
You have configured one or more hosts for remote logging to your central
syslog server. This allows you to get a quick overview of events on your
network.
Comment on lines +283 to +284
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds better to me, but not a native speaker I am:

Suggested change
syslog server. This allows you to get a quick overview of events on your
network.
syslog server. This allows you to get a quick overview of events
within your network.

</para>
</section>

<section xml:id="troubleshooting-configure-central-syslog-server">
<title>Troubleshooting</title>
<para>
In case the test log message does not appear on the syslog server, perform
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wordy:

Suggested change
In case the test log message does not appear on the syslog server, perform
If the test log message does not appear on the syslog server, perform

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You don't perform steps. You perform tasks and follow steps.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My tendency is toward "either version works" here, too.

the following steps to analyze the problem.
</para>
<variablelist>
<varlistentry>
<term>Is <systemitem class="daemon">rsyslog</systemitem> running?</term>
<listitem>
<para>
If you made an error in the configuration of <systemitem
class="daemon">rsyslog</systemitem>, the daemon might refuse to start.
Check it is running with
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Check it is running with
Check whether it is running with

<command>systemctl status rsyslog.service</command>. If the
service is down, the output includes additional information about the
reason.
</para>
<para>
Run this check on both the syslog server and the remote logging clients.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Is the firewall open?</term>
<listitem>
<para>
Check if the firewall on the log server is open with
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Check if the firewall on the log server is open with
Check if the firewall on the syslog server is open with

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would support Liam's suggestion (unsurprising, I guess ...)

<command>firewall-cmd --list-all</command>.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>

<section xml:id="next-configure-central-syslog-server">
<title>Next steps</title>
<para>
This basic setup does not include encryption and is only suitable for
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This basic setup does not include encryption and is only suitable for
This basic setup does not include encryption and it is only suitable for

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this case, either version works.

trusted internal networks. TLS encryption is strongly recommended, but
requires a certificate infrastructure.
Comment on lines +327 to +328
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
trusted internal networks. TLS encryption is strongly recommended, but
requires a certificate infrastructure.
trusted internal networks. TLS encryption is strongly recommended. However this
requires a certificate infrastructure.

</para>
<para>
In this configuration, all messages from remote hosts will be treated the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In this configuration, all messages from remote hosts will be treated the
In this configuration, all messages from remote hosts are treated the

same on the central syslog server. Consider filtering messages into separate
files by remote host or classify them by message category.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

parallel phrasing (filter_ing_ + classify_ing_)

Suggested change
files by remote host or classify them by message category.
files by remote host or classifying them by message category.

</para>
<para>
For more information about encryption, filtering, and other advanced topics,
consult the <phrase role="productname">RSyslog</phrase> documentation at
<link xlink:href="https://www.rsyslog.com/doc/master/index.html#manual"/>.
</para>
</section>

<!--
<section xml:id="related-configure-central-syslog-server">
<title>Related topics</title>
<itemizedlist>
<listitem>
<para>
An
</para>
</listitem>
<listitem>
<para>
Unordered
</para>
</listitem>
<listitem>
<para>
List
</para>
</listitem>
</itemizedlist>
</section>
-->
</article>