AMQPS (TLS)
LavinMQ supports TLS 1.2 and 1.3 for AMQPS, MQTTS and HTTPS.
If a valid certificate and key are configured, LavinMQ will listen on port 5671
for AMQPS, port 8883 for MQTTS and port 15671 for HTTPS.
The certificate and key are configured in the [main] section of lavinmq.ini:
Config
[main]
tls_cert = /etc/lavinmq/cert.pem
tls_key = /etc/lavinmq/key.pem
tls_min_version = 1.2
[amqp]
tls_port = 5671
[mqtt]
tls_port = 8883
[mgmt]
tls_port = 15671
Reloading certificates
Send a HUP signal to reload certificates if the files have changed, e.g. after renewal.
Existing connections will not be interrupted, and new TLS connections will be
served the new certificate. LavinMQ also reloads SNI host certificates.
TLS SNI (Server Name Indication)
LavinMQ supports TLS Server Name Indication (SNI), allowing you to serve different certificates based on the hostname the client connects to. This is useful when a single LavinMQ instance serves multiple domains.
SNI hosts are configured in lavinmq.ini using [sni:hostname] sections. Each section must include at least a tls_cert. You can also use wildcard hostnames (e.g. *.example.com).
When a client connects, LavinMQ matches the requested hostname against configured SNI hosts - first by exact match, then by wildcard suffix. If no match is found, the default certificate from [main] is used.
Per-protocol overrides
Each SNI host inherits default TLS settings (tls_cert, tls_key, tls_min_version, tls_ciphers) that apply to all protocols. You can override these for individual protocols by prefixing the setting with amqp_, mqtt_, or http_.
Example
[main]
tls_cert = /etc/lavinmq/default-cert.pem
tls_key = /etc/lavinmq/default-key.pem
[sni:app.example.com]
tls_cert = /etc/lavinmq/app-cert.pem
tls_key = /etc/lavinmq/app-key.pem
[sni:*.internal.example.com]
tls_cert = /etc/lavinmq/internal-cert.pem
tls_key = /etc/lavinmq/internal-key.pem
tls_min_version = 1.3
; Use a different certificate for MQTT on this host
mqtt_tls_cert = /etc/lavinmq/internal-mqtt-cert.pem
mqtt_tls_key = /etc/lavinmq/internal-mqtt-key.pem
SNI configuration reference
The following settings are available in each [sni:hostname] section. All settings except tls_cert are optional.
| Setting | Description |
|---|---|
| tls_cert | TLS certificate (including chain). Required. |
| tls_key | Private key for the certificate. Defaults to the cert file if not set. |
| tls_min_version | Minimum TLS version (1.0, 1.1, 1.2 or 1.3). |
| tls_ciphers | List of allowed TLS ciphers. |
| tls_verify_peer | Enable client certificate verification (mTLS). See the mTLS section below. |
| tls_ca_cert | CA certificate file or directory for verifying client certificates. |
| tls_keylog_file | Path to write TLS session keys for debugging. See the keylog section below. |
Each of the settings above can be overridden per protocol by prefixing with amqp_, mqtt_, or http_ (e.g. amqp_tls_cert, mqtt_tls_verify_peer).
mTLS (Mutual TLS)
Mutual TLS (mTLS) requires clients to present a valid certificate during the TLS handshake, enabling two-way authentication. In LavinMQ, mTLS is configured per SNI host.
To enable mTLS, set tls_verify_peer = true and provide a CA certificate (or directory of CA certificates) to verify client certificates against:
[sni:secure.example.com]
tls_cert = /etc/lavinmq/server-cert.pem
tls_key = /etc/lavinmq/server-key.pem
tls_verify_peer = true
tls_ca_cert = /etc/lavinmq/ca-cert.pem
When tls_verify_peer is enabled, LavinMQ rejects clients that do not present a valid certificate signed by the specified CA. The tls_ca_cert setting accepts either a file path to a CA certificate or a directory path containing multiple CA certificates.
mTLS can also be configured per protocol using the prefixed variants (e.g. amqp_tls_verify_peer, mqtt_tls_ca_cert).
kTLS (Kernel TLS offloading)
LavinMQ can offload TLS encryption to the Linux kernel, improving performance by avoiding data copies between kernel and user space. When kTLS is active, the kernel performs TLS encryption and decryption directly on the socket.
Configuration
[main]
tls_ktls = true
Or via the command line:
lavinmq --tls-ktls=true
LavinMQ logs the kTLS status for each connection (e.g. kTLS=send+recv). If the kernel tls module is not loaded, LavinMQ will log a warning at startup and TLS will fall back to user-space encryption.
TLS keylog file
For debugging TLS-encrypted traffic (e.g. with Wireshark), LavinMQ can write TLS session keys to a log file. You can then use these keys to decrypt captured traffic without access to the server’s private key.
Configuration
Set the keylog file path in lavinmq.ini:
[main]
tls_keylog_file = /tmp/sslkeys.log
Alternatively, set the SSLKEYLOGFILE environment variable. If both are set, the config file setting takes precedence.
You can also configure the keylog file per SNI host using tls_keylog_file in [sni:hostname] sections, with per-protocol overrides (e.g. amqp_tls_keylog_file).
Warning: The keylog file contains sensitive data that anyone can use to decrypt TLS traffic. Only enable this in development or debugging environments.
Ready to take the next steps?
Managed LavinMQ instance via CloudAMQP
LavinMQ has been built with performance and ease of use in mind - we've benchmarked a throughput of about 1,000,000 messages/sec . You can try LavinMQ without any installation hassle by creating a free instance on CloudAMQP. Signing up is a breeze.
Get started with CloudAMQP ->
Help and feedback
We welcome your feedback and are eager to address any questions you may have about this piece or using LavinMQ. Join our Slack channel to connect with us directly. You can also find LavinMQ on GitHub.