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
cwickert 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 3 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"
363 changes: 363 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,363 @@
<?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 log 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.
Comment thread
This conversation was marked as resolved.
</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
Copy Markdown

@dmpop dmpop Nov 11, 2021

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
Copy Markdown

@dmpop dmpop Nov 11, 2021

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
Copy Markdown

@ghost ghost Nov 10, 2021

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
Copy Markdown

@dmpop dmpop Nov 11, 2021

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
Copy Markdown

@ghost ghost Nov 10, 2021

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
Copy Markdown

@ghost ghost Nov 10, 2021

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
Copy Markdown

@ghost ghost Nov 10, 2021

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
Copy Markdown

@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
Copy Markdown

@dmpop dmpop Nov 11, 2021

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
Copy Markdown

@ghost ghost Nov 10, 2021

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
Copy Markdown

@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. -->
</para>
<para>
The TCP protocol is more reliable and should be preferred over UDP.
Copy link
Copy Markdown

@dmpop dmpop Nov 11, 2021

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
Copy Markdown

@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
Copy Markdown

@ghost ghost Nov 10, 2021

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
Copy Markdown

@dmpop dmpop Nov 11, 2021

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
Copy Markdown

@ghost ghost Nov 10, 2021

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 log server. Next, configure the clients
for remote logging.
</para>
</section>
<section >
Copy link
Copy Markdown

@ghost ghost Nov 10, 2021

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
Copy Markdown

@ghost ghost Nov 10, 2021

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 machine for remote logging on a central syslog server, perform
the following steps:
</para>
Comment on lines +219 to +223
Copy link
Copy Markdown

@ghost ghost Nov 10, 2021

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
Copy Markdown

@ghost ghost Nov 10, 2021

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 log server
Comment thread
cwickert marked this conversation as resolved.
Outdated
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
Copy Markdown

@ghost ghost Nov 10, 2021

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
Copy Markdown

@ghost ghost Nov 10, 2021

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 machine for remote logging to your central log
Comment thread
cwickert marked this conversation as resolved.
Outdated
server. Repeat this procedure for all machines 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 log
server. This allows you to get a quick to get an overview of events on your
network.
Comment on lines +283 to +284
Copy link
Copy Markdown

@ghost ghost Nov 10, 2021

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 log server, perform the
Comment thread
cwickert marked this conversation as resolved.
Outdated
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
Copy Markdown

@dmpop dmpop Nov 11, 2021

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 log server and the remote logging clients.
Copy link
Copy Markdown
Contributor

@lproven lproven Sep 15, 2021

Choose a reason for hiding this comment

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

Suggested change
Run this check on both the log server and the remote logging clients.
Run this check on both the syslog server and the remote logging clients.

Copy link
Copy Markdown
Member Author

@cwickert cwickert Oct 8, 2021

Choose a reason for hiding this comment

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

Trying to avoid duplication…

Copy link
Copy Markdown
Contributor

@lproven lproven Oct 8, 2021

Choose a reason for hiding this comment

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

OK, OK, I get it. But I am not sure that [a] in docs, repetition is so bad as in normal prose, and [b] that repetition of the phrase "log server" instead is much of an improvement.

I stand by my point: I feel that consistent usage of the precise phrase is preferable.

Copy link
Copy Markdown
Member Author

@cwickert cwickert Oct 15, 2021

Choose a reason for hiding this comment

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

[a] It's not repetition but a mix of the long and the short phrase to avoid repetition. Just like you use an article instead of a noun when it's clear what you are referring to. We do this all the time, e.g. we first use 'DNS server' and then 'the server' or 'file permissions' and then just 'permissions'. This eases reading and makes the text shorter.
[b] It is consistent: I would argue that the text is consistent. For the first occurrence in a section I use the long term, then the shorter one.

IHMO readability is just as important as consistency, and in this case wins because there is no ambiguity. Do you see any room for misinterpretations? What other server could this sentence refer to?

Copy link
Copy Markdown

@ghost ghost Oct 15, 2021

Choose a reason for hiding this comment

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

[a] in docs, repetition is so bad as in normal prose

I concur with Liam here -- exact repetition helps with terminology and translation.

Copy link
Copy Markdown
Contributor

@lproven lproven Oct 20, 2021

Choose a reason for hiding this comment

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

Thanks.

We are basically only and always talking about servers. This logging server collects logs from other servers and nothing but other servers. So I think we need to be specific.

Copy link
Copy Markdown
Member Author

@cwickert cwickert Nov 10, 2021

Choose a reason for hiding this comment

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

We are basically only and always talking about servers. This logging server collects logs from other servers and nothing but other servers.

No, the machines that log remotely are not necessarily servers and we explicitly call them clients here. Whether or not they offer any service over the network is a completely different question, that is not been dealt with here.

Anyway, I give in and will change it accordingly.

</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
Copy Markdown
Contributor

@lproven lproven Sep 15, 2021

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
Copy Markdown

@ghost ghost Nov 10, 2021

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
Copy Markdown

@dmpop dmpop Nov 11, 2021

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
Copy Markdown

@ghost ghost Nov 11, 2021

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 to be set up first.
Copy link
Copy Markdown
Contributor

@lproven lproven Sep 15, 2021

Choose a reason for hiding this comment

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

Suggested change
requires a certificate infrastructure to be set up first.
requires you to set up a certificate infrastructure first.

Copy link
Copy Markdown
Contributor

@lproven lproven Sep 15, 2021

Choose a reason for hiding this comment

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

Rewording to avoid passive voice.

Copy link
Copy Markdown
Member Author

@cwickert cwickert Oct 8, 2021

Choose a reason for hiding this comment

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

What's wrong with passive voice? We need a CA, regardless of who sets it up. In fact, many organizations already have a CA and whoever configures the logging is not necessarily the same person that sets up the log server.

Copy link
Copy Markdown

@dmpop dmpop Oct 8, 2021

Choose a reason for hiding this comment

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

For some reason I was notified of this comment, so I feel the urge to chime in. 😄 Liam's suggestion sounds much better. The passive voice in general, and in this case in particular, sounds contrived. And you doesn't refer to a specific person but a collective you.

Copy link
Copy Markdown
Member Author

@cwickert cwickert Oct 8, 2021

Choose a reason for hiding this comment

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

So it's 2:2 now (@sknorr + me vs. @lproven and @dmpop) :-) Flip a 🪙 ?

Copy link
Copy Markdown

@dmpop dmpop Oct 8, 2021

Choose a reason for hiding this comment

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

The fact that Liam is a native speaker tips the scales in our favor.

Copy link
Copy Markdown
Contributor

@lproven lproven Oct 8, 2021

Choose a reason for hiding this comment

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

It is a fair point that the person building the syslog server may not be the same one.

How about:

"TLS encryption is strongly recommended, but requires that you already have a certificate infrastructure."

Copy link
Copy Markdown

@ghost ghost Oct 8, 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.

Style guide:

Use second person (“you”) to refer to the reader. Normally, the reader is the user or administrator who performs the actions described. Do not overuse “you.” It is often understood, especially in directions.

(NB: This does not read "Exclusively use second person to the refer to the reader" -- there is room for interpretation.)

Use passive voice if there is no emphasis on the object of the verb or if the performer of the action is unknown.

Both from: https://documentation.suse.com/style/current/single-html/docu_styleguide/#sec-language

Copy link
Copy Markdown
Member Author

@cwickert cwickert Nov 10, 2021

Choose a reason for hiding this comment

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

To avoid this discussion, I simplified
requires a certificate infrastructure to be set up first. to
requires a certificate infrastructure.
When or who sets it up is a different question, we just say it's a requirement.

Copy link
Copy Markdown
Member Author

@cwickert cwickert Nov 10, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

For some reason I was notified of this comment, […]

@dmpop, you were notified because I requested a review from you.

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

@dmpop dmpop Nov 11, 2021

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 log server. Consider filtering messages into separate
files by remote host or classify them by message category.
Copy link
Copy Markdown

@ghost ghost Nov 10, 2021

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>