TLS
Fluent Bit provides integrated support for Transport Layer Security (TLS) and its predecessor Secure Sockets Layer (SSL). This section refers only to TLS for both implementations.
Fluent Bit 4.1.0 introduced the replacement of Next Protocol Negotiation (NPN) with Application Layer Protocol Negotiation (ALPN) as its implementation for TLS. Both NPN and ALPN are used when client and server are establishing SSL/TLS connections. ALPN avoids an additional round trip because the client list the application layer protocols supported by the client in the client hello message.
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:
tls
Enable or disable TLS support.
off
tls.debug
Set TLS debug verbosity level. Accepted values: 0 (No debug), 1 (Error), 2 (State change), 3 (Informational) and 4 (Verbose).
1
tls.ca_file
Absolute path to CA certificate file.
none
tls.ca_path
Absolute path to scan for certificate files.
none
tls.ciphers
Specify TLS ciphers up to TLSv1.2.
none
tls.crt_file
Absolute path to Certificate file.
none
tls.key_file
Absolute path to private Key file.
none
tls.key_passwd
Optional password for tls.key_file file.
none
tls.max_version
Specify the maximum version of TLS.
none
tls.min_version
Specify the minimum version of TLS.
none
tls.proxy.ca_file
Absolute path to the CA certificate file used to verify the HTTPS proxy's certificate. Independent from tls.ca_file, which verifies the destination's certificate. Only applies to output plugins connecting through an HTTPS proxy. See HTTP proxy. Supported in v5.1 or later.
none
tls.proxy.ca_path
Absolute path to scan for CA certificate files used to verify the HTTPS proxy's certificate. Only applies to output plugins connecting through an HTTPS proxy. Supported in v5.1 or later.
none
tls.proxy.verify
Force certificate validation for the HTTPS proxy connection. Only applies to output plugins connecting through an HTTPS proxy. Supported in v5.1 or later.
on
tls.proxy.verify_hostname
Force hostname verification for the HTTPS proxy connection. Only applies to output plugins connecting through an HTTPS proxy. Supported in v5.1 or later.
on
tls.verify
Force certificate validation.
on
tls.vhost
Hostname to be used for TLS SNI extension.
none
tls.verify_hostname
Force TLS verification of host names.
off
tls.verify_client_cert
Require and verify the TLS certificate presented by a connecting client. Enables mutual TLS (mTLS) for input plugins. Only applies to input plugins.
off
When the connection target is an IP address (IPv4 or IPv6), Fluent Bit doesn't include the TLS Server Name Indication (SNI) extension, which is consistent with RFC 6066. Certificate validation still applies against the IP address. If the server requires SNI or uses a hostname-based certificate, use a hostname as the connection target and set tls.vhost if needed.
To use TLS on input plugins, you must provide both a certificate and a private key.
The listed properties can be enabled in the configuration file, specifically in 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 implement a subset of TLS support, with restricted configuration:
Example: enable TLS on HTTP input
By default, the HTTP input plugin uses plain TCP. Run the following command to enable TLS:
See the Tips and Tricks section for details on generating self_signed.crt and self_signed.key files shown in these examples.
In the previous command, the two properties tls and tls.verify are set for demonstration purposes. Always enable verification in production environments.
The same behavior can be accomplished using a configuration file:
Example: enable TLS on HTTP output
By default, the HTTP output plugin uses plain TCP. Run the following command to enable TLS:
In the previous command, the properties tls and tls.verify are enabled for demonstration purposes. Always enable verification in production environments.
The same behavior can be accomplished using a configuration file:
Certificate reload
Automatic certificate reload is available in Fluent Bit version 5.1 and greater.
Fluent Bit reloads TLS certificates from disk without a restart or a hot reload. No configuration is required, and there's no reload interval to tune.
Each time Fluent Bit creates a new TLS session, it checks the certificate directory set by tls.ca_path, and the individual certificate and key files set by tls.ca_file, tls.crt_file, and tls.key_file. If any of them changed, Fluent Bit builds a new TLS context from disk and uses it for that session and the sessions that follow. This applies to both directions: output plugins connecting to a remote server, and input plugins accepting incoming connections.
For each of these paths, Fluent Bit compares whether the path exists, its size, and its modification and change timestamps. On Linux it also compares the device and inode numbers, and uses nanosecond timestamp precision. The inode comparison matters in practice. It detects a certificate replaced by renaming a new file over the old one, along with the symlink swap that Kubernetes performs when a mounted secret is updated.
For tls.ca_path, Fluent Bit inspects the directory itself rather than each certificate inside it. This detects certificates added to, removed from, or renamed within the directory, because those operations change the directory's own timestamps. A certificate file that's modified in place inside that directory doesn't trigger a reload. To have such an update detected, replace the file by renaming a new one over it, or reference it directly with tls.ca_file.
Sessions that are already established keep the context they were created with. A long-lived connection continues to use the previous certificate until it's reconnected.
If the new files can't be loaded, for example because a certificate and key were written separately and Fluent Bit read them mid-update, it logs detected certificate file changes but reload failed and keeps the previous context. Connections continue to work with the certificate that was already loaded, and the next session retries the reload.
Tips and tricks
Generate a self-signed certificates for testing purposes
The following command generates a 4096-bit RSA key pair and a certificate that's signed using SHA-256 with the expiration date set to 30 days in the future. In this example, test.host.net is set as the common name. This example opts out of DES, so the private key is stored in plain text.
Connect to virtual servers using TLS
Fluent Bit supports TLS server name indication. If you are serving multiple host names on a single IP address (for example, using virtual hosting), you can make use of tls.vhost to connect to a specific hostname.
Verify subjectAltName
By default, TLS verification of host names isn't done automatically. As an example, you can extract the X509v3 Subject Alternative Name from a certificate:
This certificate covers only my.fluent-aggregator.net so if you use a different hostname it should fail.
To fully verify the alternative name and demonstrate the failure, enable tls.verify_hostname:
This outgoing connect will fail and disconnect:
Last updated
Was this helpful?