rabbitmqctl

Display the status of the current node

$ rabbitmqctl status

$ tldr rabbitmqctl cluster

$ tldr rabbitmqctl users

$ tldr rabbitmqctl vhosts

$ rabbitmqctl help [command]

rabbitmqctl [GLOBAL_OPTIONS] <COMMAND> [COMMAND_OPTIONS/ARGUMENTS]

GLOBAL_OPTIONS: Options affecting rabbitmqctl itself, like target node, output format, or timeout.
COMMAND: The specific administrative action to perform (e.g., status, add_user, list_queues).
COMMAND_OPTIONS/ARGUMENTS: Arguments specific to the chosen command.

status
    Displays the status of the RabbitMQ node and application, including running applications, ports, and memory usage.

stop_app
    Stops the RabbitMQ application on the target node, but leaves the Erlang VM running. Essential before operations like reset.

start_app
    Starts the RabbitMQ application on a node where the Erlang VM is already running (e.g., after stop_app).

reset
    Resets a node to its virgin state, deleting all persistent data (queues, exchanges, bindings, users, vhosts). Requires the RabbitMQ application to be stopped first.

force_reset
    Force a node to reset its state without requiring the application to be stopped, potentially leading to data loss if not used carefully.

add_user
    Creates a new user with the specified username and password.

delete_user
    Deletes an existing user from the broker.

list_users
    Lists all configured users and their tags (e.g., administrator, management).

add_vhost
    Creates a new virtual host, which acts as a logical grouping for queues, exchanges, and bindings.

delete_vhost
    Deletes an existing virtual host and all its contents (queues, exchanges, messages).

list_vhosts
    Lists all configured virtual hosts.

set_permissions
    Sets permissions for a user on a specific virtual host, defining their access rights for configuration, writing, and reading.

list_permissions
    Lists all permissions for all users on all virtual hosts.

set_policy [priority] [apply-to]
    Defines a policy to apply specific configurations (e.g., high availability, message TTL) to queues or exchanges matching a given pattern within a vhost.

list_policies
    Lists all configured policies across all virtual hosts.

join_cluster
    Makes the current node join an existing cluster by connecting to an already running cluster node.

cluster_status
    Displays the status of the entire RabbitMQ cluster, including all participating nodes and their types (disk/RAM).

import_definitions
    Imports RabbitMQ definitions (users, vhosts, queues, exchanges, policies, etc.) from a JSON file, typically generated by export_definitions.

export_definitions
    Exports all RabbitMQ definitions from the broker into a JSON file, useful for backup or migration.

await_startup
    Waits until the RabbitMQ application has started successfully on the target node before exiting. Useful in scripting.

report
    Generates a comprehensive diagnostic report containing system information, logs, and RabbitMQ specifics, useful for troubleshooting.

rabbitmqctl is the primary command-line tool for administrating RabbitMQ, the popular open-source message broker. It provides a wide range of functionalities to interact with and control RabbitMQ nodes and clusters, including managing users, virtual hosts, permissions, policies, and node-level operations like starting, stopping, and resetting.

It communicates directly with the Erlang VM running the RabbitMQ application, allowing for real-time control and monitoring of the broker's state. This utility is essential for system administrators and developers alike to maintain, scale, and troubleshoot RabbitMQ deployments. Its commands cover everything from checking the health of a node or cluster to defining how messages are routed and consumed. Whether you're adding a new user, setting up a highly available queue, or debugging connection issues, rabbitmqctl is the primary interface for managing your RabbitMQ environment.

Most rabbitmqctl commands require the RabbitMQ Erlang node to be running for execution.

Many commands require administrative privileges on the host system or the RabbitMQ broker itself (e.g., a user with the administrator tag).

Improper use of destructive commands like reset, force_reset, delete_user, or delete_vhost can lead to permanent data loss or significant service disruption. Always back up definitions before major changes.

For successful clustering and inter-node communication, all RabbitMQ nodes and the rabbitmqctl command must share the same Erlang magic cookie.

RabbitMQ nodes are identified by Erlang node names (e.g., rabbit@hostname). rabbitmqctl by default attempts to connect to rabbit@ followed by the local hostname. This target node can be explicitly overridden using the -n <node> global option. Connectivity also relies on the Erlang Port Mapper Daemon (epmd) and correctly configured network ports.

For rabbitmqctl to communicate securely with a RabbitMQ node, both must share the same Erlang magic cookie (a secret string). This cookie is typically found in /var/lib/rabbitmq/.erlang.cookie or ~/.erlang.cookie. If the cookies differ, commands will fail with connection errors like 'could not connect to node 'rabbit@hostname''. Ensure consistent cookie files across all cluster nodes and for any administrative tools.

rabbitmqctl commands often need to be run as the rabbitmq user or root with appropriate permissions to access configuration files, logs, and interact with the running Erlang process. Incorrect permissions can prevent the tool from functioning correctly or connecting to the node.

RabbitMQ was first released in 2007 by Rabbit Technologies Ltd. rabbitmqctl has been an integral part of its administrative toolkit from early versions, evolving significantly with the broker to support new features, protocols (like AMQP 0-9-1, 1.0), and advanced clustering capabilities. Its reliance on Erlang's distributed capabilities means it interacts directly with the Erlang runtime on the RabbitMQ node, leveraging the language's strengths for robust distributed systems.

rabbitmq-plugins(8), rabbitmq-server(8), epmd(1), ss(8), netstat(8)