Improve rendering of log excerpts

Log excerpts are inconsistently written using quotation or code blocks.
When the site is built, the generated markup is different, the former
generates a BLOCKQUOTE tag, and the later a PRE tag.  Styling of these
elements is very different, as code blocks do not wrap lines and
quotations wrap lines but also collapse spaces.  While it is possible to
skip new-line collapsing with some end-of-line spaces, this is
error-prone and sometimes missing.  As a result, a lot of extracts are
not rendered correctly.

In order to improve this, introduce a new liquid block `log` that we can
use in the markdown documents around log excerpts:

```
{% log %}
A very long line that can be larger than the screen of the user.
A second very long line that can also be larger that the screen of the user.
{% endlog %}
```

This new block transform each new-line character to an explicit BR tag,
and wraps the result in a BLOCKQUOTE tag with custom CSS styling.  This
styling makes it easier to read long/wrapped lines by indenting
continuation lines:

```
|<------------ screen width------------->|
| A very long line that can be larger    |
|   than the screen of the user.         |
| A second very long line that can also  |
|   be larger that the screen of the     |
|   user.                                |
```

Signed-off-by: Romain Tartière <romain@blogreen.org>

Author: smortex

_includes/head.html

@@ -13,6 +13,7 @@
 {% include globals.html %}
 {% include skins.html %}
 
+<link rel="stylesheet" href="{{ '/assets/css/log.css' | relative_url}}">
 <link rel="preload" href="https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@5/css/all.min.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
 <noscript><link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@5/css/all.min.css"></noscript>
 

_plugins/log.rb

@@ -0,0 +1,25 @@
+require "cgi"
+
+# Liquid block to render log excerpts
+#
+# {% log %}
+# New lines are preserved.
+# Long lines will be wrapped when displayed on screen.
+# {% endlog %}
+#
+# Will be rendered in the browser to:
+#
+# |<--------- screen size --------->|
+# | New lines are preserved.        |
+# | Long lines will be wrapped when |
+# |   displayed on screen.          |
+class LogBlock < Liquid::Block
+  def render(context)
+    output = '<blockquote class="log">'
+    output << CGI.escapeHTML(super.strip).gsub("\n", "<br/>")
+    output << "</blockquote>"
+    output
+  end
+end
+
+Liquid::Template.register_tag("log", LogBlock)

assets/css/log.scss

@@ -0,0 +1,12 @@
+---
+search: false
+toc: false
+---
+
+@import "minimal-mistakes/variables";
+
+blockquote.log {
+  text-indent: 2em hanging each-line;
+  font-family: $monospace;
+  white-space: pre-wrap;
+}

doc/_admin-guide/020_The_concepts_of_syslog-ng/007_The_structure_of_a_log_message/002_EWMM_messages.md

@@ -21,9 +21,9 @@ on the receiver side.
 
 The following is a sample log message in EWMM format.
 
-><13>1 2018-05-13T13:27:50.993+00:00 my-host @syslog-ng - - -  
->{"MESSAGE":"<34>Oct 11 22:14:15 mymachine su: 'su root' failed for username on  
->/dev/pts/8","HOST_FROM":"my-host","HOST":"my-host","FILE_NAME":"/tmp/in","._TAGS":".source.s_file"}
+{% log %}
+<13>1 2018-05-13T13:27:50.993+00:00 my-host @syslog-ng - - -  {"MESSAGE":"<34>Oct 11 22:14:15 mymachine su: 'su root' failed for username on  /dev/pts/8","HOST_FROM":"my-host","HOST":"my-host","FILE_NAME":"/tmp/in","._TAGS":".source.s_file"}
+{% endlog %}
 
 The message has the following parts:
 

doc/_admin-guide/040_Quick-start_guide/003_Managing_and_checking_syslog-ng_OSE_service_on_Linux.md

@@ -71,29 +71,33 @@ To check the status of {{ site.product.short_name }} service
 
 - **active (running)** - {{ site.product.short_name }} service is up and running
 
-    Example: {{ site.product.short_name }} service active  
-
-    > syslog-ng.service - System Logger Daemon  
-    > Loaded: loaded (/lib/systemd/system/syslog-ng.service; enabled; vendor preset: enabled)  
-    > Active: active (running) since Tue 2019-06-25 08:58:09 CEST; 5s ago  
-    > Main PID: 6575 (syslog-ng)  
-    > Tasks: 3  
-    > Memory: 13.3M  
-    > CPU: 268ms  
-    > CGroup: /system.slice/syslog-ng.service  
-    > 6575 /opt/syslog-ng/libexec/syslog-ng -F --no-caps --enable-core  
+    Example: {{ site.product.short_name }} service active
+
+    {% log %}
+    syslog-ng.service - System Logger Daemon
+    Loaded: loaded (/lib/systemd/system/syslog-ng.service; enabled; vendor preset: enabled)
+    Active: active (running) since Tue 2019-06-25 08:58:09 CEST; 5s ago
+    Main PID: 6575 (syslog-ng)
+    Tasks: 3
+    Memory: 13.3M
+    CPU: 268ms
+    CGroup: /system.slice/syslog-ng.service
+    6575 /opt/syslog-ng/libexec/syslog-ng -F --no-caps --enable-core
+    {% endlog %}
 
 - **inactive (dead)** - syslog-ng service is stopped
 
     Example: {{ site.product.short_name }} status inactive
 
-    > syslog-ng.service - System Logger Daemon  
-    > Loaded: loaded (/lib/systemd/system/syslog-ng.service; enabled; vendor preset: enabled)  
-    > Active: inactive (dead) since Tue 2019-06-25 09:14:16 CEST; 2min 18s ago  
-    > Process: 6575 ExecStart=/opt/syslog-ng/sbin/syslog-ng -F --no-caps --enable-core $SYSLOGNG_OPTIONS(code=exited, status=0/SUCCESS)  
-    > Main PID: 6575 (code=exited, status=0/SUCCESS)  
-    > Status: "Shutting down... Tue Jun 25 09:14:16 2019"  
-    > Jun 25 09:14:31 as-syslog-srv systemd: Stopped System Logger Daemon.
+    {% log %}
+    syslog-ng.service - System Logger Daemon
+    Loaded: loaded (/lib/systemd/system/syslog-ng.service; enabled; vendor preset: enabled)
+    Active: inactive (dead) since Tue 2019-06-25 09:14:16 CEST; 2min 18s ago
+    Process: 6575 ExecStart=/opt/syslog-ng/sbin/syslog-ng -F --no-caps --enable-core $SYSLOGNG_OPTIONS(code=exited, status=0/SUCCESS)
+    Main PID: 6575 (code=exited, status=0/SUCCESS)
+    Status: "Shutting down... Tue Jun 25 09:14:16 2019"
+    Jun 25 09:14:31 as-syslog-srv systemd: Stopped System Logger Daemon.
+    {% endlog %}
 
 ### Checking the process of {{ site.product.short_name }}
 
@@ -105,19 +109,20 @@ ps u `pidof syslog-ng`
 
 Expected output example:
 
-> USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
->  
-> syslogng 6709 0.0 0.6 308680 13432 ? Ss 09:17 0:00  
-> /opt/syslog-ng/libexec/syslog-ng -F --no-caps --enable-core
+{% log %}
+USER     PID  %CPU %MEM VSZ    RSS   TTY STAT START TIME COMMAND
+syslogng 6709 0.0  0.6  308680 13432 ?   Ss   09:17 0:00 /opt/syslog-ng/libexec/syslog-ng -F --no-caps --enable-core
+{% endlog %}
 
 ```bash
 ps axu | grep syslog-ng | grep -v grep
 ```
 
 Expected output example:
 
-> syslogng 6709 0.0 0.6 308680 13432 ? Ss 09:17 0:00  
-> /opt/syslog-ng/libexec/syslog-ng -F --no-caps --enable-core
+{% log %}
+syslogng 6709 0.0  0.6  308680 13432 ?   Ss   09:17 0:00 /opt/syslog-ng/libexec/syslog-ng -F --no-caps --enable-core
+{% endlog %}
 
 ### Checking the internal logs of {{ site.product.short_name }}**
 
@@ -154,10 +159,11 @@ If the numbers are changing, {{ site.product.short_name }} is processing the mes
 
 Example: output example
 
-> Every 2.0s: /opt/syslog-ng/sbin/syslog-ng-ctl stats | grep  
-> ^center       Tue Jun 25 10:33:25 2019  
-> center;;queued;a;processed;112  
-> center;;received;a;processed;28  
+{% log %}
+Every 2.0s: /opt/syslog-ng/sbin/syslog-ng-ctl stats | grep ^center       Tue Jun 25 10:33:25 2019
+center;;queued;a;processed;112
+center;;received;a;processed;28
+{% endlog %}
 
 ### Source statistics
 
@@ -173,11 +179,12 @@ If the numbers are changing, {{ site.product.short_name }} is receiving messages
 
 Example: output example
 
-> Every 2.0s: /opt/syslog-ng/sbin/syslog-ng-ctl stats | grep  
-> ^source      Tue Jun 25 10:40:50 2019  
-> source;s_null;;a;processed;0  
-> source;s_net;;a;processed;0  
-> source;s_local;;a;processed;90  
+{% log %}
+Every 2.0s: /opt/syslog-ng/sbin/syslog-ng-ctl stats | grep ^source      Tue Jun 25 10:40:50 2019
+source;s_null;;a;processed;0
+source;s_net;;a;processed;0
+source;s_local;;a;processed;90
+{% endlog %}
 
 ### Destination statistics
 
@@ -193,12 +200,13 @@ If the numbers are changing, {{ site.product.short_name }} is receiving messages
 
 Example: output example
 
-> Every 2.0s: /opt/syslog-ng/sbin/syslog-ng-ctl stats | grep  
-> ^destination      Tue Jun 25 10:41:02 2019  
-> destination;d_logserver2;;a;processed;90  
-> destination;d_messages;;a;processed;180  
-> destination;d_logserver;;a;processed;90  
-> destination;d_null;;a;processed;0  
+{% log %}
+Every 2.0s: /opt/syslog-ng/sbin/syslog-ng-ctl stats | grep  ^destination      Tue Jun 25 10:41:02 2019
+destination;d_logserver2;;a;processed;90
+destination;d_messages;;a;processed;180
+destination;d_logserver;;a;processed;90
+destination;d_null;;a;processed;0
+{% endlog %}
 
 **NOTE:** If you find error messages in the internal logs, messages are not
 processed by {{ site.product.short_name }} or you encounter any issue, you have the

doc/_admin-guide/060_Sources/070_Network/001_Proxy_protocol_support/000_Proxy_protocol_working_mechanism.md

@@ -21,18 +21,19 @@ macros to every message the comes through the connection later on:
 
 - PROXY_DSTPORT (the destination port of the proxy)
 
->**NOTE:** Consider the following about macros and headers:  
->  
+>**NOTE:** Consider the following about macros and headers:
+>
 >- When the proxy protocol header is PROXY UNKNOWN, no additional macros are added.
->  
+>
 >- When {{ site.product.short_name }} cannot parse a proxy protocol header, the connection is closed:
->  
-> [2020-11-20T17:33:22.189458] PROXY protocol header received; line='PROXYdsfj'  
-> [2020-11-20T17:33:22.189475] Error parsing PROXY protocol header;  
-> [2020-11-20T17:33:22.189517] Syslog connection closed; fd='13',  
-> client='AF_INET(127.0.0.1:51665)', local='AF_INET(0.0.0.0:6666)'
-> [2020-11-20T17:33:22.189546] Freeing PROXY protocol source driver; driver='0x7fffcba5bcf0'  
+>
+> {% log %}
+> [2020-11-20T17:33:22.189458] PROXY protocol header received; line='PROXYdsfj'
+> [2020-11-20T17:33:22.189475] Error parsing PROXY protocol header;
+> [2020-11-20T17:33:22.189517] Syslog connection closed; fd='13', client='AF_INET(127.0.0.1:51665)', local='AF_INET(0.0.0.0:6666)'
+> [2020-11-20T17:33:22.189546] Freeing PROXY protocol source driver; driver='0x7fffcba5bcf0'
 > [2020-11-20T17:33:22.189600] Closing log transport fd; fd='13'
+> {% endlog %}
 {: .notice--info}
 
 **NOTE:** Since the driver only implements version 1 of the protocol, it

doc/_admin-guide/060_Sources/070_Network/001_Proxy_protocol_support/001_Proxy_protocol_configuration.md

@@ -76,9 +76,8 @@ the output.
 With the PROXY TCP4 192.168.1.1 10.10.0.1 1111 2222 input header, the
 output looks like this:
 
-> {"SOURCE":"s_tcp_pp","PROXIED_SRCPORT":"1111","PROXIED_SRCIP":"192.168.1.1",  
->"PROXIED_IP_VERSION":"4","PROXIED_DSTPORT":"2222","PROXIED_DSTIP":"10.10.0.1",  
->"PROGRAM":"TestMsg","MESSAGE":"","LEGACY_MSGHDR":"TestMsg",  
->"HOST_FROM":"localhost","HOST":"localhost"}
+{% log %}
+{"SOURCE":"s_tcp_pp","PROXIED_SRCPORT":"1111","PROXIED_SRCIP":"192.168.1.1", "PROXIED_IP_VERSION":"4","PROXIED_DSTPORT":"2222","PROXIED_DSTIP":"10.10.0.1", "PROGRAM":"TestMsg","MESSAGE":"","LEGACY_MSGHDR":"TestMsg", "HOST_FROM":"localhost","HOST":"localhost"}
+{% endlog %}
 
 Note that the macros that {{ site.product.short_name }} adds to the message appear in the output.

doc/_admin-guide/060_Sources/102_osquery/README.md

@@ -14,7 +14,7 @@ The osquery() source of {{ site.product.short_name }} allows you read the result
 periodical osquery queries (from the
 /var/log/osquery/osqueryd.results.log file) and automatically parse the
 messages (if you want to use {{ site.product.short_name }} to send log messages to
-osquery, read this blogpost).  
+osquery, read this blogpost).
 
 For example, you can:
 
@@ -100,16 +100,9 @@ the outgoing message will be a well-formed JSON message.
 
 #### Input message
 
->{"name":"pack_osquery-monitoring_osquery_info","hostIdentifier":"testhost",  
->"calendarTime":"Fri Jul 21 10:04:41 2017 >UTC","unixTime":"1500631481",  
->"decorations":{"host_uuid":"4C4C4544-004D-3610-8043-C2C04F4D3332",  
->"username":"myuser"},>"columns":{"build_distro":"xenial",  
->"build_platform":"ubuntu",>"config_hash":"43cd1c6a7d0c283e21e026a53e619b2e582e94ee",  
->"config_valid":"1","counter":"4","extensions":"active",  
->"instance_id":"d0c3eb0d-f8e0-4bea-868b-18a2c61b438d","pid":"19764",  
->"resident_size":"26416000",>"start_time":"1500629552","system_time":"223",  
->"user_time":"476","uuid":"4C4C4544-004D-3610-8043-C2C04F4D3332",
->"version":"2.5.0","watcher":"19762"},"action":"added"}
+{% log %}
+{"name":"pack_osquery-monitoring_osquery_info","hostIdentifier":"testhost", "calendarTime":"Fri Jul 21 10:04:41 2017 >UTC","unixTime":"1500631481", "decorations":{"host_uuid":"4C4C4544-004D-3610-8043-C2C04F4D3332", "username":"myuser"},>"columns":{"build_distro":"xenial", "build_platform":"ubuntu",>"config_hash":"43cd1c6a7d0c283e21e026a53e619b2e582e94ee", "config_valid":"1","counter":"4","extensions":"active", "instance_id":"d0c3eb0d-f8e0-4bea-868b-18a2c61b438d","pid":"19764", "resident_size":"26416000",>"start_time":"1500629552","system_time":"223", "user_time":"476","uuid":"4C4C4544-004D-3610-8043-C2C04F4D3332", "version":"2.5.0","watcher":"19762"},"action":"added"}
+{% endlog %}
 
 #### {{ site.product.short_name }} configuration
 
@@ -138,16 +131,8 @@ log {
 
 #### Outgoing message
 
->Outgoing message; message='{"_osquery":{"unixTime":"1500631481",  
->"name":"pack_osquery-monitoring_osquery_info","hostIdentifier":"testhost",  
->"decorations":{"username":"myuser","host_uuid":"4C4C4544-004D-3610-8043-C2C04F4D3332"},  
->"columns":{"watcher":"19762","version":"2.5.0","uuid":"4C4C4544-004D-3610-8043-C2C04F4D3332",  
->"user_time":"476","system_time":"223","start_time":"1500629552",  
->"resident_size":"26416000","pid":"19764","instance_id":"d0c3eb0d-f8e0-4bea-868b-18a2c61b438d",  
->"extensions":"active","counter":"4","config_valid":"1",  
->"config_hash":"43cd1c6a7d0c283e21e026a53e619b2e582e94ee","build_platform":"ubuntu",  
->"build_distro":"xenial"},"calendarTime":"Fri Jul 21 10:04:41 2017 UTC","action":"added"}}\x0a'
+> Outgoing message; message='{"_osquery":{"unixTime":"1500631481", "name":"pack_osquery-monitoring_osquery_info","hostIdentifier":"testhost", "decorations":{"username":"myuser","host_uuid":"4C4C4544-004D-3610-8043-C2C04F4D3332"}, "columns":{"watcher":"19762","version":"2.5.0","uuid":"4C4C4544-004D-3610-8043-C2C04F4D3332", "user_time":"476","system_time":"223","start_time":"1500629552", "resident_size":"26416000","pid":"19764","instance_id":"d0c3eb0d-f8e0-4bea-868b-18a2c61b438d", "extensions":"active","counter":"4","config_valid":"1", "config_hash":"43cd1c6a7d0c283e21e026a53e619b2e582e94ee","build_platform":"ubuntu", "build_distro":"xenial"},"calendarTime":"Fri Jul 21 10:04:41 2017 UTC","action":"added"}}\x0a'
 
 To configure a destination to send the log messages to Elasticsearch,
-see elasticsearch-http: Sending messages to Elasticsearch HTTP Bulk API.  
+see elasticsearch-http: Sending messages to Elasticsearch HTTP Bulk API.
 For other destinations, see destination: Forward, send, and store log messages.

doc/_admin-guide/060_Sources/140_Python/001_Python_logmessage_API.md

@@ -64,11 +64,13 @@ set in the message, and uses the IP address of the {{ site.product.short_name }}
 the hostname (to use the hostname instead of the IP address, set the
 use-dns() or use-fqdn() options in the Python source).
 
->msg_ietf = LogMessage.parse('<165>1 2003-10-11T22:14:15.003Z mymachine.example.com  
->evntslog - ID47 [exampleSDID@32473 iut="3" eventSource="Application" eventID="1011"]  
->An application event log entry', self.parse_options)
->msg_bsd = LogMessage.parse('<34>Oct 11 22:14:15 mymachine su: \'su root\' failed for  
->lonvick on /dev/pts/8', self.parse_options)
+```python
+msg_ietf = LogMessage.parse('<165>1 2003-10-11T22:14:15.003Z mymachine.example.com \
+evntslog - ID47 [exampleSDID@32473 iut="3" eventSource="Application" eventID="1011"] \
+An application event log entry', self.parse_options)
+msg_bsd = LogMessage.parse('<34>Oct 11 22:14:15 mymachine su: \'su root\' failed for \
+lonvick on /dev/pts/8', self.parse_options)
+```
 
 ## set_pri() method
 

doc/_admin-guide/060_Sources/155_stdin/README.md

@@ -35,6 +35,8 @@ used to collect a test message:
 $ echo "this is a test message" | ./syslog-ng -Fe --no-caps
 ```
 
-> [2017-11-14T13:47:16.757938] syslog-ng starting up; version='3.12.1'  
-> [2017-11-14T13:47:16.758195] syslog-ng shutting down; version='3.12.1'  
-> Nov 14 13:47:16 testserver this is a test message
+{% log %}
+[2017-11-14T13:47:16.757938] syslog-ng starting up; version='3.12.1'
+[2017-11-14T13:47:16.758195] syslog-ng shutting down; version='3.12.1'
+Nov 14 13:47:16 testserver this is a test message
+{% endlog %}