Over 10 years we help companies reach their financial and branding goals. Engitech is a values-driven technology agency dedicated.

Gallery

Contacts

411 University St, Seattle, USA

+1 -800-456-478-23

How to install RabbitMQ on Debian 13 with Cluster Support

This guide installs RabbitMQ on Debian 13 (Trixie) using the official Team RabbitMQ APT repositories and covers:

  • Single-node installation
  • RabbitMQ Management UI
  • Users and virtual hosts
  • 3-node RabbitMQ cluster
  • Quorum queues for high availability
  • Firewall configuration
  • Client connection strategy
  • Basic monitoring and troubleshooting

RabbitMQ officially supports Debian 13 Trixie and recommends using Team RabbitMQ's own APT repositories instead of Debian's built-in rabbitmq-server package, because distribution packages can lag behind supported RabbitMQ releases. (RabbitMQ)


Architecture

A recommended small production cluster:

                      Applications
                           │
                           │ AMQP :5672
                           ▼
                  Load Balancer / DNS
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼

        ┌───────────┐ ┌───────────┐ ┌───────────┐
        │ rabbit-01 │ │ rabbit-02 │ │ rabbit-03 │
        │           │ │           │ │           │
        │10.10.10.21│ │10.10.10.22│ │10.10.10.23│
        └─────┬─────┘ └─────┬─────┘ └─────┬─────┘
              │             │             │
              └─────────────┼─────────────┘
                            │
                 RabbitMQ Cluster Traffic
                  4369 / 25672 TCP

Management UI:

http://rabbit-01:15672

AMQP clients:

amqp://rabbit-01:5672
amqp://rabbit-02:5672
amqp://rabbit-03:5672

RabbitMQ recommends odd-numbered clusters such as 3, 5, or 7 nodes for consensus-based features such as quorum queues; two-node clusters are strongly discouraged. (RabbitMQ)


System Requirements

Operating System

Debian 13 (Trixie)
64-bit

Debian 13 is currently listed as a supported Debian distribution by RabbitMQ. (RabbitMQ)

Practical Starting Point

For a small production node:

CPU:       2-4 cores+
RAM:       4-8 GB+
Storage:   40 GB+ SSD
Network:   1 Gbps+

For queue-heavy workloads:

CPU:       4-8+ cores
RAM:       8-32 GB+
Storage:   Fast SSD / NVMe
Network:   1-10 Gbps

Actual sizing depends mainly on message rate, queue depth, message size, number of connections, retention, and replication.

For quorum queues, fast disks are particularly important because quorum queues persist their replicated log to disk. (RabbitMQ)


Required Network Ports

RabbitMQ commonly uses:

Port Purpose
4369/TCP Erlang epmd peer discovery
5672/TCP AMQP
5671/TCP AMQP over TLS
15672/TCP Management UI / HTTP API
15671/TCP Management UI over TLS
25672/TCP RabbitMQ inter-node communication
35672-35682/TCP RabbitMQ CLI tools

RabbitMQ documents 4369 and 25672 as important inter-node ports, 5672/5671 for AMQP clients, and 15672/15671 for the Management UI and HTTP API. (RabbitMQ)

For a normal cluster, keep:

4369
25672

restricted to the RabbitMQ network.


Example Cluster

This guide uses:

Node Hostname IP
Node 1 rabbit-01 10.10.10.21
Node 2 rabbit-02 10.10.10.22
Node 3 rabbit-03 10.10.10.23

1. Configure Hostnames

On node 1:

sudo hostnamectl set-hostname rabbit-01

Node 2:

sudo hostnamectl set-hostname rabbit-02

Node 3:

sudo hostnamectl set-hostname rabbit-03

Verify:

hostname

RabbitMQ node names normally use the form:

rabbit@hostname

Therefore these hosts will become:

rabbit@rabbit-01
rabbit@rabbit-02
rabbit@rabbit-03

2. Configure DNS or /etc/hosts

All cluster nodes must resolve one another reliably.

If internal DNS is unavailable:

sudo nano /etc/hosts

Add on every RabbitMQ node:

10.10.10.21 rabbit-01
10.10.10.22 rabbit-02
10.10.10.23 rabbit-03

Test:

getent hosts rabbit-01
getent hosts rabbit-02
getent hosts rabbit-03

Hostname resolution is a prerequisite for RabbitMQ inter-node communication. (RabbitMQ)


3. Install RabbitMQ

Run the following on every RabbitMQ node.

RabbitMQ recommends installing from Team RabbitMQ's repositories rather than Debian's standard RabbitMQ package. (RabbitMQ)

Install prerequisites:

sudo apt-get update

sudo apt-get install -y \
    curl \
    gnupg \
    apt-transport-https

Add the Team RabbitMQ signing key:

curl -1sLf \
    "https://keys.openpgp.org/vks/v1/by-fingerprint/0A9AF2115F4687BD29803A206B73A36E6026DFCA" |
sudo gpg --dearmor |
sudo tee /usr/share/keyrings/com.rabbitmq.team.gpg > /dev/null

For Debian 13 Trixie on amd64, RabbitMQ's current official quick-start documentation uses the Team RabbitMQ Noble repositories for modern Erlang and RabbitMQ packages. (RabbitMQ)

Create:

sudo nano /etc/apt/sources.list.d/rabbitmq.list

Add:

deb [arch=amd64 signed-by=/usr/share/keyrings/com.rabbitmq.team.gpg] https://deb1.rabbitmq.com/rabbitmq-erlang/ubuntu/noble noble main
deb [arch=amd64 signed-by=/usr/share/keyrings/com.rabbitmq.team.gpg] https://deb2.rabbitmq.com/rabbitmq-erlang/ubuntu/noble noble main

deb [arch=amd64 signed-by=/usr/share/keyrings/com.rabbitmq.team.gpg] https://deb1.rabbitmq.com/rabbitmq-server/ubuntu/noble noble main
deb [arch=amd64 signed-by=/usr/share/keyrings/com.rabbitmq.team.gpg] https://deb2.rabbitmq.com/rabbitmq-server/ubuntu/noble noble main

Update:

sudo apt-get update

Install Erlang:

sudo apt-get install -y \
    erlang-base \
    erlang-asn1 \
    erlang-crypto \
    erlang-eldap \
    erlang-ftp \
    erlang-inets \
    erlang-mnesia \
    erlang-os-mon \
    erlang-parsetools \
    erlang-public-key \
    erlang-runtime-tools \
    erlang-snmp \
    erlang-ssl \
    erlang-syntax-tools \
    erlang-tftp \
    erlang-tools \
    erlang-xmerl

Install RabbitMQ:

sudo apt-get install -y rabbitmq-server --fix-missing

This follows RabbitMQ's current Debian/Trixie installation procedure. (RabbitMQ)

The Team RabbitMQ Erlang repository used by this quick-start path is for amd64. ARM64 systems require the alternative supported Erlang package source documented by RabbitMQ. (RabbitMQ)


4. Enable RabbitMQ

sudo systemctl enable --now rabbitmq-server

Check:

sudo systemctl status rabbitmq-server

Verify the node:

sudo rabbitmq-diagnostics ping

Expected:

Ping succeeded

Check status:

sudo rabbitmqctl status

5. Enable Management UI

Enable the built-in Management plugin:

sudo rabbitmq-plugins enable rabbitmq_management

RabbitMQ's Management plugin is included with the server and does not require a node restart after activation. (RabbitMQ)

Check:

sudo rabbitmq-plugins list

You should see:

[E*] rabbitmq_management

Open:

http://SERVER_IP:15672

Example:

http://10.10.10.21:15672

The Management UI uses port 15672 by default. (RabbitMQ)


6. Create Administrator User

The default guest account is intentionally unsuitable for remote administration.

Create an administrator:

sudo rabbitmqctl add_user admin 'CHANGE_TO_STRONG_PASSWORD'

Grant administrator tag:

sudo rabbitmqctl set_user_tags admin administrator

Grant permissions:

sudo rabbitmqctl set_permissions \
    -p / \
    admin \
    ".*" \
    ".*" \
    ".*"

Login:

http://SERVER_IP:15672

with:

Username: admin
Password: <password>

7. Create Application Virtual Host

Instead of placing applications in the default:

/

create a dedicated vhost.

Example:

sudo rabbitmqctl add_vhost erp

Create application user:

sudo rabbitmqctl add_user erp-app 'CHANGE_TO_STRONG_PASSWORD'

Grant permissions:

sudo rabbitmqctl set_permissions \
    -p erp \
    erp-app \
    ".*" \
    ".*" \
    ".*"

Check:

sudo rabbitmqctl list_vhosts

Users:

sudo rabbitmqctl list_users

Permissions:

sudo rabbitmqctl list_permissions -p erp

Application Connection String

Example:

amqp://erp-app:PASSWORD@rabbit-01:5672/erp

For production applications, configure multiple RabbitMQ nodes or a suitable load-balanced endpoint instead of relying on one broker. RabbitMQ clients can connect to any cluster node, and many client libraries support multiple endpoints for reconnection after node failure. (RabbitMQ)


Single-Node Configuration

Main configuration:

/etc/rabbitmq/rabbitmq.conf

Edit:

sudo nano /etc/rabbitmq/rabbitmq.conf

Example:

listeners.tcp.default = 5672

management.tcp.port = 15672

To bind AMQP only to a particular IP:

listeners.tcp.1 = 10.10.10.21:5672

RabbitMQ supports explicit interface binding with listeners.tcp.*; otherwise 5672 listens on available interfaces by default. (RabbitMQ)

Restart:

sudo systemctl restart rabbitmq-server

3-Node Cluster Setup

Before clustering:

rabbit-01
rabbit-02
rabbit-03

are three independent RabbitMQ brokers.

Check:

sudo rabbitmqctl cluster_status

8. Configure the Erlang Cookie

RabbitMQ nodes authenticate to each other using the Erlang cookie.

On Debian/Linux, the server cookie is normally:

/var/lib/rabbitmq/.erlang.cookie

All nodes in the same RabbitMQ cluster must use the same cookie value. (RabbitMQ)


Get Cookie from Node 1

On:

rabbit-01

run:

sudo cat /var/lib/rabbitmq/.erlang.cookie

Example:

LRMCQXDRZRLJGHPTZXYZ

Do not expose this secret publicly.


Copy Cookie to Node 2 and Node 3

Stop RabbitMQ on node 2:

sudo systemctl stop rabbitmq-server

Replace:

sudo nano /var/lib/rabbitmq/.erlang.cookie

with the exact value from node 1.

Set ownership:

sudo chown rabbitmq:rabbitmq \
    /var/lib/rabbitmq/.erlang.cookie

Permissions:

sudo chmod 400 \
    /var/lib/rabbitmq/.erlang.cookie

Repeat on node 3.

Then:

sudo systemctl start rabbitmq-server

Verify Cookie

On each node:

sudo sha256sum /var/lib/rabbitmq/.erlang.cookie

The hashes should match.

RabbitMQ documentation identifies cookie mismatches as a common cause of inter-node authentication failures. (RabbitMQ)


9. Join Node 2

On:

rabbit-02

run:

sudo rabbitmqctl join_cluster rabbit@rabbit-01

Modern RabbitMQ no longer requires the older:

stop_app
reset
join_cluster
start_app

sequence before joining; starting with RabbitMQ 4.1, join_cluster can perform the join directly. (RabbitMQ)


10. Join Node 3

On:

rabbit-03

run:

sudo rabbitmqctl join_cluster rabbit@rabbit-01

You could also join through another online cluster member:

sudo rabbitmqctl join_cluster rabbit@rabbit-02

A node only needs one reachable member of the existing cluster in order to join that cluster. (RabbitMQ)


11. Verify Cluster

On any node:

sudo rabbitmqctl cluster_status

Expected nodes:

rabbit@rabbit-01
rabbit@rabbit-02
rabbit@rabbit-03

RabbitMQ documents rabbitmqctl cluster_status as the standard way to verify cluster membership. (RabbitMQ)

Also run:

sudo rabbitmq-diagnostics cluster_status

Management UI in Cluster

Enable the Management plugin on each node:

sudo rabbitmq-plugins enable rabbitmq_management

You can then access:

http://rabbit-01:15672
http://rabbit-02:15672
http://rabbit-03:15672

Any cluster node with the Management plugin enabled can return an aggregated cluster view. (RabbitMQ)


Firewall — Cluster Nodes

Assume the RabbitMQ cluster network is:

10.10.10.0/24

Allow EPMD:

sudo ufw allow \
    from 10.10.10.0/24 \
    to any port 4369 \
    proto tcp

Allow RabbitMQ distribution:

sudo ufw allow \
    from 10.10.10.0/24 \
    to any port 25672 \
    proto tcp

RabbitMQ uses these ports for node discovery and inter-node communication. (RabbitMQ)


Allow Application Servers

Suppose:

Application network:
10.10.20.0/24

Allow AMQP:

sudo ufw allow \
    from 10.10.20.0/24 \
    to any port 5672 \
    proto tcp

Allow Management Access

For administrator network:

10.10.30.0/24

allow:

sudo ufw allow \
    from 10.10.30.0/24 \
    to any port 15672 \
    proto tcp

Check:

sudo ufw status

Do Not Publicly Expose Cluster Ports

Do not expose:

4369
25672
35672-35682

to the Internet.

RabbitMQ explicitly recommends keeping inter-node and CLI communication ports private unless there is a specific reason to expose them. (RabbitMQ)


High Availability: Use Quorum Queues

A RabbitMQ cluster alone does not automatically make every queue's messages highly available.

For replicated, highly available queues, use:

Quorum Queues

Quorum queues use the Raft consensus algorithm and are RabbitMQ's recommended queue type when replicated, highly available storage is required. (RabbitMQ)

Classic queue mirroring has been removed from RabbitMQ 4.x. (RabbitMQ)


Quorum Queue Architecture

                    orders.queue
                         │
                   Quorum Queue
                         │
             ┌───────────┼───────────┐
             │           │           │
             ▼           ▼           ▼

          rabbit-01   rabbit-02   rabbit-03

            Leader     Follower     Follower
               │           │           │
               └──── Raft Replication ─┘

With three replicas:

3 members
    ↓
2 required for majority

If one node fails:

2 remain
    ↓
majority still available
    ↓
queue remains operational

Quorum queue operations require a majority of replicas to remain available. (RabbitMQ)


Declare Quorum Queue

Client applications should declare:

x-queue-type = quorum

Example conceptual declaration:

Queue:
orders

Durable:
true

Arguments:
x-queue-type = quorum

Make Quorum the Default Queue Type

For a dedicated application vhost, you can configure the default queue type.

Example:

sudo rabbitmqctl add_vhost erp

Depending on how queues are provisioned in your environment, configure the application to explicitly declare quorum queues rather than relying on classic queues.

For critical production workloads, explicit queue type selection is preferable.


Balance Queue Leaders

RabbitMQ can distribute queue leaders more evenly.

Configure:

sudo nano /etc/rabbitmq/rabbitmq.conf

Add:

queue_leader_locator = balanced

RabbitMQ documents balanced as an available queue leader placement strategy. (RabbitMQ)

Restart nodes one at a time:

sudo systemctl restart rabbitmq-server

Rebalance Existing Quorum Queue Leaders

Run:

sudo rabbitmq-queues rebalance quorum

RabbitMQ provides rabbitmq-queues rebalance quorum specifically for rebalancing quorum queue leaders. (RabbitMQ)


Client High Availability

RabbitMQ clients should not rely exclusively on:

rabbit-01

Prefer:

rabbit-01:5672
rabbit-02:5672
rabbit-03:5672

or a suitable TCP load balancer.

RabbitMQ recommends client libraries reconnect to another cluster node when their current node becomes unavailable. (RabbitMQ)


Option A — Multiple Client Endpoints

Application
    │
    ├── rabbit-01:5672
    ├── rabbit-02:5672
    └── rabbit-03:5672

This is often preferable when the client library has good recovery and endpoint-selection support.


Option B — Load Balancer

Application
     │
     ▼
rabbitmq.internal.example.com:5672
     │
     ▼
Load Balancer
     │
     ├── rabbit-01:5672
     ├── rabbit-02:5672
     └── rabbit-03:5672

Suitable TCP load balancers include:

HAProxy
Nginx Stream
Keepalived + HAProxy
Cloud load balancers

Do not use ordinary HTTP proxying for AMQP traffic.


RabbitMQ Management UI Behind Reverse Proxy

The management interface is HTTP:

http://rabbit-01:15672

It can be placed behind HTTPS:

Internet / Admin Network
          │
          ▼
https://rabbitmq.example.com
          │
          ▼
Reverse Proxy
          │
          ▼
rabbit-01:15672

Keep AMQP traffic separate:

5672 / 5671

The Management UI port does not accept AMQP connections. (RabbitMQ)


TLS / AMQPS

Normal AMQP:

5672

Encrypted AMQP:

5671

RabbitMQ supports disabling plaintext AMQP and exposing only the TLS listener. (RabbitMQ)

Example configuration:

listeners.tcp = none

listeners.ssl.default = 5671

ssl_options.cacertfile = /etc/rabbitmq/certs/ca.pem
ssl_options.certfile   = /etc/rabbitmq/certs/server.pem
ssl_options.keyfile    = /etc/rabbitmq/certs/server-key.pem

ssl_options.verify = verify_peer
ssl_options.fail_if_no_peer_cert = false

Restart:

sudo systemctl restart rabbitmq-server

Check Listeners

sudo rabbitmq-diagnostics listeners

Typical output includes:

5672   AMQP
15672  HTTP
25672  clustering

Check OS listeners:

sudo ss -lntp | grep -E '5672|15672|25672|4369'

Check Cluster Health

sudo rabbitmq-diagnostics ping

Then:

sudo rabbitmqctl cluster_status

Check alarms:

sudo rabbitmq-diagnostics check_local_alarms

Check running status:

sudo rabbitmq-diagnostics check_running

List Queues

sudo rabbitmqctl list_queues

More details:

sudo rabbitmqctl list_queues \
    name \
    type \
    durable \
    messages \
    messages_ready \
    messages_unacknowledged \
    consumers

List Connections

sudo rabbitmqctl list_connections

Useful fields:

sudo rabbitmqctl list_connections \
    user \
    peer_host \
    peer_port \
    state \
    channels

List Channels

sudo rabbitmqctl list_channels

List Exchanges

sudo rabbitmqctl list_exchanges

Service Management

Start:

sudo systemctl start rabbitmq-server

Stop:

sudo systemctl stop rabbitmq-server

Restart:

sudo systemctl restart rabbitmq-server

Enable:

sudo systemctl enable rabbitmq-server

Status:

sudo systemctl status rabbitmq-server

Logs

Check systemd logs:

sudo journalctl -u rabbitmq-server

Follow:

sudo journalctl -u rabbitmq-server -f

RabbitMQ log files are typically under:

/var/log/rabbitmq/

Check:

sudo ls -lah /var/log/rabbitmq/

Data Directory

RabbitMQ's node database and persisted queue data are normally stored under:

/var/lib/rabbitmq/

Do not manually copy live RabbitMQ data directories between arbitrary cluster members as a backup strategy.


Remove a Cluster Node

Suppose:

rabbit-03

must be permanently removed.

On rabbit-03:

sudo rabbitmqctl stop_app

On another member:

sudo rabbitmqctl forget_cluster_node rabbit@rabbit-03

RabbitMQ documents forget_cluster_node for removing a reachable or permanently unavailable node from the cluster. (RabbitMQ)

For quorum queues, make sure queue membership and quorum remain healthy before removing nodes.


Reset Removed Node

If rabbit-03 will become standalone again:

sudo rabbitmqctl stop_app
sudo rabbitmqctl reset
sudo rabbitmqctl start_app

Check:

sudo rabbitmqctl cluster_status

Upgrade Strategy

Do not upgrade every cluster node simultaneously.

Use a supported RabbitMQ rolling or blue/green upgrade procedure and verify Erlang/RabbitMQ compatibility before upgrading.

RabbitMQ publishes dedicated upgrade strategies for supported releases. (RabbitMQ)

For a 3-node cluster, normally work on one node at a time while preserving quorum.


Recommended Production Architecture

                           Applications
                                │
                          AMQP / AMQPS
                                │
                                ▼
                     rabbitmq.internal.local
                                │
                         Load Balancer
                                │
               ┌────────────────┼────────────────┐
               │                │                │
               ▼                ▼                ▼
        ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
        │  rabbit-01  │  │  rabbit-02  │  │  rabbit-03  │
        │             │  │             │  │             │
        │10.10.10.21  │  │10.10.10.22  │  │10.10.10.23  │
        └─────────────┘  └─────────────┘  └─────────────┘
               │                │                │
               └────────────────┼────────────────┘
                                │
                         Quorum Queues
                                │
                       Raft Replication

Management:

Administrators
      │
      ▼
HTTPS
      │
      ▼
RabbitMQ Management UI

Recommended Production Checklist

  • [ ] Use Team RabbitMQ's APT repositories.
  • [ ] Use a RabbitMQ-supported Erlang release.
  • [ ] Use 3 nodes rather than 2 for an HA cluster.
  • [ ] Configure stable hostnames and DNS.
  • [ ] Use the same Erlang cookie on every cluster member.
  • [ ] Keep ports 4369 and 25672 private.
  • [ ] Restrict Management UI access.
  • [ ] Create dedicated application users.
  • [ ] Create application-specific virtual hosts.
  • [ ] Do not use administrator credentials from applications.
  • [ ] Use quorum queues for replicated critical queues.
  • [ ] Prefer SSD/NVMe for quorum queue workloads.
  • [ ] Configure applications with multiple broker endpoints or a TCP load balancer.
  • [ ] Use TLS/AMQPS for untrusted networks.
  • [ ] Monitor memory and disk alarms.
  • [ ] Monitor queue depth and unacknowledged messages.
  • [ ] Maintain quorum during maintenance.
  • [ ] Upgrade cluster nodes gradually.
  • [ ] Back up configuration/definitions and application-critical data appropriately.

Quick Single-Node Setup

Install RabbitMQ using the Team RabbitMQ repository steps above.

Then:

sudo systemctl enable --now rabbitmq-server

sudo rabbitmq-plugins enable rabbitmq_management

Create administrator:

sudo rabbitmqctl add_user admin 'CHANGE_TO_STRONG_PASSWORD'

sudo rabbitmqctl set_user_tags \
    admin \
    administrator

sudo rabbitmqctl set_permissions \
    -p / \
    admin \
    ".*" \
    ".*" \
    ".*"

Open:

http://SERVER_IP:15672

AMQP:

SERVER_IP:5672

Quick 3-Node Cluster Setup

Assume RabbitMQ is already installed on:

rabbit-01
rabbit-02
rabbit-03

Configure /etc/hosts on all nodes:

10.10.10.21 rabbit-01
10.10.10.22 rabbit-02
10.10.10.23 rabbit-03

Copy:

/var/lib/rabbitmq/.erlang.cookie

from rabbit-01 to all nodes.

Set:

sudo chown rabbitmq:rabbitmq \
    /var/lib/rabbitmq/.erlang.cookie

sudo chmod 400 \
    /var/lib/rabbitmq/.erlang.cookie

Restart:

sudo systemctl restart rabbitmq-server

On rabbit-02:

sudo rabbitmqctl join_cluster rabbit@rabbit-01

On rabbit-03:

sudo rabbitmqctl join_cluster rabbit@rabbit-01

Verify:

sudo rabbitmqctl cluster_status

Expected:

rabbit@rabbit-01
rabbit@rabbit-02
rabbit@rabbit-03

Enable Management UI on every node:

sudo rabbitmq-plugins enable rabbitmq_management

Use quorum queues for queues that require replicated high availability.


References

RabbitMQ's official Debian installation documentation currently supports Debian 13 Trixie and recommends installing RabbitMQ and a supported Erlang version through Team RabbitMQ's APT repositories rather than Debian's standard RabbitMQ package. (RabbitMQ)

RabbitMQ recommends odd-numbered clusters and strongly discourages two-node clusters for consensus-based features. Modern RabbitMQ also allows nodes to join a cluster directly using rabbitmqctl join_cluster without the older stop/reset sequence. (RabbitMQ)

RabbitMQ uses ports 4369 and 25672 for clustering, 5672/5671 for AMQP, and 15672/15671 for the Management UI and HTTP API. (RabbitMQ)

For highly available replicated queues, RabbitMQ recommends quorum queues, which use Raft-based replication; classic queue mirroring has been removed from RabbitMQ 4.x. (RabbitMQ)

Leave a comment

Your email address will not be published. Required fields are marked *