TLS Configuration

Secure RabbitMQ connections with TLS encryption and optional client certificates.

Overview

Certificate Requirements

Certificate	Purpose
CA Certificate	Root of trust
Server Certificate	RabbitMQ server identity
Client Certificate	Optional client authentication

Generate Certificates

Create CA

# Create CA directory
mkdir -p /etc/rabbitmq/ssl
cd /etc/rabbitmq/ssl

# Generate CA key
openssl genrsa -out ca.key 4096

# Generate CA certificate
openssl req -x509 -new -nodes \
  -key ca.key \
  -sha256 -days 3650 \
  -out ca.crt \
  -subj "/CN=Mantis RabbitMQ CA/O=Mantis"

Create Server Certificate

# Generate server key
openssl genrsa -out server.key 2048

# Create certificate signing request
openssl req -new \
  -key server.key \
  -out server.csr \
  -subj "/CN=rabbitmq.example.com/O=Mantis"

# Create SAN extension file
cat > server_san.ext << EOF
subjectAltName = @alt_names
[alt_names]
DNS.1 = rabbitmq.example.com
DNS.2 = localhost
IP.1 = 127.0.0.1
EOF

# Sign with CA
openssl x509 -req \
  -in server.csr \
  -CA ca.crt \
  -CAkey ca.key \
  -CAcreateserial \
  -out server.crt \
  -days 365 \
  -sha256 \
  -extfile server_san.ext

Create Client Certificate (Optional)

# Generate client key
openssl genrsa -out client.key 2048

# Create CSR
openssl req -new \
  -key client.key \
  -out client.csr \
  -subj "/CN=mantis-client/O=Mantis"

# Sign with CA
openssl x509 -req \
  -in client.csr \
  -CA ca.crt \
  -CAkey ca.key \
  -CAcreateserial \
  -out client.crt \
  -days 365 \
  -sha256

Set Permissions

# Secure the keys
chmod 600 /etc/rabbitmq/ssl/*.key
chmod 644 /etc/rabbitmq/ssl/*.crt
chown -R rabbitmq:rabbitmq /etc/rabbitmq/ssl

RabbitMQ TLS Configuration

Basic TLS

# Disable plain TCP listener (recommended for production)
# listeners.tcp = none

# Enable TLS listener
listeners.ssl.default = 5671

# Certificate configuration
ssl_options.cacertfile = /etc/rabbitmq/ssl/ca.crt
ssl_options.certfile = /etc/rabbitmq/ssl/server.crt
ssl_options.keyfile = /etc/rabbitmq/ssl/server.key

# TLS version (require TLS 1.2+)
ssl_options.versions.1 = tlsv1.2
ssl_options.versions.2 = tlsv1.3

# Cipher suites
ssl_options.ciphers.1 = TLS_AES_256_GCM_SHA384
ssl_options.ciphers.2 = TLS_AES_128_GCM_SHA256
ssl_options.ciphers.3 = ECDHE-RSA-AES256-GCM-SHA384
ssl_options.ciphers.4 = ECDHE-RSA-AES128-GCM-SHA256

# Honor server cipher preference
ssl_options.honor_cipher_order = true
ssl_options.honor_ecc_order = true

Client Certificate Verification

# Require client certificates
ssl_options.verify = verify_peer
ssl_options.fail_if_no_peer_cert = true

# Depth of certificate chain verification
ssl_options.depth = 2

Both TCP and TLS

For migration or internal/external separation:

# TCP on localhost only
listeners.tcp.local = 127.0.0.1:5672

# TLS on all interfaces
listeners.ssl.default = 5671

Management UI TLS

Enable HTTPS

# Disable HTTP
management.tcp.port = 0

# Enable HTTPS
management.ssl.port = 15671
management.ssl.cacertfile = /etc/rabbitmq/ssl/ca.crt
management.ssl.certfile = /etc/rabbitmq/ssl/server.crt
management.ssl.keyfile = /etc/rabbitmq/ssl/server.key

Thorax Configuration

TLS Connection

[queue]
enabled = true
host = "rabbitmq.example.com"
port = 5671
username = "mantis"
password = "password"
ca_cert_path = "/etc/mantis/certs/rabbitmq-ca.crt"
prefetch_count = 10

With Client Certificate

[queue]
enabled = true
host = "rabbitmq.example.com"
port = 5671
username = "mantis"
password = "password"
ca_cert_path = "/etc/mantis/certs/ca.crt"
client_cert_path = "/etc/mantis/certs/client.crt"
client_key_path = "/etc/mantis/certs/client.key"

Environment Variables

THORAX__QUEUE__HOST="rabbitmq.example.com"
THORAX__QUEUE__PORT=5671
THORAX__QUEUE__USERNAME="mantis"
THORAX__QUEUE__CA_CERT_PATH="/etc/mantis/certs/ca.crt"

Mandible Configuration

Mandible publishes commands to RabbitMQ and uses the same [queue] settings block with the MANDIBLE__ env var prefix.

TLS Connection

[queue]
enabled = true
host = "rabbitmq.example.com"
port = 5671
username = "mantis"
password = "password"
ca_cert_path = "/etc/mantis/certs/rabbitmq-ca.crt"

With Client Certificate

[queue]
enabled = true
host = "rabbitmq.example.com"
port = 5671
username = "mantis"
password = "password"
ca_cert_path = "/etc/mantis/certs/ca.crt"
client_cert_path = "/etc/mantis/certs/client.crt"
client_key_path = "/etc/mantis/certs/client.key"

Environment Variables

MANDIBLE__QUEUE__HOST="rabbitmq.example.com"
MANDIBLE__QUEUE__PORT=5671
MANDIBLE__QUEUE__USERNAME="mantis"
MANDIBLE__QUEUE__CA_CERT_PATH="/etc/mantis/certs/ca.crt"

Docker Configuration

Docker Compose

services:
  rabbitmq:
    image: rabbitmq:3.13-management-alpine
    hostname: rabbitmq
    volumes:
      - ./ssl/ca.crt:/etc/rabbitmq/ssl/ca.crt:ro
      - ./ssl/server.crt:/etc/rabbitmq/ssl/server.crt:ro
      - ./ssl/server.key:/etc/rabbitmq/ssl/server.key:ro
      - ./rabbitmq.conf:/etc/rabbitmq/rabbitmq.conf:ro
    ports:
      - '5671:5671' # AMQPS
      - '15671:15671' # Management HTTPS

Kubernetes Secret

apiVersion: v1
kind: Secret
metadata:
  name: rabbitmq-tls
type: Opaque
data:
  ca.crt: <base64-encoded-ca>
  server.crt: <base64-encoded-cert>
  server.key: <base64-encoded-key>

Verification

Test TLS Connection

# Using OpenSSL
openssl s_client -connect rabbitmq.example.com:5671 \
  -CAfile /etc/mantis/certs/ca.crt \
  -showcerts

# Check certificate
openssl s_client -connect rabbitmq.example.com:5671 \
  -CAfile /etc/mantis/certs/ca.crt \
  </dev/null 2>/dev/null | openssl x509 -text -noout

Test AMQPS Connection

# Using amqp-tools
amqp-declare-queue \
  --url="amqps://mantis:password@rabbitmq.example.com:5671" \
  --cacert=/etc/mantis/certs/ca.crt \
  --queue=test

# Using Python
python3 -c "
import ssl
import pika

context = ssl.create_default_context(cafile='/etc/mantis/certs/ca.crt')
params = pika.ConnectionParameters(
    host='rabbitmq.example.com',
    port=5671,
    credentials=pika.PlainCredentials('mantis', 'password'),
    ssl_options=pika.SSLOptions(context)
)
connection = pika.BlockingConnection(params)
print('Connected successfully')
connection.close()
"

Check RabbitMQ TLS Status

# List TLS listeners
sudo rabbitmqctl eval 'rabbit_networking:active_listeners().'

# Check connection TLS info
sudo rabbitmqctl list_connections name ssl ssl_protocol ssl_cipher

Certificate Renewal

Automated Renewal

#!/bin/bash
SSL_DIR="/etc/rabbitmq/ssl"
DAYS_BEFORE_EXPIRY=30

# Check if certificate needs renewal
EXPIRY=$(openssl x509 -enddate -noout -in $SSL_DIR/server.crt | cut -d= -f2)
EXPIRY_EPOCH=$(date -d "$EXPIRY" +%s)
NOW_EPOCH=$(date +%s)
DAYS_LEFT=$(( ($EXPIRY_EPOCH - $NOW_EPOCH) / 86400 ))

if [ $DAYS_LEFT -lt $DAYS_BEFORE_EXPIRY ]; then
    echo "Certificate expires in $DAYS_LEFT days, renewing..."

    # Generate new certificate
    openssl req -new -key $SSL_DIR/server.key -out $SSL_DIR/server.csr \
        -subj "/CN=rabbitmq.example.com/O=Mantis"

    openssl x509 -req -in $SSL_DIR/server.csr \
        -CA $SSL_DIR/ca.crt -CAkey $SSL_DIR/ca.key \
        -CAcreateserial -out $SSL_DIR/server.crt \
        -days 365 -sha256 -extfile $SSL_DIR/server_san.ext

    # Reload RabbitMQ
    sudo systemctl reload rabbitmq-server

    echo "Certificate renewed successfully"
else
    echo "Certificate valid for $DAYS_LEFT more days"
fi

Schedule Renewal

# Weekly check
0 0 * * 0 /opt/mantis/scripts/renew-rabbitmq-certs.sh >> /var/log/rabbitmq/cert-renewal.log 2>&1

Troubleshooting

TLS Handshake Failed

Error: TLS handshake failed

Causes:

Certificate hostname mismatch
Expired certificate
CA certificate not trusted

Solutions:

Verify SAN includes hostname: openssl x509 -in server.crt -text | grep DNS
Check expiry: openssl x509 -in server.crt -enddate -noout
Verify CA is correct

Certificate Verification Failed

Error: certificate verify failed

Solutions:

Ensure CA certificate is correct
Check certificate chain is complete
Verify verify_peer settings match on both sides

Connection Reset

Error: connection reset by peer

Causes:

TLS version mismatch
Cipher suite incompatibility

Solutions:

Check TLS versions match
Verify cipher suites are compatible

Next Steps

Queue Topology - Queue configuration
Monitoring - RabbitMQ monitoring
RabbitMQ Setup - Initial setup