RabbitMQ Message Broker

Synopsis #

RabbitMQ is a message broker that implements the AMQP (Advanced Message Queuing Protocol). It is used to decouple services and distribute tasks using queues, topics, and publish-subscribe mechanisms.

RabbitMQ supports persistent queues, acknowledgements, clustering, TLS encryption, and various plugins including web-based management.

RabbitMQ is available on OpenBSD via the packages system. It runs on top of the Erlang runtime and communicates over TCP (AMQP by default on port 5672, and optionally HTTPS on port 15671 for management).

Installation #

Install both RabbitMQ and its Erlang runtime dependencies:

doas pkg_add rabbitmq

This installs:

  • rabbitmq-server: the main daemon
  • rabbitmqctl: administrative CLI
  • rabbitmq-plugins: plugin management utility
  • Default config directory: /etc/rabbitmq/

RabbitMQ will refuse to run without a writable data directory.

Service Initialization #

The RabbitMQ service must be initialized before starting:

doas install -d -o _rabbitmq -g _rabbitmq /var/rabbitmq

Enable and start the service:

doas rcctl enable rabbitmq
doas rcctl start rabbitmq

Before using CLI tools for the first time, wait for the broker to create its private Erlang cookie. Running a CLI tool as root too early can create a cookie that _rabbitmq cannot read:

doas sh <<'ROOT'
set -eu
cookie=/var/rabbitmq/.erlang.cookie
uid=$(id -u _rabbitmq)
n=0
while :; do
 if test -f "$cookie" && test ! -L "$cookie" &&
    test "$(stat -f %l "$cookie")" = 1 &&
    test "$(stat -f %u "$cookie")" = "$uid" &&
    { test "$(stat -f %Lp "$cookie")" = 400 || test "$(stat -f %Lp "$cookie")" = 600; } &&
    test "$(stat -f %z "$cookie")" -gt 0; then break; fi
 n=$((n+1)); test "$n" -le 60; sleep 1
done
rabbitmqctl -t 60 await_startup
rabbitmqctl status
ROOT

If /var/rabbitmq/.erlang.cookie is root-owned, stop the service, set its owner to _rabbitmq:_rabbitmq and mode to 0400, then restart. Preserve the cookie contents and keep them private.

See the RabbitMQ CLI shared-secret seeding guidance for the first-start race.

By default, the daemon listens on:

  • TCP port 5672 (AMQP)
  • TCP port 25672 (Erlang distribution for clustering and administrative CLI communication)

Configuration #

RabbitMQ uses a directory-based config under /etc/rabbitmq/.

There are two main files:

  • /etc/rabbitmq/rabbitmq-env.conf: shell environment overrides
  • /etc/rabbitmq/rabbitmq.conf: main configuration file (in INI-style format)

Example /etc/rabbitmq/rabbitmq.conf:

# Preserve the default guest loopback restriction

# Default listener
listeners.tcp.default = 127.0.0.1:5672

# Enable TLS
# listeners.ssl.default = 0.0.0.0:5671
# ssl_options.certfile = /etc/ssl/rabbitmq/server.crt
# ssl_options.keyfile = /etc/ssl/rabbitmq/server.key
# ssl_options.cacertfile = /etc/ssl/rabbitmq/ca.crt

Restart RabbitMQ after configuration changes:

doas rcctl restart rabbitmq

User and Access Control #

To create a new user and virtual host:

doas rabbitmqctl add_user myuser secretpass
doas rabbitmqctl add_vhost myvhost
doas rabbitmqctl set_permissions -p myvhost myuser ".*" ".*" ".*"

Disable the default guest user for security:

doas rabbitmqctl delete_user guest

List users and vhosts:

doas rabbitmqctl list_users
doas rabbitmqctl list_vhosts

Web-Based Management Plugin #

To enable the RabbitMQ management interface:

doas rabbitmq-plugins enable rabbitmq_management
doas rcctl restart rabbitmq

This exposes:

  • Port 15672: web UI (HTTP)
  • Port 15671: web UI (HTTPS, if TLS is configured)

Access it at http://localhost:15672 using a user with an appropriate management tag and permissions.

Create an admin user:

doas rabbitmqctl add_user adminuser strongpass
doas rabbitmqctl set_user_tags adminuser administrator

Management HTTPS requires separate management.ssl settings; AMQP TLS below does not enable HTTPS on port 15671. Restrict the management listener to the administration network or loopback.

TLS Support #

To enable TLS, add to /etc/rabbitmq/rabbitmq.conf:

listeners.ssl.default = 0.0.0.0:5671
ssl_options.certfile = /etc/ssl/rabbitmq/server.crt
ssl_options.keyfile = /etc/ssl/rabbitmq/server.key
ssl_options.cacertfile = /etc/ssl/rabbitmq/ca.crt
ssl_options.verify = verify_peer
ssl_options.fail_if_no_peer_cert = true

Ensure correct permissions:

doas sh -c 'chown _rabbitmq:_rabbitmq /etc/ssl/rabbitmq/*'
doas sh -c 'chmod 640 /etc/ssl/rabbitmq/*'

Then restart:

doas rcctl restart rabbitmq

Firewall Configuration #

If running outside localhost, allow ports through pf.conf:

int_if = "em1"
table <trusted_nets> { 192.0.2.0/24 }
pass in on $int_if inet proto tcp from <trusted_nets> to ($int_if) port { 5672 5671 15672 }

Avoid exposing RabbitMQ to untrusted networks unless TLS is enabled.

Service Management #

Standard service control:

doas rcctl enable rabbitmq
doas rcctl start rabbitmq
doas rcctl check rabbitmq
doas rcctl restart rabbitmq

Check runtime info:

doas rabbitmqctl status
doas rabbitmqctl list_queues
doas rabbitmqctl list_connections

Inspecting Connection Protocols #

The list_connections command accepts connection fields as positional arguments. The output columns follow the same order as the arguments. To display only the negotiated AMQP protocol version:

doas rabbitmqctl list_connections protocol

For a more useful connection inventory, include the connection name, authenticated user, client address, server listener, protocol, TLS state, and connection state:

doas rabbitmqctl list_connections name user peer_host peer_port port protocol ssl state

The protocol field reports {0,9,1} for AMQP 0-9-1 and {0,8,0} for AMQP 0-8. RabbitMQ treats an AMQP 0-9 request as AMQP 0-9-1. The port field is the server-side listener port. The peer_host and peer_port fields identify the client endpoint.

The ssl field reports whether TLS protects the connection. Add ssl_protocol when the negotiated TLS version is also required:

doas rabbitmqctl list_connections name protocol ssl ssl_protocol

OpenBSD 8.0 packages RabbitMQ 4.3.6, where AMQP 1.0 support is built in. Use rabbitmqctl list_amqp10_connections for AMQP 1.0 connections; no AMQP 1.0 plugin activation is needed.

Logging #

RabbitMQ logs are written to:

/var/log/rabbitmq/

Use tail -f to follow log output:

doas tail -f /var/log/rabbitmq/rabbit@localhost.log
Report a bug