tls: Add descriptions for x509v3 alt name verification (tls.verify_hostname) (#1393)

* tls: Add a description for tls.verify_hostname parameter

Signed-off-by: Hiroshi Hatake <[email protected]>

* filter_kubernetes: Add a description for tls.verify_hostname

Signed-off-by: Hiroshi Hatake <[email protected]>

* Address comments

Co-authored-by: Pat <[email protected]>
Signed-off-by: Hiroshi Hatake <[email protected]>

---------

Signed-off-by: Hiroshi Hatake <[email protected]>
Co-authored-by: Pat <[email protected]>

Author: cosmo0920

administration/transport-security.md

@@ -9,6 +9,7 @@ Both input and output plugins that perform Network I/O can optionally enable TLS
 | :--- | :--- | :--- |
 | tls | enable or disable TLS support | Off |
 | tls.verify | force certificate validation | On |
+| tls.verify\_hostname | force TLS verification of hostnames | Off |
 | tls.debug | Set TLS debug verbosity level. It accept the following values: 0 \(No debug\), 1 \(Error\), 2 \(State change\), 3 \(Informational\) and 4 Verbose | 1 |
 | tls.ca\_file | absolute path to CA certificate file |  |
 | tls.ca\_path | absolute path to scan for certificate files |  |
@@ -171,3 +172,42 @@ Fluent Bit supports [TLS server name indication](https://en.wikipedia.org/wiki/S
     tls.ca_file /etc/certs/fluent.crt
     tls.vhost   fluent.example.com
 ```
+
+### Verify subjectAltName
+
+By default, TLS verification of hostnames is not done automatically.
+As an example, we can extract the X509v3 Subject Alternative Name from a certificate:
+
+```
+X509v3 Subject Alternative Name:
+    DNS:my.fluent-aggregator.net
+```
+
+As you can see, this certificate covers only `my.fluent-aggregator.net` so if we use a different hostname it should fail.
+
+To fully verify the alternative name and demonstrate the failure we enable `tls.verify_hostname`:
+
+
+```text
+[INPUT]
+    Name  cpu
+    Tag   cpu
+
+[OUTPUT]
+    Name                forward
+    Match               *
+    Host                other.fluent-aggregator.net
+    Port                24224
+    tls                 On
+    tls.verify          On
+    tls.verify_hostname on
+    tls.ca_file         /path/to/fluent-x509v3-alt-name.crt
+```
+
+This outgoing connect will be failed and disconnected:
+
+```
+[2024/06/17 16:51:31] [error] [tls] error: unexpected EOF with reason: certificate verify failed
+[2024/06/17 16:51:31] [debug] [upstream] connection #50 failed to other.fluent-aggregator.net:24224
+[2024/06/17 16:51:31] [error] [output:forward:forward.0] no upstream connections available
+```

pipeline/filters/kubernetes.md

@@ -37,6 +37,7 @@ The plugin supports the following configuration parameters:
 | Keep\_Log | When `Keep_Log` is disabled, the `log` field is removed from the incoming message once it has been successfully merged \(`Merge_Log` must be enabled as well\). | On |
 | tls.debug | Debug level between 0 \(nothing\) and 4 \(every detail\). | -1 |
 | tls.verify | When enabled, turns on certificate validation when connecting to the Kubernetes API server. | On |
+| tls.verify\_hostname | When enabled, turns on hostname validation for certificates | Off |
 | Use\_Journal | When enabled, the filter reads logs coming in Journald format. | Off |
 | Cache\_Use\_Docker\_Id | When enabled, metadata will be fetched from K8s when docker\_id is changed. | Off |
 | Regex\_Parser | Set an alternative Parser to process record Tag and extract pod\_name, namespace\_name, container\_name and docker\_id. The parser must be registered in a [parsers file](https://github.com/fluent/fluent-bit/blob/master/conf/parsers.conf) \(refer to parser _filter-kube-test_ as an example\). |  |