RabbitMQ ships with multiple command line tools, each with a set of related commands:
they can be found under the sbin directory in installation root.
On Windows, the above tool names will end with .bat, e.g. rabbitmqctl in a Windows installation will be named rabbitmqctl.bat.
Additional tools are optional and can be obtained from GitHub:
Different tools cover different usage scenarios. For example, rabbitmqctl is usually only available to RabbitMQ administrator given that it provides full control over a node, including virtual host, user and permission management, destructive operations on node's data and so on.
rabbitmqadmin is built on top of the HTTP API and uses a different mechanism, and only requires that the HTTP API port is open for outside connections.
Even though CLI tools ship with the server, most commands can be used to operate on remote nodes. Plugins can provide CLI commands that will be discovered by CLI tools for explicitly enabled plugins.
RabbitMQ CLI tools require a compatible Erlang/OTP version to be installed.
The tools assume that system locale is a UTF-8 one (e.g. en_GB.UTF-8 or en_US.UTF-8). If that's not the case, the tools may still function correctly but it cannot be guaranteed. A warning will be emitted in non-UTF-8 locales.
Except for rabbitmqadmin, all of the tools above ship with RabbitMQ and can be found under the sbin directory in installation root. With most package types that directory is added to PATH at installation time. This means that core tools such as rabbitmq-diagnostics and rabbitmqctl are available on every node that has RabbitMQ installed.
Generic UNIX package users have to make sure that the sbin directory under installation root is added to PATH for simpler interactive use. Non-interactive use cases can use full or relative paths without modifications to the PATH environment variable.
rabbitmqadmin is a standalone tool (no dependencies other than Python 3) that can be downloaded from a running node or directly from GitHub.
If interaction from a remote node is required, download and extract the generic UNIX package or use the Windows installer.
Besides authentication, all configuration for core CLI tools is optional.
Commands that require specific arguments list them in the usage section and will report any missing arguments when executed.
To find out what commands are available, use the help command:
rabbitmqctl help
rabbitmq-diagnostics help
The command can display usage information for a particular command:
rabbitmq-diagnostics help status
Alternatively, the --help option can be used:
rabbitmqctl --help
including for individual commands:
rabbitmq-diagnostics status --help
rabbitmqctl is the original CLI tool that ships with RabbitMQ. It supports a wide range of operations, mostly administrative (operational) in nature.
This includes
and more.
rabbitmqctl uses a shared secret authentication mechanism (described below) with server nodes.
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 shared secret authentication (described below) with server nodes.
--offline is a flag supported by rabbitmq-plugins commands. When provided, the tool will avoid contacting the target node and instead operate on plugin files directly.
When the --offline flag is used, the command will rely on environment variables to determine where to find the plugins directory of the local node.
For example, it will respect and use the RABBITMQ_PLUGINS_DIR environment variable value just like a RabbitMQ node would. When RABBITMQ_PLUGINS_DIR is overriden for server nodes, it must also be set identically for the local OS user that invokes CLI tools.
With the exception of rabbitmqadmin, RabbitMQ tools use a shared secret authentication mechanism. This requires that inter-node and CLI communication ports (by default) is open for external connections on the target node.
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.
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.
If a system uses fully qualified domain names (FQDNs) for hostnames, RabbitMQ nodes and CLI tools must be configured to use so called long node names. For server nodes this is done by setting the RABBITMQ_USE_LONGNAME environment variable to true.
For CLI tools, either RABBITMQ_USE_LONGNAME must be set or the --longnames option must be specified:
# this example assumes that host1.messaging.eng.coolcorporation.banana is a hostname # that successfully resolves rabbitmq-diagnostics -n rabbit@host1.messaging.eng.coolcorporation.banana check_alarms --longnames
RabbitMQ CLI tools largely follow existing, long established command line argument parsing conventions. This section provides some examples and focuses on edge cases and lesser known features.
Different commands take different arguments. Some are named options such as --node (aliased as -n), others are positional arguments, such as the username and password arguments in
rabbitmqctl add_user <username> <password>
A specific example:
rabbitmqctl add_user "a-user" "a-pa$$w0rd"
Options can be provided before or after positional arguments with one exception: anything that follows a double hyphen (--) will be treated as positional arguments:
# all values after the double hyphen (--) will be treated as positional arguments, # even if they begin with a hyphen or a double hyphen rabbitmqctl add_user --node rabbit@host1.messaging.eng.coolcorporation.banana -- "a-user" "a-pa$$w0rd"
The explicit positional argument separator must be used when positional arguments begin with a hyphen or a double hyphen (such as generated passwords), to make sure they are not parsed as options:
# Since "--!a-pa$$w0rd" is explicitly provided as a positional argument, it won't # be mistakenly considered for an unsupported option, even though it starts with a double hyphen rabbitmqctl add_user --node rabbit@host1.messaging.eng.coolcorporation.banana -- "a-user" "--!a-pa$$w0rd"
Option values can be passed as --option <value> or --option=<value>. The latter variant must be used when the value begins with a hyphen (-), otherwise it would be treated as an option:
# an alternative way of providing an option value rabbitmqctl add_user --node=rabbit@host1.messaging.eng.coolcorporation.banana -- "a-user" "a-pa$$w0rd"
rabbitmqctl, rabbitmq-diagnostics, rabbitmq-plugins, and rabbitmq-queues support command aliases.
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.
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.
Docker community RabbitMQ image uses RABBITMQ_ERLANG_COOKIE environment variable value to populate the cookie file.
Configuration management and container orchestration tools that use this image must make sure that every RabbitMQ node container in a cluster uses the same value.
In the context of Kubernetes, the value must be specified in the deployment file. For instance, this can be seen in the RabbitMQ on Kubernetes examples repository.
On Windows, the cookie location depends on a few factors:
With Erlang versions starting with 20.2, the cookie file locations are:
If the Windows service is used, the cookie should be copied from C:\Windows\system32\config\systemprofile\.erlang.cookie to the expected location for users running commands like rabbitmqctl.bat.
As an alternative, the option "-setcookie <value>" can be added to RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS environment variable value to override the cookie value used by a RabbitMQ node:
RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS="-setcookie cookie-value"
CLI tools can take a cookie value using a command line flag:
rabbitmq-diagnostics status --erlang-cookie "cookie-value"
Both are the least secure options and generally not recommended.
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
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.
Starting with RabbitMQ 3.8.6, CLI tools provide two commands that help verify that hostname resolution on a node works as expected. The commands are not meant to replace dig and other specialised DNS tools but rather provide a way to perform most basic checks while taking Erlang runtime hostname resolver features into account.
The commands are covered in the Networking guide.
When the cookie is misconfigured (for example, not identical), RabbitMQ nodes will log errors such as "Connection attempt from disallowed node", "", "Could not auto-cluster".
For example, when a CLI tool connects and tries to authenticate using a mismatching secret value:
2020-06-15 13:03:33 [error] <0.1187.0> ** Connection attempt from node 'rabbitmqcli-99391-rabbit@warp10' rejected. Invalid challenge reply. **
When a CLI tool such as rabbitmqctl fails to authenticate with RabbitMQ, the message usually says
* epmd reports node 'rabbit' running on port 25672 * TCP connection succeeded but Erlang distribution failed * suggestion: hostname mismatch? * suggestion: is the cookie set correctly? * suggestion: is the Erlang distribution using TLS?
This means that TCP connection from a CLI tool to a RabbitMQ node succeeded but authentication attempt was rejected by the server. The message also mentions several most common reasons for that, which are covered next.
An incorrectly placed cookie file or cookie value mismatch are most common scenarios for such failures.
RabbitMQ node logs its cookie hash on start. CLI tools print their cookie hash value when they fail to authenticate with the target node.
When a recent Erlang/OTP version is used, authentication failures contain more information and cookie mismatches can be identified better:
rabbit@warp10: * connected to epmd (port 4369) on warp10 * epmd reports node 'rabbit' running on port 25672 * TCP connection succeeded but Erlang distribution failed * Authentication failed (rejected by the remote node), please check the Erlang cookie current node details: - node name: 'rabbitmq-cli-63@warp10' - home dir: /home/username - cookie hash: Sg08R8+G85EYHZ3H/9NUfg==
If RabbitMQ nodes are configured to use long node names (RABBITMQ_USE_LONGNAME is exported to true), so should CLI tools via the same environment variable or the --longnames command line flag introduced in 3.7.0.
If RabbitMQ is set up to encrypt inter-node and CLI connections using TLS, CLI tools also must use TLS and therefore require additional options. Non-TLS connections from other nodes and CLI tools will fail.
Other reasons include a hostname mismatch in node name used by the target RabbitMQ node and that provided to the CLI tool (e.g. via the -n flag). For example, if a node runs using rabbit@rmq1.eng.megacorp.local as its name but rabbitmqctl is invoked as
rabbitmq-diagnostics status -n rabbit@rmq-dev.eng.megacorp.local
then even if rmq-dev.eng.megacorp.local and rmq1.eng.megacorp.local resolve to the same IP address, the server will reject rabbitmqctl's authentication attempt. This scenario is relatively rare.
When a recent Erlang/OTP version is used, authentication failures contain more information and hostname mismatches can be identified better:
rabbit@localhost: * connected to epmd (port 4369) on localhost * epmd reports node 'rabbit' running on port 25672 * TCP connection succeeded but Erlang distribution failed * Hostname mismatch: node "rabbit@warp10" believes its host is different. Please ensure that hostnames resolve the same way locally and on "rabbit@warp10" current node details: - node name: 'rabbitmq-cli-30@warp10' - home dir: /Users/antares - cookie hash: Sg08R8+G85EYHZ3H/9NUfg==
Just like with any network connection, CLI-to-node connections can fail due to
and so on.
RabbitMQ Networking guide contains a section on troubleshooting of networking-related issues.
To retrieve node status, use rabbitmq-diagnostics status or rabbitmq-diagnostics.bat status with an optional --node target:
rabbitmq-diagnostics status
rabbitmq-diagnostics status --node rabbit@target-hostname.local
rabbitmq-diagnostics .bat status
rabbitmq-diagnostics .bat status --node rabbit@target-hostname.local
How RabbitMQ nodes are started depends on the package type used:
To stop a node, consider using the same service management tooling used when starting the node, which depends on the package typed used when RabbitMQ was installed.
To stop a node using RabbitMQ CLI tools, use rabbitmqctl shutdown or rabbitmqctl.bat shutdown with an optional --node target:
rabbitmqctl shutdown
rabbitmqctl shutdown --node rabbit@target-hostname.local
rabbitmqctl.bat shutdown
rabbitmqctl.bat shutdown --node rabbit@target-hostname.local
rabbitmqadmin is a command line tool that's built on top of RabbitMQ HTTP API. It is not a replacement for rabbitmqctl and provides access to a subset of most commonly performed operations provided by the management UI.
The tool requires Python 2.7.9 or a more recent version.
rabbitmqadmin uses HTTP API authentication mechanism (basic HTTP authentication). It has to be downloaded separately from a running node or GitHub.
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.
A RabbitMQ plugin can provide CLI commands that will be discovered by tools such as rabbitmq-diagnostics, rabbitmq-queues, rabbitmqctl, and others. For plugin commands to be discoverable, the plugin must be explicitly enabled.
When performing command discovery, CLI tools will consult the Enabled Plugins File to determine what plugins to scan for commands. If a plugin is not included into that file, e.g. because it was enabled implicitly as a dependency, it won't be listed in the enabled plugins file and thus its CLI commands will not be discovered and will not be available.
Use the help command to see what commands are available, both core and provided by plugins.
rabbitmqctl, rabbitmq-diagnostics and rabbitmq-plugins support command aliases. Aliases provide a way to define abbreviated versions of certain commands and their arguments. For example, instead of typing rabbitmqctl environment it may be more convenient to define an alias, rabbitmqctl env, that would expand to rabbitmqctl environment.
Aliases are loaded from a file specified via the RABBITMQ_CLI_ALIASES_FILE environment variable:
export RABBITMQ_CLI_ALIASES_FILE=/path/to/cli_aliases.conf
The aliases file uses a very minimalistic ini-style alias = command format, for example:
env = environment st = status --quiet lp = list_parameters --quiet lq = list_queues --quiet lu = list_users --quiet cs = cipher_suites --openssl-format --quiet
With this alias file in place it will be possible to use
rabbitmqctl env
which would expand to
rabbitmqctl environment
or
rabbitmqctl lq
which would expand to
rabbitmqctl list_queues --quiet
The last alias in the example above configures a rabbitmq-diagnostics command:
rabbitmq-diagnostics cs
would expand to
rabbitmq-diagnostics cipher_suites --openssl-format --quiet
All tools process aliases the same way. As long as the expanded command is recognized, aliases can be used with any tool or even more than one. For example, both rabbitmqctl and rabbitmq-diagnostics provide the environment command so the env alias works for both of them exactly the same way:
rabbitmq-diagnostics env
would expand to
rabbitmq-diagnostics environment
The file will be consulted only if the command invoked is not provided by the tool.
If you have questions about the contents of this guide or any other topic related to RabbitMQ, don't hesitate to ask them using GitHub Discussions or our community Discord server.
If you'd like to contribute an improvement to the site, its source is available on GitHub. Simply fork the repository and submit a pull request. Thank you!