New task: Configure a central syslog server #28
Conversation
xml/task-configure-syslog-server.xml
Outdated
| <para> | ||
| This basic setup does not include encryption and is only suitable for | ||
| trusted internal networks. TLS encryption is strongly recommended but | ||
| requires a certificate infrastructure to be set up first. |
There was a problem hiding this comment.
| requires a certificate infrastructure to be set up first. | |
| requires you to set up a certificate infrastructure first. |
There was a problem hiding this comment.
Rewording to avoid passive voice.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
The fact that Liam is a native speaker tips the scales in our favor.
There was a problem hiding this comment.
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."
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
For some reason I was notified of this comment, […]
@dmpop, you were notified because I requested a review from you.
xml/task-configure-syslog-server.xml
Outdated
| reason. | ||
| </para> | ||
| <para> | ||
| Run this check on both the log server and the remote logging clients. |
There was a problem hiding this comment.
| 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. |
There was a problem hiding this comment.
Trying to avoid duplication…
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
[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?
There was a problem hiding this comment.
[a] in docs, repetition is so bad as in normal prose
I concur with Liam here -- exact repetition helps with terminology and translation.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
| <term>Is the firewall open?</term> | ||
| <listitem> | ||
| <para> | ||
| Check if the firewall on the log server is open with |
There was a problem hiding this comment.
| Check if the firewall on the log server is open with | |
| Check if the firewall on the syslog server is open with |
There was a problem hiding this comment.
I would support Liam's suggestion (unsurprising, I guess ...)
Most but not all suggestions applied, others will follow manually. Co-authored-by: Liam Proven <[email protected]>
|
I have now replaced all but one instance of "log server" with "syslog server". The only remaining occurrence of "log server" is in line 109, where we have "syslog server" right before it in line 108 repeating this really sounds awkward. @sknorr or @dmpop, please be so kind as to review and approve this. |
| The <package>rsyslog</package> package is installed on all machines. | ||
| If not, run <command>zypper in yast2-mail</command> to install it. | ||
| </para> | ||
| <!-- <screen>&prompt.root;<command>zypper in rsyslog</command></screen> --> |
There was a problem hiding this comment.
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
[...]| <title>Configure the central <systemitem>rsyslog</systemitem> server</title> | ||
| <para> | ||
| To set up a central syslog server, perform the following steps: | ||
| </para> |
There was a problem hiding this comment.
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.)
| </para> | ||
| <step> | ||
| <para> | ||
| Edit the configuration file |
There was a problem hiding this comment.
This step does not tell you anything about editing things, soo... maybe reword like this:
| Edit the configuration file | |
| In an editor, open the configuration file |
| <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. |
There was a problem hiding this comment.
I am a moderate fan of putting port numbers into literals. I won't be offended if you disagree though.
| 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>. |
| <title>TCP versus UDP protocol</title> | ||
| <para> | ||
| Traditionally syslog uses the UDP protocol to transmit log messages over | ||
| the network. This involves less overhead, but lacks reliability. Log |
There was a problem hiding this comment.
Improve wording:
| the network. This involves less overhead, but lacks reliability. Log | |
| the network. This creates less overhead, but is less reliable. Log |
| syslog server. This allows you to get a quick overview of events on your | ||
| network. |
There was a problem hiding this comment.
Sounds better to me, but not a native speaker I am:
| 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. |
| <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 |
There was a problem hiding this comment.
Wordy:
| 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 |
There was a problem hiding this comment.
You don't perform steps. You perform tasks and follow steps.
There was a problem hiding this comment.
My tendency is toward "either version works" here, too.
| Setting up a central syslog server consists of two parts. First you configure | ||
| the central log server, then the clients for remote logging. |
There was a problem hiding this comment.
An (imo) more accurate way to describe the task that also avoids the awkwardness you mentioned about repeating the word "syslog server":
| 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. |
| <term>Is the firewall open?</term> | ||
| <listitem> | ||
| <para> | ||
| Check if the firewall on the log server is open with |
There was a problem hiding this comment.
I would support Liam's suggestion (unsurprising, I guess ...)
| <para> | ||
| In this configuration, all messages from remote hosts will be treated the | ||
| same on the central syslog server. Consider filtering messages into separate | ||
| files by remote host or classify them by message category. |
There was a problem hiding this comment.
parallel phrasing (filter_ing_ + classify_ing_)
| files by remote host or classify them by message category. | |
| files by remote host or classifying them by message category. |
| <itemizedlist> | ||
| <listitem> | ||
| <para> | ||
| You have installed your product and your system is up and running. |
There was a problem hiding this comment.
What product? What system? It's the first time you mention them.
| <listitem> | ||
| <para> | ||
| The <package>rsyslog</package> package is installed on all machines. | ||
| If not, run <command>zypper in yast2-mail</command> to install it. |
There was a problem hiding this comment.
| If not, run <command>zypper in yast2-mail</command> to install it. | |
| Otherwise, run <command>zypper in yast2-mail</command> to install it. |
| <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 |
There was a problem hiding this comment.
| 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 |
| <important> | ||
| <title>TCP versus UDP protocol</title> | ||
| <para> | ||
| Traditionally syslog uses the UDP protocol to transmit log messages over |
There was a problem hiding this comment.
Traditionally? Not the word you'd use in a tech doc. Perhaps by default?
| unreliability, using TCP recommended. --> | ||
| </para> | ||
| <para> | ||
| The TCP protocol is more reliable and should be preferred over UDP. |
There was a problem hiding this comment.
| 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. |
| <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 |
There was a problem hiding this comment.
You don't perform steps. You perform tasks and follow steps.
| <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 |
There was a problem hiding this comment.
| Check it is running with | |
| Check whether it is running with |
| <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 |
There was a problem hiding this comment.
| 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 |
| trusted internal networks. TLS encryption is strongly recommended, but | ||
| requires a certificate infrastructure. |
There was a problem hiding this comment.
| 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. |
| requires a certificate infrastructure. | ||
| </para> | ||
| <para> | ||
| In this configuration, all messages from remote hosts will be treated the |
There was a problem hiding this comment.
| In this configuration, all messages from remote hosts will be treated the | |
| In this configuration, all messages from remote hosts are treated the |
|
@dmpop Ignore my review request, I didn't see your comments. Thanks, I'll deal with them tomorrow. |
Feel free to make changes as you like. Please take care of merging this while I'm away over the weekend. TIA!
task-configure-central-syslog-server_color_en.pdf