Transport Security

Fluent Bit provides integrated support for Transport Layer Security (TLS) and it predecessor Secure Sockets Layer (SSL) respectively. In this section we will refer as TLS only for both implementations.

Both input and output plugins that perform Network I/O can optionally enable TLS and configure the behavior. The following table describes the properties available:

PropertyDescriptionDefault

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

tls.crt_file

absolute path to Certificate file

tls.key_file

absolute path to private Key file

tls.key_passwd

optional password for tls.key_file file

tls.vhost

hostname to be used for TLS SNI extension

Note : in order to use TLS on input plugins the user is expected to provide both a certificate and private key

The listed properties can be enabled in the configuration file, specifically on each output plugin section or directly through the command line.

The following output plugins can take advantage of the TLS feature:

The following input plugins can take advantage of the TLS feature:

In addition, other plugins implements a sub-set of TLS support, meaning, with restricted configuration:

Example: enable TLS on HTTP input

By default HTTP input plugin uses plain TCP, enabling TLS from the command line can be done with:

./bin/fluent-bit -i http \
           -p port=9999 \
           -p tls=on \
           -p tls.verify=off \
           -p tls.crt_file=self_signed.crt \
           -p tls.key_file=self_signed.key \
           -o stdout \
           -m '*'

In the command line above, the two properties tls and tls.verify where enabled for demonstration purposes (we strongly suggest always keep verification ON).

The same behavior can be accomplished using a configuration file:

[INPUT]
    name http
    port 9999
    tls on
    tls.verify off
    tls.crt_file self_signed.crt
    tls.key_file self_signed.key

[OUTPUT]
    Name       stdout
    Match      *

Example: enable TLS on HTTP output

By default HTTP output plugin uses plain TCP, enabling TLS from the command line can be done with:

$ fluent-bit -i cpu -t cpu -o http://192.168.2.3:80/something \
    -p tls=on         \
    -p tls.verify=off \
    -m '*'

In the command line above, the two properties tls and tls.verify where enabled for demonstration purposes (we strongly suggest always keep verification ON).

The same behavior can be accomplished using a configuration file:

[INPUT]
    Name  cpu
    Tag   cpu

[OUTPUT]
    Name       http
    Match      *
    Host       192.168.2.3
    Port       80
    URI        /something
    tls        On
    tls.verify Off

Tips and Tricks

Generate your own self signed certificates for testing purposes.

This will generate a 4096 bit RSA key pair and a certificate that is signed using SHA-256 with the expiration date set to 30 days in the future, test.host.net set as common name and since we opted out of DES the private key will be stored in plain text.

openssl req -x509 \
            -newkey rsa:4096 \
            -sha256 \
            -nodes \
            -keyout self_signed.key \
            -out self_signed.crt \
            -subj "/CN=test.host.net"

Connect to virtual servers using TLS

Fluent Bit supports TLS server name indication. If you are serving multiple hostnames on a single IP address (a.k.a. virtual hosting), you can make use of tls.vhost to connect to a specific hostname.

[INPUT]
    Name  cpu
    Tag   cpu

[OUTPUT]
    Name        forward
    Match       *
    Host        192.168.10.100
    Port        24224
    tls         On
    tls.verify  On
    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:

[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

Last updated