Как проверить rabbitmq linux

Command Line Tools

Overview

RabbitMQ ships with multiple command line tools:

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:

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

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.

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.

Installation

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.

Discovering Commands Using the Help Command

To find out what commands are available, use the help command:

The command can display usage information for a particular command:

Alternatively a —help option can be used:

including for individual commands:

rabbitmqctl

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

• 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

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

Authentication

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.

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@ 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:

Some commands, such as

can be used against any node. Others, such as

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 :

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:

Options and Positional Arguments

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

A specific example:

Options can be provided before or after positional arguments with one exception: anything that follows a double hyphen ( — ) will be treated as positional arguments:

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:

Option values can be passed as —option or —option= . The latter variant must be used when the value begins with a hyphen ( — ), otherwise it would be treated as an option:

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

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.

Community Docker Image and Kubernetes

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.

Windows

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

• Whether the HOMEDRIVE and HOMEPATH environment variables are both set
• Erlang version: prior to 20.2 (these are no longer supported by any maintained release series of RabbitMQ) or 20.2 and later

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 .

Overriding Using CLI and Runtime Command Line Arguments

As an alternative, the option » -setcookie » can be added to RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS environment variable value to override the cookie value used by a RabbitMQ node:

CLI tools can take a cookie value using a command line flag:

Both are the least secure options and generally not recommended.

Troubleshooting Cookie-based Authentication

CLI Tools

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

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

Server Nodes

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

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 .

Hostname Resolution

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.

Authentication Failures

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:

When a CLI tool such as rabbitmqctl fails to authenticate with RabbitMQ, the message usually says

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.

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:

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 rabbit@rmq1.eng.megacorp.local as its name but rabbitmqctl is invoked as

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:

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)

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:

The aliases file uses a very minimalistic ini-style alias = command format, for example:

With this alias file in place it will be possible to use

which would expand to

which would expand to

The last alias in the example above configures a rabbitmq-diagnostics command:

would expand to

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:

would expand to

The file will be consulted only if the command invoked is not provided by the tool.

Getting Help and Providing Feedback

If you have questions about the contents of this guide or any other topic related to RabbitMQ, don’t hesitate to ask them on the RabbitMQ mailing list.

Help Us Improve the Docs <3

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!

Источник