syslog() source updates (#218)

Updated syslog() source options with special attention to
transport(auto) updates in 4.9.

Author: zsoltgyulai94

_includes/doc/admin-guide/options/source-transport.md

@@ -1,19 +1,28 @@
 ## transport()
 
-|  Type:|      udp, tcp, tls, proxied-tcp, proxied-tls, proxied-tls-passthrough, text-with-nuls|
-  |Default:|   tcp|
-
-*Description:* Specifies the protocol used to receive messages from the
-source.
-
-For detailed information about how {{ site.product.short_name }} supports the
-proxied-tcp, the proxied-tls, and the proxied-tls-passthrough
-parameters, see Proxy Protocol support.
-text-with-nuls: Allows embedded **NUL** characters in the message from a
-TCP source, that is, {{ site.product.short_name }} will not delimiter the incoming
-messages on **NUL** characters, only on **newline** characters (contrary
-to tcp transport, which splits the incoming log on **newline**
-characters and **NUL** characters).
+|Type:   | `auto`, `proxied-tcp`, `proxied-tls`, `proxied-tls-passthrough`, `tcp`, `text-with-nuls`, `tls`, `udp`|
+|Default:|   `tcp`|
+
+**Description:** This option specifies the protocol used to receive messages from the source.
+
+* `auto`: Available in {{ site.product.short_name }} 4.9 and later versions. The `transport(auto)` option of the syslog() source allows you to support all TCP-based variants with a single source driver. In {{ site.product.short_name }} there are numerous transport options and protocols. RFC3164 describes the legacy or BSD syslog protocol, while RFC5424 refers to the more recent syslog protocol. RFC5424 formatted messages normally come with framing or octet counting (RFC6587), where messages are prefixed with the length of the message. Furthermore, some software use RFC5424 message formatting, but without octet counting. In versions prior to {{ site.product.short_name }} 4.9, this many variants meant that you had to configure a different port on syslog-ng for each of them to parse them correctly. In {{ site.product.short_name }} 4.9 and later versions, the new `transport(auto)` option of syslog-ng allows you collect all of these variants using a single port.
+
+### Example: configuring syslog() source with transport(auto)
+
+```config
+source s_auto {
+  syslog(port(514) transport(auto));
+};
+destination d_auto {
+  file("/var/log/auto.txt");
+};
+log {
+  source(s_auto); destination(d_auto);
+};
+```
+
+* `proxied-tcp`, `proxied-tls`, `proxied-tls-passthrough`: Refers to the HAProxy Proxy Protocol. For more information, see Proxy Protocol support.
+* `text-with-nuls`: Allows embedded `NUL` characters in the message from a TCP source, that is, {{ site.product.short_name }} will not delimiter the incoming messages on `NUL` characters, only on `newline` characters (contrary to tcp transport, which splits the incoming log on `newline` characters and `NUL` characters).
 
 **NOTE:** The {{ site.product.short_name }} application does not support embedded **NUL**
 characters everywhere, so it is recommended that you also use

_includes/doc/admin-guide/warnings/tcp-warning.md

@@ -0,0 +1,5 @@
+>![]({{ site.baseurl}}/assets/images/caution.png) **CAUTION:**
+>The tcp-keepalive-time(), tcp-keepalive-probes(), and tcp-keepalive-intvl() options only work on platforms which support the TCP_KEEPCNT, TCP_KEEPIDLE,and TCP_KEEPINTVL setsockopts. Currently, this is Linux.
+>
+>A connection that has no traffic is closed after tcp-keepalive-time() + tcp-keepalive-intvl() * tcp-keepalive-probes() seconds.
+{: .notice--warning}

doc/_admin-guide/060_Sources/170_Syslog/000_syslog_source_options.md

@@ -13,6 +13,16 @@ The syslog() driver has the following options.
 
 {% include doc/admin-guide/options/dynamic-window-size.md %}
 
+## ebpf()
+
+|Type:   | string|
+|Default:|   None|
+
+This option is available in {{ site.product.short_name }} 4.2 and later versions.
+
+*Description:* By default, the kernel selects the receive socket for a specific UDP randomly based on the source IP/port of the sender. You can customize this algorithm using the Extended Berkeley Packet Filter (eBPF) plugin. The `ebpf()` option changes the kernel’s `SO_REUSEPORT` algorithm so that all messages are randomly placed into one of the UDP sockets. The decision which UDP socket buffer a datagram is placed is made for every datagram, and not once for every stream. This means that messages are perfectly load-balanced across your set of UDP sockets. While this resolves the imbalance between the sockets and results in perfect load balancing, you will lose ordering between messages from the same sender, which is the price to pay for increased throughput.
+
+
 {% include doc/admin-guide/options/encoding.md %}
 
 {% include doc/admin-guide/options/source-flags.md %}
@@ -23,11 +33,12 @@ The syslog() driver has the following options.
 
 ## interface()
 
+Available in {{ site.product.short_name }} 3.19 and later versions.
+
 |  Type:|      string|
   |Default:|   None|
 
 *Description:* Bind to the specified interface instead of an IP address.
-Available in 3.19 and later.
 
 {% include doc/admin-guide/options/ip-localip.md %}
 
@@ -73,6 +84,39 @@ Available in 3.19 and later.
 
 {% include doc/admin-guide/options/tags.md %}
 
+## tcp-keepalive-intvl()
+
+Available in {{ site.product.short_name }} 3.4 and later versions.
+
+|Type:   | number [seconds]|
+|Default:|   `0`|
+
+*Description:* This option specifies the interval between subsequential keepalive probes in seconds, regardless of the traffic exchanged in the connection. This option is equivalent to `/proc/sys/net/ipv4/tcp_keepalive_intvl`. The default value is `0`, which results in using the kernel default.
+
+{% include doc/admin-guide/warnings/tcp-warning.md %}
+
+## tcp-keepalive-probes()
+
+Available in {{ site.product.short_name }} 3.4 and later versions.
+
+|Type:   | number [seconds]|
+|Default:|   `0`|
+
+*Description:* This option specifies the number of unacknowledged probes to send before considering the connection dead. This option is equivalent to `/proc/sys/net/ipv4/tcp_keepalive_probes`. The default value is `0`, which results in using the kernel default.
+
+{% include doc/admin-guide/warnings/tcp-warning.md %}
+
+## tcp-keepalive-time()
+
+Available in {{ site.product.short_name }} 3.4 and later versions.
+
+|Type:   | number [seconds]|
+|Default:|   `0`|
+
+*Description:* This option specifies the interval between the last data packet sent and the first keepalive probe in seconds. This option is equivalent to `/proc/sys/net/ipv4/tcp_keepalive_time`. The default value is `0`, which results in using the kernel default.
+
+{% include doc/admin-guide/warnings/tcp-warning.md %}
+
 {% include doc/admin-guide/options/time-zone.md %}
 
 {% include doc/admin-guide/options/source-transport.md %}