Merge pull request #71 from axoflow/check-hostname-update

Documents the check-hostname source-level option

content/chapter-global-options/reference-options/_index.md

@@ -121,9 +121,20 @@ For example, consider a client-relay-server scenario with the following hostname
 | Accepted values: | `yes`, `no` |
 | Default:         | `no`           |
 
-*Description:* Enable or disable checking whether the hostname contains valid characters.
+*Description:* When receiving messages, {{< product >}} can check whether the hostname contains valid characters.
 
+Valid characters are:
 
+- alphanumeric characters (A-Z, a-z, 0-9)
+- the dash (`-`) and underscore (`_`) characters
+- the dot (`.`) and the colon (`:`) characters
+- the `@` and slash (`/`)
+
+If the hostname contains invalid characters, {{< product >}} sets the `syslog.invalid_hostname` tag for the message, and doesn't parse the `${HOST}` field from the message.
+
+The `check-hostname()` global option applies to the following sources: [`file()`]({{< relref "/chapter-sources/configuring-sources-file/_index.md" >}}), [`network()`]({{< relref "/chapter-sources/configuring-sources-network/_index.md" >}}), [`pipe()`]({{< relref "/chapter-sources/source-pipe/_index.md" >}}), [`program()`]({{< relref "/chapter-sources/source-program/_index.md" >}}), [`stdin()`]({{< relref "/chapter-sources/configuring-sources-stdin/_index.md" >}}), [`syslog()`]({{< relref "/chapter-sources/source-syslog/_index.md" >}}), [`systemd-syslog()`]({{< relref "/chapter-sources/source-system/_index.md" >}}), [`unix-dgram()`]({{< relref "/chapter-sources/source-unixstream/_index.md" >}}), [`unix-stream()`]({{< relref "/chapter-sources/source-unixstream/_index.md" >}}), [`wildcard-file()`]({{< relref "/chapter-sources/configuring-sources-wildcard-file/_index.md" >}}). Instead of using the global option, you can also set the `check-hostname()` option for the specific source.
+
+For the [`python()`]({{< relref "/chapter-sources/python-source/_index.md" >}}) and [`python-fetcher()`]({{< relref "/chapter-sources/python-fetcher-source/_index.md" >}}) sources and the [`syslog-parser()`]({{< relref "/chapter-parsers/parser-syslog/_index.md" >}}) parser you can enable this option as a flag.
 
 ## create-dirs() {#global-option-create-dirs}
 

content/chapter-parsers/parser-syslog/parser-syslog-options/_index.md

@@ -14,6 +14,8 @@ The `syslog-parser()` has the following options:
 
 {{< include-headless "chunk/option-source-flags.md" >}}
 
+For the `syslog-parser()` you can also set the `check-hostname` flag, which is equivalent with the [`check-hostname()` global option]({{< relref "/chapter-global-options/reference-options/_index.md#global-option-check-hostname" >}}), but only applies to this parser.
+
 ## sdata-prefix()
 
 |           |                              |

content/chapter-sources/configuring-sources-file/reference-source-file/_index.md

@@ -6,6 +6,8 @@ weight:  300
 
 The `file()` driver has the following options:
 
+{{< include-headless "chunk/option-source-check-hostname.md" >}}
+
 {{< include-headless "chunk/option-source-default-facility.md" >}}
 
 {{< include-headless "chunk/option-source-default-priority.md" >}}

content/chapter-sources/configuring-sources-stdin/stdin()-source-options/_index.md

@@ -6,6 +6,8 @@ weight:  100
 
 The `stdin()` driver has the following options:
 
+{{< include-headless "chunk/option-source-check-hostname.md" >}}
+
 {{% include-headless "chunk/option-source-default-facility.md" %}}
 
 {{% include-headless "chunk/option-source-default-priority.md" %}}

content/chapter-sources/configuring-sources-systemd-syslog/reference-source-systemd-syslog/_index.md

@@ -6,4 +6,6 @@ weight:  100
 
 The `systemd-syslog()` driver has the following options:
 
+{{< include-headless "chunk/option-source-check-hostname.md" >}}
+
 {{< include-headless "chunk/option-destination-hook.md" >}}

content/chapter-sources/configuring-sources-wildcard-file/reference-source-wildcard-file/_index.md

@@ -25,6 +25,8 @@ The `wildcard-file()` driver has the following options:
 
 {{% include-headless "chunk/synopsis-wildcard-file-source-example.md" %}}
 
+{{< include-headless "chunk/option-source-check-hostname.md" >}}
+
 {{% include-headless "chunk/option-source-default-facility.md" %}}
 
 {{% include-headless "chunk/option-source-default-priority.md" %}}

content/chapter-sources/python-source/reference-source-python/_index.md

@@ -47,6 +47,8 @@ For details, see {{% xref "/chapter-configuration-file/python-code-external-file
 
 {{< include-headless "chunk/option-source-flags.md" >}}
 
+For the `python()` and `python-fetcher()` sources you can also set the `check-hostname` flag, which is equivalent with the [`check-hostname()` global option]({{< relref "/chapter-global-options/reference-options/_index.md#global-option-check-hostname" >}}), but only applies to this source.
+
 The flags and the hostname-related options (for example, `use-dns`) set in the configuration file influence the behavior of the `LogMessage.parse()` method of the Python source. They have no effect if you set the message or the hostname directly, without using `LogMessage.parse()`.
 
 

content/chapter-sources/source-pipe/reference-source-pipe/_index.md

@@ -6,6 +6,8 @@ weight:  100
 
 The `pipe` driver has the following options:
 
+{{< include-headless "chunk/option-source-check-hostname.md" >}}
+
 {{% include-headless "chunk/option-destination-create-dirs.md" %}}
 
 {{< include-headless "chunk/option-source-flags.md" >}}

content/chapter-sources/source-program/reference-source-program/_index.md

@@ -6,6 +6,8 @@ weight:  100
 
 The `program` driver has the following options:
 
+{{< include-headless "chunk/option-source-check-hostname.md" >}}
+
 {{< include-headless "chunk/option-source-flags.md" >}}
 
 {{< include-headless "chunk/option-destination-hook.md" >}}

content/chapter-sources/source-unixstream/reference-source-unixstream/_index.md

@@ -6,6 +6,8 @@ weight:  300
 
 These two drivers behave similarly: they open an `AF_UNIX` socket and start listening on it for messages. The following options can be specified for these drivers:
 
+{{< include-headless "chunk/option-source-check-hostname.md" >}}
+
 {{% include-headless "chunk/option-destination-create-dirs.md" %}}
 
 {{% include-headless "chunk/option-source-encoding.md" %}}

content/headless/chunk/option-source-check-hostname.md

@@ -0,0 +1,12 @@
+---
+---
+<!-- DISCLAIMER: This file is based on the syslog-ng Open Source Edition documentation https://github.com/balabit/syslog-ng-ose-guides/commit/2f4a52ee61d1ea9ad27cb4f3168b95408fddfdf2 and is used under the terms of The syslog-ng Open Source Edition Documentation License. The file has been modified by Axoflow. -->
+
+## check-hostname()
+
+|          |                                                                                 |
+| -------- | ------------------------------------------------------------------------------- |
+| Type:    | boolean (`yes` or `no`)                                                         |
+| Default: | Use the global `check-hostname()` option, which defaults to `no`. |
+
+Checks that the hostname contains valid characters. Uses the value of the [global option]({{< relref "/chapter-global-options/reference-options/_index.md#global-option-check-hostname" >}}) if not specified.

content/headless/chunk/source-syslog-options.md

@@ -1,6 +1,9 @@
 ---
 ---
 <!-- DISCLAIMER: This file is based on the syslog-ng Open Source Edition documentation https://github.com/balabit/syslog-ng-ose-guides/commit/2f4a52ee61d1ea9ad27cb4f3168b95408fddfdf2 and is used under the terms of The syslog-ng Open Source Edition Documentation License. The file has been modified by Axoflow. -->
+
+{{< include-headless "chunk/option-source-check-hostname.md" >}}
+
 {{% include-headless "chunk/option-source-dynamic-window-size.md" %}}
 
 {{% include-headless "chunk/option-source-ebpf.md" %}}

content/headless/chunk/tags-parsing-errors.md

@@ -6,7 +6,7 @@
 
 - `message.utf8_sanitized`: The message is not valid UTF-8.
 - `syslog.missing_timestamp`: The message has no timestamp.
-- `syslog.invalid_hostname`: The hostname field doesn't seem to be valid, for example, it contains invalid characters.
+- `syslog.invalid_hostname`: The hostname field doesn't seem to be valid, for example, it contains invalid characters. For details on the valid characters, see the [`check-hostname()` global option]({{< relref "/chapter-global-options/reference-options/_index.md#global-option-check-hostname" >}}).
 - `syslog.missing_pri`: The priority (PRI) field is missing from the message.
 - `syslog.unexpected_framing`: An octet count was found in front of the message, suggested invalid framing.
 - `syslog.rfc3164_missing_header`: The date and the host are missing from an RFC3164-formatted message - practically that's the entire header of RFC3164-formatted messages.