This article say: how to manage RabbitMQ

Command Line Tools

https://www.rabbitmq.com/docs/3.13/cli

Overview

Standard RabbitMQ CLI Tools

RabbitMQ ships with multiple command line tools, each with a set of related commands:

• rabbitmqctl for service management and general operator tasks
• rabbitmq-diagnostics for diagnostics monitoring and health checking
• rabbitmq-plugins for plugin management
• rabbitmq-queues for maintenance tasks on queues, in particular quorum queues
• rabbitmq-streams for maintenance tasks on streams
• rabbitmq-upgrade for maintenance tasks related to upgrades

On Windows, the above tool names will end with .bat, e.g. rabbitmqctl in a Windows installation will be named rabbitmqctl.bat.

Additional Tools

Additional tools are optional and can be obtained from GitHub:

• rabbitmqadmin for operator tasks over HTTP API
• rabbitmq-collect-env which collects relevant cluster and environment information as well as server logs. This tool is specific to Linux and UNIX-like operating systems.

rabbitmqctl

rabbitmqctl is the original CLI tool that ships with RabbitMQ. It supports a wide range of operations, mostly administrative (operational) in nature.

This includes

• Stopping node
• Access to node status, effective configuration, health checks
• Virtual host management
• User and permission management
• Policy management
• Listing queues, connections, channels, exchanges, consumers
• Cluster membership management

and more.

rabbitmqctl uses a shared secret authentication mechanism (described below) with server nodes.

rabbitmq-queues

rabbitmq-queues allows the operator to manage replicas of replicated queues. It ships with RabbitMQ.

Most commands only support the online mode (when target node is running).

rabbitmq-queues uses a shared secret authentication mechanism (described below) with server nodes.

rabbitmq-streams

rabbitmq-streams allows the operator to manage replicas of streams. It ships with RabbitMQ.

Most commands only support the online mode (when target node is running).

rabbitmq-streams uses a shared secret authentication mechanism (described below) with server nodes.

rabbitmq-diagnostics

rabbitmq-diagnostics is the primary tool for inspecting node state. It has many commands that allow the operator to study various aspects of the system. It ships with RabbitMQ.

It supports both online (when target node is running) and offline mode (changes take effect on node restart).

rabbitmq-diagnostics uses a shared secret authentication mechanism (described below) with server nodes.

rabbitmq-plugins

rabbitmq-plugins is a tool that manages plugins: lists, enables and disables them. It ships with RabbitMQ.

It supports both online (when target node is running) and offline mode (changes take effect on node restart).

rabbitmq-plugins uses a shared secret authentication mechanism (described below) with server nodes.

rabbitmq-upgrade

rabbitmq-upgrade is a tool dedicated to pre-upgrade, upgrade and post-upgrade operations. It ships with RabbitMQ.

Most commands only support the online mode (when target node is running).

rabbitmq-upgrade uses a shared secret authentication mechanism (described below) with server nodes.

Using CLI Tools against Remote Server Nodes

CLI tools can be used to talk to remote nodes as well as the local ones. Nodes are identified by node names. If no node name is specified, rabbit@{local hostname} is assumed to be the target. When contacting remote nodes, the same authentication requirements apply.

To contact a remote node, use the --node (-n) option that rabbitmqctl, rabbitmq-diagnostics and other core CLI tools accept. The following example contact the node rabbit@remote-host.local to find out its status:

rabbitmq-diagnostics status -n rabbit@remote-host.local

Some commands, such as

rabbitmq-diagnostics status

can be used against any node. Others, such as

rabbitmqctl shutdown

or

rabbitmqctl wait

can only be run on the same host or in the same container as their target node. These commands typically rely on or modify something in the local environment, e.g. the local enabled plugins file.

Node Names

RabbitMQ nodes are identified by node names. A node name consists of two parts, a prefix (usually rabbit) and hostname. For example, rabbit@node1.messaging.svc.local is a node name with the prefix of rabbit and hostname of node1.messaging.svc.local.

Node names in a cluster must be unique. If more than one node is running on a given host (this is usually the case in development and QA environments), they must use different prefixes, e.g. rabbit1@hostname and rabbit2@hostname.

CLI tools identify and address server nodes using node names. Most CLI commands are invoked against a node called target node. To specify a target node, use the --node (-n) option. For example, to run a health check on node rabbit@warp10.local:

rabbitmq-diagnostics -n rabbit@warp10 check_alarms

Some commands accept both a target node and another node name. For example, rabbitmqctl forget_cluster_node accepts both a target node (that will perform the action) and a name of the node to be removed.

In a cluster, nodes identify and contact each other using node names. See Clustering guide for details.

When a node starts up, it checks whether it has been assigned a node name. This is done via the RABBITMQ_NODENAME environment variable. If no value was explicitly configured, the node resolves its hostname and prepends rabbit to it to compute its node name.

How CLI Tools Authenticate to Nodes (and Nodes to Each Other): the Erlang Cookie

RabbitMQ nodes and CLI tools (with the exception of rabbitmqadmin) use a cookie to determine whether they are allowed to communicate with each other. For a CLI tool and a node to be able to communicate they must have the same shared secret called the Erlang cookie. The cookie is just a string of alphanumeric characters up to 255 characters in size. It is usually stored in a local file. The file must be only accessible to the owner (e.g. have UNIX permissions of 600 or similar). Every cluster node must have the same cookie.

If the file does not exist, Erlang VM will automatically create one with a randomly generated value when the RabbitMQ server starts up.

Erlang cookie generation should be done at cluster deployment stage, ideally using automation and orchestration tools.

Cookie File Locations

Linux, MacOS, *BSD

On UNIX systems, the cookie will be typically located in /var/lib/rabbitmq/.erlang.cookie (used by the server) and $HOME/.erlang.cookie (used by CLI tools). Note that since the value of $HOME varies from user to user, it's necessary to place a copy of the cookie file for each user that will be using the CLI tools. This applies to both non-privileged users and root.

RabbitMQ nodes will log its effective user's home directory location early on boot.

Troubleshooting

Starting with version 3.8.6, rabbitmq-diagnostics includes a command that provides relevant information on the Erlang cookie file used by CLI tools:

rabbitmq-diagnostics erlang_cookie_sources

The command will report on the effective user, user home directory and the expected location of the cookie file:

Cookie File

Effective user: antares
Effective home directory: /home/cli-user
Cookie file path: /home/cli-user/.erlang.cookie
Cookie file exists? true
Cookie file type: regular
Cookie file access: read
Cookie file size: 20

Cookie CLI Switch

--erlang-cookie value set? false
--erlang-cookie value length: 0

Env variable  (Deprecated)

RABBITMQ_ERLANG_COOKIE value set? false
RABBITMQ_ERLANG_COOKIE value length: 0

Server Nodes

When a node starts, it will log the home directory location of its effective user:

node           : rabbit@cdbf4de5f22d
home dir       : /var/lib/rabbitmq

Unless any server directories were overridden, that's the directory where the cookie file will be looked for, and created by the node on first boot if it does not already exist.

In the example above, the cookie file location will be /var/lib/rabbitmq/.erlang.cookie.

"Node-local" and "Clusterwide" Commands

Client connections, channels and queues will be distributed across cluster nodes. Operators need to be able to inspect and monitor such resources across all cluster nodes.

CLI tools such as rabbitmqctl and rabbitmq-diagnostics provide commands that inspect resources and cluster-wide state. Some commands focus on the state of a single node (e.g. rabbitmq-diagnostics environment and rabbitmq-diagnostics status), others inspect cluster-wide state. Some examples of the latter include rabbitmqctl list_connections, rabbitmqctl list_mqtt_connections, rabbitmqctl list_stomp_connections, rabbitmqctl list_users, rabbitmqctl list_vhosts and so on.

Such "cluster-wide" commands will often contact one node first, discover cluster members and contact them all to retrieve and combine their respective state. For example, rabbitmqctl list_connections will contact all nodes, retrieve their AMQP 0-9-1 and AMQP 1.0 connections, and display them all to the user. The user doesn't have to manually contact all nodes.

Assuming a non-changing state of the cluster (e.g. no connections are closed or opened), two CLI commands executed against two different nodes one after another will produce identical or semantically identical results. "Node-local" commands, however, likely will not produce identical results since two nodes rarely have entirely identical state.

Configuration

Overview

RabbitMQ comes with default built-in settings. Those can be entirely sufficient in some environment (e.g. development and QA). For all other cases, as well as production deployment tuning, there is a way to configure many things in the broker as well as plugins.

This guide covers a number of topics related to configuration:

• Different ways in which various settings of the server and plugins are configured
• Configuration file(s): primary rabbitmq.conf or a directory of .conf files, and optional advanced.config
• Default configuration file location(s) on various platforms
• Configuration troubleshooting: how to find config file location and inspect and verify effective configuration
• Environment variable interpolation in rabbitmq.conf
• Environment variables used by RabbitMQ nodes
• Operating system (kernel) limits
• Available core server settings
• Available environment variables
• How to encrypt sensitive configuration values

and more.

Since configuration affects many areas of the system, including plugins, individual documentation guides dive deeper into what can be configured. Runtime Tuning is a companion to this guide that focuses on the configurable parameters in the runtime. Deployment Guidelines is a related guide that outlines what settings will likely need tuning in most production environments.

Means of Configuration

A RabbitMQ node can be configured using a number of mechanisms responsible for different areas:

Most settings are configured using the first two methods. This guide, therefore, focuses on them.

Configuration File(s)

Introduction

While some settings in RabbitMQ can be tuned using environment variables, most are configured using a main configuration file named rabbitmq.conf.

This includes configuration for the core server as well as plugins. An additional configuration file can be used to configure settings that cannot be expressed in the main file's configuration format. This is covered in more details below.

The sections below cover the syntax and location of both files, where to find examples, and more.

Config File Locations

Default config file locations vary between operating systems and package types.

This topic is covered in more detail in the rest of this guide.

When in doubt about RabbitMQ config file location, consult the log file and/or management UI as explained in the following section.

How to Find Config File Location

The active configuration file can be verified by inspecting the RabbitMQ log file. It will show up in the log file at the top, along with the other broker boot log entries. For example:

node           : rabbit@example
home dir       : /var/lib/rabbitmq
config file(s) : /etc/rabbitmq/advanced.config
               : /etc/rabbitmq/rabbitmq.conf

If the configuration file cannot be found or read by RabbitMQ, the log entry will say so:

node           : rabbit@example
home dir       : /var/lib/rabbitmq
config file(s) : /var/lib/rabbitmq/hare.conf (not found)

Alternatively, the location of configuration files used by a local node, use the rabbitmq-diagnostics status command:

# displays key
rabbitmq-diagnostics status

and look for the Config files section that would look like this:

Config files

 * /etc/rabbitmq/advanced.config
 * /etc/rabbitmq/rabbitmq.conf

To inspect the locations of a specific node, including nodes running remotely, use the -n (short for --node) switch:

rabbitmq-diagnostics status -n [node name]

Finally, config file location can be found in the management UI, together with other details about nodes.

When troubleshooting configuration settings, it is very useful to verify that the config file path is correct, exists and can be loaded (e.g. the file is readable) before verifying effective node configuration. Together, these steps help quickly narrow down most common misconfiguration problems.

The Main Configuration File, rabbitmq.conf

The configuration file rabbitmq.conf allows the RabbitMQ server and plugins to be configured. The file uses the sysctl format, unlike advanced.config and the original rabbitmq.config (both use the Erlang terms format).

The syntax can be briefly explained in 3 lines:

• One setting uses one line
• Lines are structured Key = Value
• Any line starting with a # character is a comment

A minimalistic example configuration file follows:

# this is a comment
listeners.tcp.default = 5673

The RabbitMQ server source repository contains an example rabbitmq.conf file named rabbitmq.conf.example. It contains examples of most of the configuration items you might want to set (with some very obscure ones omitted), along with documentation for those settings.

Documentation guides such as Networking, TLS, or Access Control contain many examples in relevant formats.

Note that this configuration file is not to be confused with the environment variable configuration files, rabbitmq-env.conf and rabbitmq-env-conf.bat.

To override the main RabbitMQ config file location, use the RABBITMQ_CONFIG_FILE environment variables. Use .conf as file extension for the new style config format, e.g. /etc/rabbitmq/rabbitmq.conf or /data/configuration/rabbitmq/rabbitmq.conf

Environment Variable Interpolation in rabbitmq.conf

Modern RabbitMQ versions support environment variable interpolation in rabbitmq.conf. For example, to override default user credentials, one can use import a definition file or the following config file in combination with two environment variables:

# environment variable interpolation
default_user = $(SEED_USERNAME)
default_pass = $(SEED_USER_PASSWORD)

Environment variables can be used to configure a portion of a value, for example, cluster name:

cluster_name = deployment-$(DEPLOYMENT_ID)

Environment variable values are interpolated as strings before the config file is parsed and validated. This means that they can be used to override numerical settings (such as ports) or paths (such as TLS certificate and private key paths).

In addition, RabbitMQ respects a number of environment variables for when a value must be known before the configuration file is loaded.

Location of rabbitmq.conf, advanced.config and rabbitmq-env.conf

Default configuration file location is distribution-specific. RabbitMQ packages or nodes will not create any configuration files. Users and deployment tool should use the following locations when creating the files:

Environment variables can be used to override the location of the configuration file:

# overrides primary config file location
RABBITMQ_CONFIG_FILE=/path/to/a/custom/location/rabbitmq.conf

# overrides advanced config file location
RABBITMQ_ADVANCED_CONFIG_FILE=/path/to/a/custom/location/advanced.config

# overrides environment variable file location
RABBITMQ_CONF_ENV_FILE=/path/to/a/custom/location/rabbitmq-env.conf

When Will Configuration File Changes Be Applied

rabbitmq.conf and advanced.config changes take effect after a node restart.

If rabbitmq-env.conf doesn't exist, it can be created manually in the location specified by the RABBITMQ_CONF_ENV_FILE variable. On Windows systems, it is named rabbitmq-env-conf.bat.

How to Inspect and Verify Effective Configuration of a Running Node

It is possible to print effective configuration (user provided values from all configuration files merged into defaults) using the rabbitmq-diagnostics environment command:

# inspect effective configuration on a node
rabbitmq-diagnostics environment

to check effective configuration of a specific node, including nodes running remotely, use the -n (short for --node) switch:

rabbitmq-diagnostics environment -n [node name]

The command above will print applied configuration for every application (RabbitMQ, plugins, libraries) running on the node. Effective configuration is computed using the following steps:

• rabbitmq.conf is translated into the internally used (advanced) config format. These configuration is merged into the defaults
• advanced.config is loaded if present, and merged into the result of the step above

Effective configuration should be verified together with config file location. Together, these steps help quickly narrow down most common misconfiguration problems.

Example Configuration Files

The RabbitMQ server source repository contains examples for the configuration files:

• rabbitmq.conf.example
• advanced.config.example

These files contain examples of most of the configuration keys along with a brief explanation for those settings. All configuration items are commented out in the example, so you can uncomment what you need. Note that the example files are meant to be used as, well, examples, and should not be treated as a general recommendation.

In most distributions the example file is placed into the same location as the real file should be placed (see above). On Debian and RPM distributions policy forbids doing so; instead find the file under /usr/share/doc/rabbitmq-server/ or /usr/share/doc/rabbitmq-server-3.13.7/, respectively.

Configuration Using Environment Variables

Certain server parameters can be configured using environment variables: node name, RabbitMQ configuration file location, inter-node communication ports, Erlang VM flags, and so on.

Linux, MacOS, BSD

On UNIX-based systems (Linux, MacOS and flavours of BSD) it is possible to use a file named rabbitmq-env.conf to define environment variables that will be used by the broker. Its location is configurable using the RABBITMQ_CONF_ENV_FILE environment variable.

rabbitmq-env.conf uses the standard environment variable names but without the RABBITMQ_ prefix. For example, the RABBITMQ_CONFIG_FILE variable appears below as CONFIG_FILE and RABBITMQ_NODENAME becomes NODENAME:

# Example rabbitmq-env.conf file entries. Note that the variables
# do not have the RABBITMQ_ prefix.
#
# Overrides node name
NODENAME=bunny@myhost

# Specifies new style config file location
CONFIG_FILE=/etc/rabbitmq/rabbitmq.conf

# Specifies advanced config file location
ADVANCED_CONFIG_FILE=/etc/rabbitmq/advanced.config

See the rabbitmq-env.conf man page for details.

Environment Variables Used by RabbitMQ

All environment variables used by RabbitMQ use the prefix RABBITMQ_ (except when defined in rabbitmq-env.conf or rabbitmq-env-conf.bat).

Environment variables set in the shell environment take priority over those set in rabbitmq-env.conf or rabbitmq-env-conf.bat, which in turn override RabbitMQ built-in defaults.

The table below describes key environment variables that can be used to configure RabbitMQ. More variables are covered in the File and Directory Locations guide.

Besides the variables listed above, there are several environment variables which tell RabbitMQ where to locate its database, log files, plugins, configuration and so on.

Finally, some environment variables are operating system-specific.

Virtual Hosts

Introduction

RabbitMQ is multi-tenant system: connections, exchanges, queues, bindings, user permissions, policies and some other things belong to virtual hosts, logical groups of entities. If you are familiar with virtual hosts in Apache or server blocks in Nginx, the idea is similar.

There is, however, one important difference: virtual hosts in Apache are defined in the configuration file; that's not the case with RabbitMQ: virtual hosts are created and deleted using rabbitmqctl or the HTTP API instead.

Logical and Physical Separation

Virtual hosts provide logical grouping and separation of resources. Separation of physical resources is not a goal of virtual hosts, although certain resources can be limited for individual virtual hosts.

For example, resource permissions in RabbitMQ are scoped per virtual host. A user doesn't have global permissions, only permissions in one or more virtual hosts. User tags can be considered global permissions but they are an exception to the rule.

Therefore when talking about user permissions it is very important to clarify what virtual host(s) they apply to.

Virtual Hosts and Client Connections

A virtual host has a name. When an AMQP 0-9-1 client connects to RabbitMQ, it specifies a vhost name to connect to. If authentication succeeds and the username provided was granted permissions to the vhost, connection is established.

Connections to a vhost can only operate on exchanges, queues, bindings, and so on in that vhost. "Interconnection" of e.g. a queue and an exchange in different vhosts is only possible when an application connects to two vhosts at the same time. For example, an application can consume from one vhost then republishes into the other. This scenario can involve vhosts in different clusters or the same cluster (or a single node). RabbitMQ Shovel plugin is one example of such application.

Creating a Virtual Host

A virtual host can be created using CLI tools or an HTTP API endpoint.

A newly created vhost will have a default set of exchanges but no other entities and no user permissions. For a user to be able to connect and use the virtual host, permissions to it must be granted to every user that will use the vhost, e.g. using rabbitmqctl set_permissions.

Using CLI Tools

A virtual host can be created using rabbitmqctl's add_vhost command which accepts virtual host name as the only mandatory argument.

Here's an example that creates a virtual host named qa1:

rabbitmqctl add_vhost qa1

Virtual Host Metadata

Virtual hosts can have metadata associated with them:

• A description
• A set of tags
• Default queue type configured for the virtual host

All these settings are optional. They can be provided at virtual host creation time or updated later.

Using CLI Tools

The rabbitmqctl add_vhost command accepts a virtual host name as well as a number of optional flags.

Here's an example that creates a virtual host named qa1 with quorum queues for default queue type, a description and two tags:

rabbitmqctl add_vhost qa1 --description "QA env 1" --default-queue-type quorum

rabbitmqctl update_vhost_metadata can be used to update all or some of the metadata values demonstrated above:

rabbitmqctl update_vhost_metadata qa1 --description "QA environment for issue 1662" --default-queue-type quorum --tags qa,project-a,qa-1662

To inspect virtual host metadata, use rabbitmqctl list_vhosts and provide the additional column(s):

rabbitmqctl -q --formatter=pretty_table list_vhosts name description tags default_queue_type

Default Queue Type (DQT)

When a client declares a queue without explicitly specifying its type using the x-queue-type header, a configurable default type is used. The default can be overridden by specifying it in virtual host metadata (see above):

rabbitmqctl add_vhost qa1 --description "QA environment 1" --default-queue-type quorum --tags qa,project-a

Supported queue types are:

• "quorum"
• "stream"
• "classic"

The default is only effective for new queue declarations; updating the default will not affect queue type of any existing queues or streams because queue type is immutable and cannot be changed after declaration.

Starting with RabbitMQ 3.13.4, for queues that were declared without an explicitly set queue type, the effective virtual host default will be injected into the queue properties at definition export time.

Node-wide Default Queue Type (Node-wide DQT)

Starting with RabbitMQ 3.13.4, instead of configuring the same default queue type for every virtual host in the cluster, a node-wide default can be set using rabbitmq.conf:

# supported values are: quorum, stream, classic, or a custom queue type module name
default_queue_type = quorum

When both the virtual host DQT and the node-wide DQT are set, the virtual host one will take precedence.

Deleting a Virtual Host

A virtual host can be deleted using CLI tools or an HTTP API endpoint.

Deleting a virtual host will permanently delete all entities (queues, exchanges, bindings, policies, permissions, etc) in it.

Using CLI Tools

A virtual host can be deleted using rabbitmqctl's delete_vhost command which accepts virtual host name as the only mandatory argument.

Here's an example that deletes a virtual host named qa1:

rabbitmqctl delete_vhost qa1

Authentication, Authorisation, Access Control

Overview

This document describes authentication and authorisation features in RabbitMQ. Together they allow the operator to control access to the system.

Different users can be granted access only to specific virtual hosts. Their permissions in each virtual host also can be limited.

RabbitMQ supports two major authentication mechanisms as well as several authentication and authorisation backends.

This guide covers a variety of authentication, authorisation and user management topics such as

• Access control essentials
• Default virtual host and user
• Connectivity limitations imposed on the default user
• Authorisation and resource permissions
• How to manage users and permissions using CLI tools
• How to change an authentication or authorization backend used, or use a combination of backends
• How to authenticate clients using their TLS certificate information
• How to limit access to topics on a topic exchange
• User tags and how they are used
• How to rotate credentials and revoke access for a user
• Shell escaping of characters in generated passwords
• How to pre-create users and their permissions
• Troubleshooting of authentication and authorisation failures

Password-based authentication has a companion guide. Two closely related topics of OAuth 2 support and TLS support, including x.509-certificate based authentication, are covered in dedicated guides.

Terminology and Definitions

Authentication and authorisation are often confused or used interchangeably. That's wrong and in RabbitMQ, the two are separated. For the sake of simplicity, we'll define authentication as "identifying who the user is" and authorisation as "determining what the user is and isn't allowed to do."

The Basics

When clients connect to RabbitMQ, they specify a set of credentials: a username-password pair, a JWT token, or a x.509 certificate. Every connection has an associated user which is authenticated. It also targets a virtual host for which the user must have a certain set of permissions.

Authentication: Who Do You Say You Are?

After an application connects to RabbitMQ and before it can perform operations, it must authenticate, that is, present and prove its identity. With that identity, RabbitMQ nodes can look up its permissions and authorize access to resources such as virtual hosts, queues, exchanges, and so on.

Two primary ways of authenticating a client are username/password pairs and X.509 certificates. Username/password pairs can be used with a variety of authentication backends that verify the credentials.

Connections that fail to authenticate will be closed with an error message in the server log.

"guest" user can only connect from localhost

By default, the guest user is prohibited from connecting from remote hosts; it can only connect over a loopback interface (localhost). This applies to connections regardless of the protocol. Any other users will not (by default) be restricted in this way.

Remote connections that use the default user will be refused with a log message similar to this:

[error] <0.918.0> PLAIN login refused: user 'guest' can only connect via localhost

The recommended way to address this in production systems is to create a new user with generated credentials, or set of users, with the permissions to access the necessary virtual hosts. This can be done using CLI tools, HTTP API or definitions import.

Managing Users and Permissions

Users and permissions can be managed using CLI tools and definition import (covered below).

Before We Start: Shell Escaping and Generated Passwords

It is a common security practice to generate complex passwords, often involving non-alphanumeric characters. This practice is perfectly applicable to RabbitMQ users.

Shells (bash, zsh, and so on) interpret certain characters (!, ?, &, ^, ", ', *, ~, and others) as control characters.

When a password is specified on the command line for rabbitmqctl add_user, rabbitmqctl change_password, and other commands that accept a password, such control characters must be escaped appropriately for the shell used. With inappropriate escaping the command will fail or RabbitMQ CLI tools will receive a different value from the shell.

When generating passwords that will be passed on the command line, long (say, 40 to 100 characters) alphanumeric value with a very limited set of symbols (e.g. :, =) is the safest option.

Adding a User

To add a user, use rabbitmqctl add_user. It has multiple ways of specifying a password:

• bash
• PowerShell
• cmd

# will prompt for password, only use this option interactively
rabbitmqctl add_user "username"

# Password is provided via standard input.
# Note that certain characters such as !, &, $, #, and so on must be escaped to avoid
# special interpretation by the shell.
echo '2a55f70a841f18b97c3a7db939b7adc9e34a0f1b' | rabbitmqctl add_user 'username'

# Password is provided as a command line argument.
# Note that certain characters such as !, &, $, #, and so on must be escaped to avoid
# special interpretation by the shell.
rabbitmqctl add_user 'username' '2a55f70a841f18b97c3a7db939b7adc9e34a0f1b'

A newly added user must be granted permissions for one or more virtual hosts, otherwise its connections will be refused.

Listing Users

To list users in a cluster, use rabbitmqctl list_users:

• bash
• PowerShell

rabbitmqctl list_users

The output can be changed to be JSON:

• bash
• PowerShell

rabbitmqctl list_users --formatter=json

Deleting a User

To delete a user, use rabbitmqctl delete_user:

• bash
• PowerShell

rabbitmqctl delete_user 'username'

Granting Permissions to a User

To grant permissions to a user in a virtual host, use rabbitmqctl set_permissions:

• bash
• PowerShell

# First ".*" for configure permission on every entity
# Second ".*" for write permission on every entity
# Third ".*" for read permission on every entity
rabbitmqctl set_permissions -p "custom-vhost" "username" ".*" ".*" ".*"

Clearing Permissions of a User in a Virtual Host

To revoke permissions from a user in a virtual host, use rabbitmqctl clear_permissions:

• bash
• PowerShell

# Revokes permissions in a virtual host
rabbitmqctl clear_permissions -p "custom-vhost" "username"

Authorisation: How Permissions Work

When a RabbitMQ client establishes a connection to a server and authenticates, it specifies a virtual host within which it intends to operate. A first level of access control is enforced at this point, with the server checking whether the user has any permissions to access the virtual hosts, and rejecting the connection attempt otherwise.

Resources, i.e. exchanges and queues, are named entities inside a particular virtual host; the same name denotes a different resource in each virtual host. A second level of access control is enforced when certain operations are performed on resources.

RabbitMQ distinguishes between configure, write and read operations on a resource. The configure operations create or destroy resources, or alter their behaviour. The write operations inject messages into a resource. And the read operations retrieve messages from a resource.

In order to perform an operation on a resource the user must have been granted the appropriate permissions for it. The following table shows what permissions on what type of resource are required for all the AMQP 0-9-1 commands which perform permission checks.

Permissions are expressed as a triple of regular expressions — one each for configure, write and read — on a per-vhost basis. The user is granted the respective permission for operations on all resources with names matching the regular expressions.

For example, the table above demonstrates that the queue.bind protocol operation requires write permission on the target queue and the read permission is required on the target exchange.

In other words, in order to allow a user to bind a queue named queueA to an exchange named exchangeB the user will need the write permission regex (for the correct virtual host) to match queueA, and the read permission regex to match exchangeB.

For convenience RabbitMQ maps AMQP 0-9-1's default exchange's blank name to 'amq.default' when performing permission checks.

The regular expression '^$', i.e. matching nothing but the empty string, covers all resources and effectively stops the user from performing any operation. Built-in AMQP 0-9-1 resource names are prefixed with amq. and server generated names are prefixed with amq.gen.

For example, '^(amq\.gen.*|amq\.default)$' gives a user access to server-generated names and the default exchange. The empty string, '' is a synonym for '^$' and restricts permissions in the exact same way.

RabbitMQ may cache the results of access control checks on a per-connection or per-channel basis. Hence changes to user permissions may only take effect when the user reconnects.

For details of how to set up access control, please see the User management section as well as the rabbitmqctl man page.

User Tags and Management UI Access

In addition to the permissions covered above, users can have tags associated with them. Currently only management UI access is controlled by user tags.

The tags are managed using rabbitmqctl. Newly created users do not have any tags set on them by default.

Please refer to the management plugin guide to learn more about what tags are supported and how they limit management UI access.

Topic Authorisation

RabbitMQ supports topic authorisation for topic exchanges. The routing key of a message published to a topic exchange is taken into account when publishing authorisation is enforced (e.g. in RabbitMQ default authorisation backend, the routing key is matched against a regular expression to decide whether the message can be routed downstream or not). Topic authorisation targets protocols like STOMP and MQTT, which are structured around topics and use topic exchanges under the hood.

Topic authorisation is an additional layer on top of existing checks for publishers. Publishing a message to a topic-typed exchange will go through both the basic.publish and the routing key checks. The latter is never called if the former refuses access.

Topic authorisation can also be enforced for topic consumers. Note that it works differently for different protocols. The concept of topic authorisation only really makes sense for the topic-oriented protocols such as MQTT and STOMP. In AMQP 0-9-1, for example, consumers consume from queues and thus the standard resource permissions apply. In addition for AMQP 0-9-1, binding routing keys between an AMQP 0-9-1 topic exchange and a queue/exchange are checked against the topic permissions configured, if any. For more information about how RabbitMQ handles authorisation for topics, please see the STOMP and MQTT documentation guides.

When default authorisation backend is used, publishing to a topic exchange or consuming from a topic is always authorised if no topic permissions are defined (which is the case on a fresh RabbitMQ installation). With this authorisation backend, topic authorisation is optional: you don't need to approve any exchanges. To use topic authorisation therefore you need to opt in and define topic permissions for one or more exchanges. For details please see the rabbitmqctl man page.

Internal (default) authorisation backend supports variable expansion in permission patterns. Three variables are supported: username, vhost, and client_id. Note that client_id only applies to MQTT. For example, if tonyg is the connected user, the permission ^{username}-.* is expanded to ^tonyg-.*

If a different authorisation backend (e.g. LDAP, HTTP, OAuth 2) is used, please refer to the documentation of those backends.

If a custom authorisation backend is used, topic authorisation is enforced by implementing the check_topic_access callback of the rabbit_authz_backend behavior.

Revoking User Access and Credential Rotation

Revoking User Access

To revoke user access, the recommended procedure is deleting the user. All open connections that belong to a deleted user will be closed.

It is also possible to clear user permissions but that will not affect any currently open connections. Connections use an authorization operation cache, so client operations will be refused eventually. The period of time depends on the authorization backend used.

Permissions

rabbitmqctl authenticate_user can be used to test authentication for a username and password pair:

• bash
• PowerShell

rabbitmqctl authenticate_user "a-username" "a/password"

If authentication succeeds, it will exit with the code of zero. In case of a failure, a non-zero exit code will be used and a failure error message will be printed.

rabbitmqctl authenticate_user will use a CLI-to-node communication connection to attempt to authenticate the username/password pair against an internal API endpoint. The connection is assumed to be trusted. If that's not the case, its traffic can be encrypted using TLS.

Insufficient Permissions

Another very common scenario is that the permissions are defined but they are insufficient for the operations that the client tries to perform.

In this case the connection will be accepted

rabbitmqctl list_permissions can be used to inspect a user's permission in a given virtual host:

• bash
• PowerShell

rabbitmqctl list_permissions --vhost /
# => Listing permissions for vhost "/" ...
# => user	configure	write	read
# => user2	.*	.*	.*
# => guest	.*	.*	.*
# => temp-user	.*	.*	.*

rabbitmqctl list_permissions --vhost gw1
# => Listing permissions for vhost "gw1" ...
# => user	configure	write	read
# => guest	.*	.*	.*
# => user2	^user2	^user2	^user2

Deployment Guidelines

Overview

Data services such as RabbitMQ often have many tunable parameters. Some configurations or practices make a lot of sense for development but are not really suitable for production. No single configuration fits every use case. It is, therefore, important to assess system configuration and have a plan for "day two operations" activities such as upgrades before going into production.

Table of Contents

Production systems have concerns that go beyond configuration: system observability, security, application development practices, resource usage, release support timeline, and more.

Monitoring and metrics are the foundation of a production-grade system. Besides helping detect issues, it provides the operator data that can be used to size and configure both RabbitMQ nodes and applications.

This guide provides recommendations in a few areas:

• Storage considerations for node data directories
• Networking-related recommendations
• Recommendations related to virtual hosts, users and permissions
• Monitoring and resource usage
• Per-virtual host and per-user limits
• Security
• Clustering and multi-node deployments
• Application-level practices and considerations

and more.

Networking and RabbitMQ

Overview

Clients communicate with RabbitMQ over the network. All protocols supported by the broker are TCP-based. Both RabbitMQ and the operating system provide a number of knobs that can be tweaked. Some of them are directly related to TCP and IP operations, others have to do with application-level protocols such as TLS. This guide covers multiple topics related to networking in the context of RabbitMQ. This guide is not meant to be an extensive reference but rather an overview. Some tuneable parameters discussed are OS-specific. This guide focuses on Linux when covering OS-specific subjects, as it is the most common platform RabbitMQ is deployed on.

There are several areas which can be configured or tuned. Each has a section in this guide:

• Interfaces the node listens on for client connections
• IP version preferences: dual stack, IPv6-only and IPv4-only
• Ports used by clients, inter-node traffic in clusters and CLI tools
• IPv6 support for inter-node traffic
• TLS for client connections
• Tuning for a large number of concurrent connections
• High connection churn scenarios and resource exhaustion
• TCP buffer size (affects throughput and how much memory is used per connection)
• Hostname resolution-related topics such as reverse DNS lookups
• The interface and port used by epmd
• How to suspend and resume listeners to temporarily stop and resume new client connections
• Other TCP socket settings
• Proxy protocol support for client connections
• Kernel TCP settings and limits (e.g. TCP keepalives and open file handle limit)
• How to allow Erlang runtime to accept inbound connections when MacOS Application Firewall is enabled
• OS-level tuning related to networking

This guide also covers a few topics closely related to networking:

Except for OS kernel parameters and DNS, all RabbitMQ settings are configured via RabbitMQ configuration file(s).

Networking is a broad topic. There are many configuration options that can have positive or negative effect on certain workloads. As such, this guide does not try to be a complete reference but rather offer an index of key tunable parameters and serve as a starting point.

In addition, this guide touches on a few topics closely related to networking, such as

• Hostnames, hostname resolution and DNS
• connection lifecycle logging
• Heartbeats (a.k.a. keepalives)
• proxies and load balancers

VMware Tanzu RabbitMQ commercial offerings provide an Intra-cluster Compression feature. The previous documentation link goes to the Tanzu RabbitMQ for Kubernetes commercial offering.

A methodology for troubleshooting of networking-related issues is covered in a separate guide.

Network Interfaces for Client Connections

For RabbitMQ to accept client connections, it needs to bind to one or more interfaces and listen on (protocol-specific) ports. One such interface/port pair is called a listener in RabbitMQ parlance. Listeners are configured using the listeners.tcp.* configuration option(s).

TCP listeners configure both an interface and port. The following example demonstrates how to configure AMQP 0-9-1 and AMQP 1.0 listener to use a specific IP and the standard port:

listeners.tcp.1 = 192.168.1.99:5672

By default, RabbitMQ will listen on port 5672 on all available interfaces. It is possible to limit client connections to a subset of the interfaces or even just one, for example, IPv6-only interfaces. The following few sections demonstrate how to do it.

Listening on Dual Stack (Both IPv4 and IPv6) Interfaces

The following example demonstrates how to configure RabbitMQ to listen on localhost only for both IPv4 and IPv6:

listeners.tcp.1 = 127.0.0.1:5672
listeners.tcp.2 = ::1:5672

With modern Linux kernels and Windows releases, when a port is specified and RabbitMQ is configured to listen on all IPv6 addresses but IPv4 is not deactivated explicitly, IPv4 address will be included, so

listeners.tcp.1 = :::5672

is equivalent to

listeners.tcp.1 = 0.0.0.0:5672
listeners.tcp.2 = :::5672

Port Access

RabbitMQ nodes bind to ports (open server TCP sockets) in order to accept client and CLI tool connections. Other processes and tools such as SELinux may prevent RabbitMQ from binding to a port. When that happens, the node will fail to start.

CLI tools, client libraries and RabbitMQ nodes also open connections (client TCP sockets). Firewalls can prevent nodes and CLI tools from communicating with each other. Make sure the following ports are accessible:

• 4369: epmd, a peer discovery service used by RabbitMQ nodes and CLI tools
• 5672, 5671: used by AMQP 0-9-1 and AMQP 1.0 clients without and with TLS
• 5552, 5551: used by the RabbitMQ Stream protocol clients without and with TLS
• 6000 through 6500: used for stream replication
• 25672: used for inter-node and CLI tools communication (Erlang distribution server port) and is allocated from a dynamic range (limited to a single port by default, computed as AMQP port + 20000). Unless external connections on these ports are really necessary (e.g. the cluster uses federation or CLI tools are used on machines outside the subnet), these ports should not be publicly exposed
• 35672-35682: this client TCP port range is used by CLI tools for communication with nodes. By default, the range computed as (server distribution port + 10000) through (server distribution port + 10010)
• 15672, 15671: HTTP API clients, management UI and rabbitmqadmin, without and with TLS (only if the management plugin is enabled)
• 61613, 61614: STOMP clients without and with TLS (only if the STOMP plugin is enabled)
• 1883, 8883: MQTT clients without and with TLS, if the MQTT plugin is enabled
• 15674: STOMP-over-WebSockets clients (only if the Web STOMP plugin is enabled)
• 15675: MQTT-over-WebSockets clients (only if the Web MQTT plugin is enabled)
• 15692, 15691: Prometheus metrics, without and with TLS (only if the Prometheus plugin is enabled)

It is possible to configure RabbitMQ to use different ports and specific network interfaces.