Skip to content

Latest commit

 

History

History
383 lines (265 loc) · 14.8 KB

cli.md

File metadata and controls

383 lines (265 loc) · 14.8 KB

Command Line Tools NOSYNTAX

RabbitMQ comes with multiple command line tools:

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.

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.

rabbitmqadmin is built on top of the HTTP API and uses a different mechanism, and only HTTP API port open.

rabbitmqctl, rabbitmq-diagnostics and rabbitmq-plugins support command aliases.

System and Environment Requirements

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.

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 shared secret authentication (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 shared secret authentication (described below) with server nodes.

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 management is best done using automation tools such as Chef, BOSH, Docker or similar.

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.

Windows

On Windows, the cookie location depends on a few factors:

  • Erlang version: prior to 20.2 or 20.2 and later
  • Whether the HOMEDRIVE and HOMEPATH environment variables are both set
Erlang 20.2 or later

With Erlang versions starting with 20.2, the cookie file locations are:

  • %HOMEDRIVE%%HOMEPATH%\.erlang.cookie (usually C:\Users\%USERNAME%\.erlang.cookie for user %USERNAME%) if both the HOMEDRIVE and HOMEPATH environment variables are set
  • %USERPROFILE%\.erlang.cookie (usually C:\Users\%USERNAME%\.erlang.cookie) if HOMEDRIVE and HOMEPATH are not both set
  • For the RabbitMQ Windows service - %USERPROFILE%\.erlang.cookie (usually C:\WINDOWS\system32\config\systemprofile)

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.

Erlang 19.3 through 20.2

With Erlang versions prior to 20.2, the cookie file locations are:

  • %HOMEDRIVE%%HOMEPATH%\.erlang.cookie (usually C:\Users\%USERNAME%\.erlang.cookie for user %USERNAME%) if both the HOMEDRIVE and HOMEPATH environment variables are set
  • %USERPROFILE%\.erlang.cookie (usually C:\Users\%USERNAME%\.erlang.cookie) if HOMEDRIVE and HOMEPATH are not both set
  • For the RabbitMQ Windows service - %WINDIR%\.erlang.cookie (usually C:\Windows\.erlang.cookie)

If the Windows service is used, the cookie should be copied from C:\Windows\.erlang.cookie to the expected location for users running commands like rabbitmqctl.bat.

Troubleshooting

When a node starts, it will log its home (base) directory location. Unless any server directories were overridden, that's the directory the cookie file will be created in by the RabbitMQ service.

Runtime Arguments

As an alternative, you can add the option "-setcookie <i>value</i>" in the RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS environment variable value:

RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS="-setcookie cookie-value"

This is the least secure option and generally not recommended.

Authentication Failures

When the cookie is misconfigured (for example, not identical), RabbitMQ will log errors such as "Connection attempt from disallowed node" and "Could not auto-cluster". 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 succeded but authentication attempt was rejected by the server. The message also mentions several most common reasons for that, which are covered next.

Possible Reason 1: Misplaced or Missing Cookie File

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==

Possible Reason 2: Node Name Type Mismatch

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.

Possible Reason 3: Inter-node Connections Require TLS

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.

Possible Reason 4: Hostname Mismatch

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 [email protected] as its name but rabbitmqctl is invoked as

rabbitmqctl status -n [email protected]

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==

Other Possible Reasons

Just like with any network connection, CLI-to-node connections can fail due to

  • Hostname resolution failures
  • Incorrect IP routing
  • TCP port access blocked (firewalls, etc)

and so on.

RabbitMQ Networking guide contains a section on troubleshooting of networking-related issues.

rabbitmqadmin

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.

"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.

Command Aliases

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 vary 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 both 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.