2466 lines
75 KiB
Groff
2466 lines
75 KiB
Groff
.\" vim:ft=nroff:
|
|
.\" This Source Code Form is subject to the terms of the Mozilla Public
|
|
.\" License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
.\" file, You can obtain one at https://mozilla.org/MPL/2.0/.
|
|
.\"
|
|
.\" Copyright (c) 2007-2025 Broadcom. All Rights Reserved. The term “Broadcom” refers to Broadcom Inc. and/or its subsidiaries. All rights reserved.
|
|
.\"
|
|
.Dd June 22, 2023
|
|
.Dt RABBITMQCTL 8
|
|
.Os "RabbitMQ Server"
|
|
.Sh NAME
|
|
.Nm rabbitmqctl
|
|
.Nd tool for managing RabbitMQ nodes
|
|
.\" ------------------------------------------------------------------------------------------------
|
|
.Sh SYNOPSIS
|
|
.\" ------------------------------------------------------------------------------------------------
|
|
.Nm
|
|
.Op Fl q
|
|
.Op Fl s
|
|
.Op Fl l
|
|
.Op Fl n Ar node
|
|
.Op Fl t Ar timeout
|
|
.Ar command
|
|
.Op Ar command_options
|
|
.\" ------------------------------------------------------------------------------------------------
|
|
.Sh DESCRIPTION
|
|
.\" ------------------------------------------------------------------------------------------------
|
|
RabbitMQ is an open-source multi-protocol messaging broker.
|
|
.Pp
|
|
.Nm
|
|
is the main command line tool for managing a RabbitMQ server node,
|
|
together with
|
|
.Cm rabbitmq-diagnostics
|
|
,
|
|
.Cm rabbitmq-upgrade
|
|
, and others.
|
|
.Pp
|
|
It performs all actions by connecting to the target RabbitMQ node
|
|
on a dedicated CLI tool communication port and authenticating
|
|
using a shared secret (known as the cookie file).
|
|
.Pp
|
|
Diagnostic information is displayed if the connection failed,
|
|
the target node was not running, or
|
|
.Nm
|
|
could not authenticate to
|
|
the target node successfully.
|
|
|
|
To learn more, see the
|
|
.Lk https://www.rabbitmq.com/docs/cli "RabbitMQ CLI Tools guide"
|
|
.\" ------------------------------------------------------------------------------------------------
|
|
.Sh OPTIONS
|
|
.\" ------------------------------------------------------------------------------------------------
|
|
.Bl -tag -width Ds
|
|
.It Fl n Ar node
|
|
The default node is
|
|
.Qq Ar rabbit@target-hostname ,
|
|
where
|
|
.Ar target-hostname
|
|
is the local host.
|
|
On a host named
|
|
.Qq myserver.example.com ,
|
|
the node name will usually be
|
|
.Qq rabbit@myserver
|
|
(unless
|
|
.Ev RABBITMQ_NODENAME
|
|
has been overridden, in which case you'll need to use
|
|
.It Fl -longnames
|
|
).
|
|
The output of
|
|
.Qq hostname -s
|
|
is usually the correct hostname to use after the
|
|
.Qq @
|
|
sign.
|
|
See
|
|
.Xr rabbitmq-server 8
|
|
for details of configuring a RabbitMQ node.
|
|
.It Fl q , -quiet
|
|
Quiet output mode is selected.
|
|
Informational messages are reduced when quiet mode is in effect.
|
|
.It Fl s , -silent
|
|
Silent output mode is selected.
|
|
Informational messages are reduced and table headers are suppressed when silent mode is in effect.
|
|
.It Fl -no-table-headers
|
|
Do not output headers for tabular data.
|
|
.It Fl -dry-run
|
|
Do not run the command.
|
|
Only print informational messages.
|
|
.It Fl t Ar timeout , Fl -timeout Ar timeout
|
|
Operation timeout in seconds.
|
|
Not all commands support timeouts.
|
|
The default is
|
|
.Cm infinity .
|
|
.It Fl l , Fl -longnames
|
|
Must be specified when the cluster is configured to use long (FQDN) node names.
|
|
To learn more, see the
|
|
.Lk https://www.rabbitmq.com/docs/clustering "RabbitMQ Clustering guide"
|
|
.It Fl -erlang-cookie Ar cookie
|
|
Shared secret to use to authenticate to the target node.
|
|
Prefer using a local file or the
|
|
.Ev RABBITMQ_ERLANG_COOKIE
|
|
environment variable instead of specifying this option on the command line.
|
|
To learn more, see the
|
|
.Lk https://www.rabbitmq.com/docs/cli "RabbitMQ CLI Tools guide"
|
|
.El
|
|
.\" ------------------------------------------------------------------------------------------------
|
|
.Sh COMMANDS
|
|
.\" ------------------------------------------------------------------------------------------------
|
|
.Bl -tag -width Ds
|
|
.It Cm help Oo Fl l Oc Op Ar command_name
|
|
.Pp
|
|
Prints usage for all available commands.
|
|
.Bl -tag -width Ds
|
|
.It Fl l , Fl -list-commands
|
|
List command usages only, without parameter explanation.
|
|
.It Ar command_name
|
|
Prints usage for the specified command.
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm version
|
|
.Pp
|
|
Displays CLI tools version
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.\" ## Nodes
|
|
.\" ------------------------------------------------------------------
|
|
.Ss Nodes
|
|
.Bl -tag -width Ds
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm await_startup
|
|
.Pp
|
|
Waits for the RabbitMQ application to start on the target node
|
|
.Pp
|
|
For example, to wait for the RabbitMQ application to start:
|
|
.sp
|
|
.Dl rabbitmqctl await_startup
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm reset
|
|
.Pp
|
|
Returns a RabbitMQ node to its virgin state.
|
|
.Pp
|
|
Removes the node from any cluster it belongs to, removes all data from
|
|
the management database, such as configured users and vhosts, and
|
|
deletes all persistent messages.
|
|
.Pp
|
|
For
|
|
.Cm reset
|
|
and
|
|
.Cm force_reset
|
|
to succeed the RabbitMQ application must have been stopped, e.g. with
|
|
.Cm stop_app .
|
|
.Pp
|
|
For example, to reset the RabbitMQ node:
|
|
.sp
|
|
.Dl rabbitmqctl reset
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm rotate_logs
|
|
.Pp
|
|
Instructs the RabbitMQ node to perform internal log rotation.
|
|
.Pp
|
|
Log rotation is performed according to the logging settings specified in the configuration file.
|
|
The rotation operation is asynchronous, there is no guarantee that it will complete before this command returns.
|
|
.Pp
|
|
Note that there is no need to call this command in case of external log rotation (e.g. from logrotate(8)).
|
|
.Pp
|
|
For example, to initial log rotation:
|
|
.sp
|
|
.Dl rabbitmqctl rotate_logs
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm shutdown
|
|
.Pp
|
|
Shuts down the node, both RabbitMQ and its runtime.
|
|
The command is blocking and will return after the runtime process exits.
|
|
If RabbitMQ fails to stop, it will return a non-zero exit code.
|
|
This command infers the OS PID of the target node and
|
|
therefore can only be used to shut down nodes running on the same
|
|
host (or broadly speaking, in the same operating system,
|
|
e.g. in the same VM or container)
|
|
.Pp
|
|
Unlike the stop command, the shutdown command:
|
|
.Bl -bullet
|
|
.It
|
|
does not require a
|
|
.Ar pid_file
|
|
to wait for the runtime process to exit
|
|
.It
|
|
returns a non-zero exit code if the RabbitMQ node is not running
|
|
.El
|
|
.Pp
|
|
For example, this will shut down a local RabbitMQ node running with
|
|
the default node name:
|
|
.sp
|
|
.Dl rabbitmqctl shutdown
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm start_app
|
|
.Pp
|
|
Starts the RabbitMQ application.
|
|
.Pp
|
|
This command is typically run after performing other management actions
|
|
that require the RabbitMQ application to be stopped, e.g.\&
|
|
.Cm reset .
|
|
.Pp
|
|
For example, to instruct the RabbitMQ node to start the RabbitMQ
|
|
application:
|
|
.sp
|
|
.Dl rabbitmqctl start_app
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm stop Op Ar pid_file
|
|
.Pp
|
|
Stops the Erlang node on which RabbitMQ is running.
|
|
To restart the node follow the instructions for
|
|
.Qq Running the Server
|
|
in the
|
|
.Lk https://www.rabbitmq.com/docs/download installation guide .
|
|
.Pp
|
|
If a
|
|
.Ar pid_file
|
|
is specified, also waits for the process specified there to terminate.
|
|
See the description of the
|
|
.Cm wait
|
|
command for details on this file.
|
|
.Pp
|
|
For example, to instruct the RabbitMQ node to terminate:
|
|
.sp
|
|
.Dl rabbitmqctl stop
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm stop_app
|
|
.Pp
|
|
Stops the RabbitMQ application, leaving the runtime (Erlang VM) running.
|
|
.Pp
|
|
This command is typically run before performing other management
|
|
actions that require the RabbitMQ application to be stopped, e.g.\&
|
|
.Cm reset .
|
|
.Pp
|
|
For example, to instruct the RabbitMQ node to stop the RabbitMQ
|
|
application:
|
|
.sp
|
|
.Dl rabbitmqctl stop_app
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm wait Ar pid_file , Cm wait Fl -pid Ar pid
|
|
.Pp
|
|
Waits for the RabbitMQ application to start.
|
|
.Pp
|
|
This command will wait for the RabbitMQ application to start at the
|
|
node.
|
|
It will wait for the pid file to be created if
|
|
.Ar pidfile
|
|
is specified, then for a process with a pid specified in the pid file or
|
|
the
|
|
.Fl -pid
|
|
argument, and then for the RabbitMQ application to start in that process.
|
|
It will fail if the process terminates without starting the RabbitMQ
|
|
application.
|
|
.Pp
|
|
If the specified pidfile is not created or the erlang node is not started
|
|
within
|
|
.Fl -timeout
|
|
the command will fail.
|
|
The default timeout is 10 seconds.
|
|
.Pp
|
|
A suitable pid file is created by the
|
|
.Xr rabbitmq-server 8
|
|
script.
|
|
By default, this is located in the Mnesia directory.
|
|
Modify the
|
|
.Ev RABBITMQ_PID_FILE
|
|
environment variable to change the location.
|
|
.Pp
|
|
For example, this command will return when the RabbitMQ node has started
|
|
up:
|
|
.sp
|
|
.Dl rabbitmqctl wait /var/run/rabbitmq/pid
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.\" ## Cluster Operations
|
|
.\" ------------------------------------------------------------------
|
|
.Ss Cluster management
|
|
.Bl -tag -width Ds
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm await_online_nodes Ar count
|
|
.Pp
|
|
Waits for
|
|
.Ar count
|
|
nodes to join the cluster
|
|
.Pp
|
|
For example, to wait for two RabbitMQ nodes to start:
|
|
.sp
|
|
.Dl rabbitmqctl await_online_nodes 2
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm change_cluster_node_type Ar type
|
|
.Pp
|
|
Changes the type of the cluster node.
|
|
.Pp
|
|
The
|
|
.Ar type
|
|
must be one of the following:
|
|
.Bl -bullet -compact
|
|
.It
|
|
.Cm disc
|
|
.It
|
|
.Cm ram
|
|
.El
|
|
.Pp
|
|
The node must be stopped for this operation to succeed, and when turning
|
|
a node into a RAM node the node must not be the only disc node in the
|
|
cluster.
|
|
.Pp
|
|
For example, this command will turn a RAM node into a disc node:
|
|
.sp
|
|
.Dl rabbitmqctl change_cluster_node_type disc
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm cluster_status
|
|
.Pp
|
|
Displays all the nodes in the cluster grouped by node type, together
|
|
with the currently running nodes.
|
|
.Pp
|
|
For example, this command displays the nodes in the cluster:
|
|
.sp
|
|
.Dl rabbitmqctl cluster_status
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm force_boot
|
|
.Pp
|
|
Ensures that the node will start next time, even if it was not the last
|
|
to shut down.
|
|
.Pp
|
|
Normally when you shut down a RabbitMQ cluster altogether, the first
|
|
node you restart should be the last one to go down, since it may have
|
|
seen things happen that other nodes did not.
|
|
But sometimes that's not possible: for instance, if the entire cluster
|
|
loses power then all nodes may think they were not the last to shut
|
|
down.
|
|
.Pp
|
|
In such a case you can invoke
|
|
.Cm force_boot
|
|
while the node is down.
|
|
This will tell the node to unconditionally start the next time you ask
|
|
it.
|
|
Any changes to the cluster after this node shut down will be lost.
|
|
.Pp
|
|
If the last node to go down is permanently lost then you should use
|
|
.Cm forget_cluster_node Fl -offline
|
|
instead of this command, as it will ensure that mirrored queues
|
|
whose leader replica was on the lost node get promoted.
|
|
.Pp
|
|
For example, this will force the node not to wait for other nodes the
|
|
next time it is started:
|
|
.sp
|
|
.Dl rabbitmqctl force_boot
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm force_reset Em (deprecated)
|
|
.Pp
|
|
Forcefully returns a RabbitMQ node to its virgin state.
|
|
.Pp
|
|
The
|
|
.Cm force_reset
|
|
command differs from
|
|
.Cm reset
|
|
in that it resets the node unconditionally, regardless of the current
|
|
management database state and cluster configuration.
|
|
It should only be used as a last resort if the database or cluster
|
|
configuration has been corrupted.
|
|
.Pp
|
|
The
|
|
.Cm force_reset
|
|
command is
|
|
.Sy deprecated .
|
|
It remains available when the Mnesia metadata store is used.
|
|
It is unsupported with the Khepri metadata store.
|
|
.Pp
|
|
For
|
|
.Cm reset
|
|
and
|
|
.Cm force_reset
|
|
to succeed the RabbitMQ application must have been stopped, e.g. with
|
|
.Cm stop_app .
|
|
.Pp
|
|
For example, to reset the RabbitMQ node:
|
|
.sp
|
|
.Dl rabbitmqctl force_reset
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm forget_cluster_node Op Fl -offline
|
|
.Bl -tag -width Ds
|
|
.It Fl -offline
|
|
Enables node removal from an offline node.
|
|
This is only useful in the situation where all the nodes are offline and
|
|
the last node to go down cannot be brought online, thus preventing the
|
|
whole cluster from starting.
|
|
It should not be used in any other circumstances since it can lead to
|
|
inconsistencies.
|
|
.El
|
|
.Pp
|
|
Removes a cluster node remotely.
|
|
The node that is being removed must be offline, while the node we are
|
|
removing from must be online, except when using the
|
|
.Fl -offline
|
|
flag.
|
|
.Pp
|
|
When using the
|
|
.Fl -offline
|
|
flag ,
|
|
.Nm
|
|
will not attempt to connect to a node as normal; instead it will
|
|
temporarily become the node in order to make the change.
|
|
This is useful if the node cannot be started normally.
|
|
In this case, the node will become the canonical source for cluster
|
|
metadata (e.g. which queues exist), even if it was not before.
|
|
Therefore you should use this command on the latest node to shut down if
|
|
at all possible.
|
|
.Pp
|
|
For example, this command will remove the node
|
|
.Qq rabbit@stringer
|
|
from the node
|
|
.Qq hare@mcnulty :
|
|
.sp
|
|
.Dl rabbitmqctl -n hare@mcnulty forget_cluster_node rabbit@stringer
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm join_cluster Ar seed-node Op Fl -ram
|
|
.Bl -tag -width Ds
|
|
.It Ar seed-node
|
|
Existing cluster member (seed node) to cluster with.
|
|
.It Fl -ram
|
|
If provided, the node will join the cluster as a RAM node.
|
|
RAM node use is discouraged. Use only if you understand why
|
|
exactly you need to use them.
|
|
.El
|
|
.Pp
|
|
Instructs the node to become a member of the cluster that the specified
|
|
node is in.
|
|
Before clustering, the node is reset, so be careful when using this
|
|
command.
|
|
For this command to succeed the RabbitMQ application must have been
|
|
stopped, e.g. with
|
|
.Cm stop_app .
|
|
.Pp
|
|
Cluster nodes can be of two types: disc or RAM.
|
|
Disc nodes replicate data in RAM and on disk, thus providing redundancy
|
|
in the event of node failure and recovery from global events such as
|
|
power failure across all nodes.
|
|
RAM nodes replicate data in RAM only (except for queue contents, which
|
|
can reside on disk if the queue is persistent or too big to fit in
|
|
memory) and are mainly used for scalability.
|
|
RAM nodes are more performant only when managing resources (e.g.\&
|
|
adding/removing queues, exchanges, or bindings).
|
|
A cluster must always have at least one disc node and usually should
|
|
have more than one.
|
|
.Pp
|
|
The node will be a disc node by default.
|
|
If you wish to create a RAM node, provide the
|
|
.Fl -ram
|
|
flag.
|
|
.Pp
|
|
After executing the
|
|
.Cm join_cluster
|
|
command, whenever the RabbitMQ application is started on the current
|
|
node it will attempt to connect to the nodes that were in the cluster
|
|
when the node went down.
|
|
.Pp
|
|
To leave a cluster,
|
|
.Cm reset
|
|
the node.
|
|
You can also remove nodes remotely with the
|
|
.Cm forget_cluster_node
|
|
command.
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ node to join the cluster that
|
|
.Qq hare@elena
|
|
is part of, as a ram node:
|
|
.sp
|
|
.Dl rabbitmqctl join_cluster hare@elena --ram
|
|
.Pp
|
|
To learn more, see the
|
|
.Lk https://www.rabbitmq.com/docs/clustering "RabbitMQ Clustering guide".
|
|
.\" ------------------------------------------------------------------
|
|
.\" ## User management
|
|
.\" ------------------------------------------------------------------
|
|
.Ss User Management
|
|
Note that all user management commands
|
|
.Nm
|
|
only can manage users in the internal RabbitMQ database.
|
|
Users from any alternative authentication backends such as LDAP cannot be inspected
|
|
or managed with those commands.
|
|
.Nm .
|
|
.Bl -tag -width Ds
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm add_user Ar username Ar password
|
|
.Bl -tag -width Ds
|
|
.It Ar username
|
|
The name of the user to create.
|
|
.It Ar password
|
|
The password the created user will use to log in to the broker.
|
|
.El
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to create a (non-administrative) user named
|
|
.Qq janeway
|
|
with (initial) password
|
|
.Qq changeit :
|
|
.sp
|
|
.Dl rabbitmqctl add_user janeway changeit
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm authenticate_user Ar username Ar password
|
|
.Bl -tag -width Ds
|
|
.It Ar username
|
|
The name of the user.
|
|
.It Ar password
|
|
The password of the user.
|
|
.El
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to authenticate the user named
|
|
.Qq janeway
|
|
with the password
|
|
.Qq verifyit :
|
|
.sp
|
|
.Dl rabbitmqctl authenticate_user janeway verifyit
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm change_password Ar username Ar newpassword
|
|
.Bl -tag -width Ds
|
|
.It Ar username
|
|
The name of the user whose password is to be changed.
|
|
.It Ar newpassword
|
|
The new password for the user.
|
|
.El
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to change the
|
|
password for the user named
|
|
.Qq janeway
|
|
to
|
|
.Qq newpass :
|
|
.sp
|
|
.Dl rabbitmqctl change_password janeway newpass
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm clear_password Ar username
|
|
.Bl -tag -width Ds
|
|
.It Ar username
|
|
The name of the user whose password is to be cleared.
|
|
.El
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to clear the
|
|
password for the user named
|
|
.Qq janeway :
|
|
.sp
|
|
.Dl rabbitmqctl clear_password janeway
|
|
.Pp
|
|
This user now cannot log in with a password (but may be able to through
|
|
e.g. SASL EXTERNAL if configured).
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm hash_password Ar plaintext
|
|
.Bl -tag -width Ds
|
|
.It Ar plaintext
|
|
The plaintext password to hash
|
|
.El
|
|
.Pp
|
|
Hashes a plaintext password according to the currently configured password hashing algorithm
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm delete_user Ar username
|
|
.Bl -tag -width Ds
|
|
.It Ar username
|
|
The name of the user to delete.
|
|
.El
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to delete the user named
|
|
.Qq janeway :
|
|
.sp
|
|
.Dl rabbitmqctl delete_user janeway
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_users
|
|
.Pp
|
|
Lists users.
|
|
Each result row will contain the user name followed by a list of the
|
|
tags set for that user.
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to list all users:
|
|
.sp
|
|
.Dl rabbitmqctl list_users
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm set_user_tags Ar username Op Ar tag ...
|
|
.Bl -tag -width Ds
|
|
.It Ar username
|
|
The name of the user whose tags are to be set.
|
|
.It Ar tag
|
|
Zero, one or more tags to set.
|
|
Any existing tags will be removed.
|
|
.El
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to ensure the user named
|
|
.Qq janeway
|
|
is an administrator:
|
|
.sp
|
|
.Dl rabbitmqctl set_user_tags janeway administrator
|
|
.Pp
|
|
This has no effect when the user authenticates using a messaging protocol, but can be used to
|
|
permit the user to manage users, virtual hosts and permissions when
|
|
the user logs in via some other means (for example with the management
|
|
plugin).
|
|
.Pp
|
|
This command instructs the RabbitMQ broker to remove any tags from the user named
|
|
.Qq janeway :
|
|
.sp
|
|
.Dl rabbitmqctl set_user_tags janeway
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.\" ## Access Control
|
|
.\" ------------------------------------------------------------------
|
|
.Ss Access control
|
|
.Bl -tag -width Ds
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm clear_permissions Oo Fl p Ar vhost Oc Ar username
|
|
.Bl -tag -width Ds
|
|
.It Ar vhost
|
|
The name of the virtual host to which to deny the user access,
|
|
defaulting to
|
|
.Qq / .
|
|
.It Ar username
|
|
The name of the user to deny access to the specified virtual host.
|
|
.El
|
|
.Pp
|
|
Sets user permissions.
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to deny the user
|
|
named
|
|
.Qq janeway
|
|
access to the virtual host called
|
|
.Qq my-vhost :
|
|
.sp
|
|
.Dl rabbitmqctl clear_permissions -p my-vhost janeway
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm clear_topic_permissions Oo Fl p Ar vhost Oc Ar username Oo Ar exchange Oc
|
|
.Bl -tag -width Ds
|
|
.It Ar vhost
|
|
The name of the virtual host to which to clear the topic permissions,
|
|
defaulting to
|
|
.Qq / .
|
|
.It Ar username
|
|
The name of the user to clear topic permissions to the specified virtual host.
|
|
.It Ar exchange
|
|
The name of the topic exchange to clear topic permissions, defaulting to all the
|
|
topic exchanges the given user has topic permissions for.
|
|
.El
|
|
.Pp
|
|
Clear user topic permissions.
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to remove topic permissions
|
|
for the user named
|
|
.Qq janeway
|
|
for the topic exchange
|
|
.Qq amq.topic
|
|
in the virtual host called
|
|
.Qq my-vhost :
|
|
.sp
|
|
.Dl rabbitmqctl clear_topic_permissions -p my-vhost janeway amq.topic
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_permissions Op Fl p Ar vhost
|
|
.Bl -tag -width Ds
|
|
.It Ar vhost
|
|
The name of the virtual host for which to list the users that have been
|
|
granted access to it, and their permissions.
|
|
Defaults to
|
|
.Qq / .
|
|
.El
|
|
.Pp
|
|
Lists permissions in a virtual host.
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to list all the
|
|
users who have been granted access to the virtual host called
|
|
.Qq my-vhost ,
|
|
and the permissions they have for operations on resources in that
|
|
virtual host.
|
|
Note that an empty string means no permissions are granted:
|
|
.sp
|
|
.Dl rabbitmqctl list_permissions -p my-vhost
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_topic_permissions Op Fl p Ar vhost
|
|
.Bl -tag -width Ds
|
|
.It Ar vhost
|
|
The name of the virtual host for which to list the user's topic permissions.
|
|
Defaults to
|
|
.Qq / .
|
|
.El
|
|
.Pp
|
|
Lists topic permissions in a virtual host.
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to list all the
|
|
users who have been granted topic permissions in the virtual host called
|
|
.Qq my-vhost:
|
|
.sp
|
|
.Dl rabbitmqctl list_topic_permissions -p my-vhost
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_user_permissions Ar username
|
|
.Bl -tag -width Ds
|
|
.It Ar username
|
|
The name of the user for which to list the permissions.
|
|
.El
|
|
.Pp
|
|
Lists user permissions.
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to list all the
|
|
virtual hosts to which the user named
|
|
.Qq janeway
|
|
has been granted access, and the permissions the user has for operations
|
|
on resources in these virtual hosts:
|
|
.sp
|
|
.Dl rabbitmqctl list_user_permissions janeway
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_user_topic_permissions Ar username
|
|
.Bl -tag -width Ds
|
|
.It Ar username
|
|
The name of the user for which to list the topic permissions.
|
|
.El
|
|
.Pp
|
|
Lists user topic permissions.
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to list all the
|
|
virtual hosts to which the user named
|
|
.Qq janeway
|
|
has been granted access, and the topic permissions the user has in these virtual hosts:
|
|
.sp
|
|
.Dl rabbitmqctl list_user_topic_permissions janeway
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_vhosts Op Ar vhostinfoitem ...
|
|
.Pp
|
|
Lists virtual hosts.
|
|
.Pp
|
|
The
|
|
.Ar vhostinfoitem
|
|
parameter is used to indicate which virtual host information items to
|
|
include in the results.
|
|
The column order in the results will match the order of the parameters.
|
|
.Ar vhostinfoitem
|
|
can take any value from the list that follows:
|
|
.Bl -tag -width Ds
|
|
.It Cm name
|
|
The name of the virtual host with non-ASCII characters escaped as in C.
|
|
.It Cm tracing
|
|
Whether tracing is enabled for this virtual host.
|
|
.It Cm default_queue_type
|
|
Default queue type for this vhost.
|
|
.It Cm description
|
|
Virtual host description.
|
|
.It Cm tags
|
|
Virtual host tags.
|
|
.It Cm cluster_state
|
|
Virtual host state: nodedown, running, stopped.
|
|
.El
|
|
.Pp
|
|
If no
|
|
.Ar vhostinfoitem s
|
|
are specified then the vhost name is displayed.
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to list all
|
|
virtual hosts:
|
|
.sp
|
|
.Dl rabbitmqctl list_vhosts name tracing
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm set_permissions Oo Fl p Ar vhost Oc Ar user Ar conf Ar write Ar read
|
|
.Bl -tag -width Ds
|
|
.It Ar vhost
|
|
The name of the virtual host to which to grant the user access,
|
|
defaulting to
|
|
.Qq / .
|
|
.It Ar user
|
|
The name of the user to grant access to the specified virtual host.
|
|
.It Ar conf
|
|
A regular expression matching resource names for which the user is
|
|
granted configure permissions.
|
|
.It Ar write
|
|
A regular expression matching resource names for which the user is
|
|
granted write permissions.
|
|
.It Ar read
|
|
A regular expression matching resource names for which the user is
|
|
granted read permissions.
|
|
.El
|
|
.Pp
|
|
Sets user permissions.
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to grant the
|
|
user named
|
|
.Qq janeway
|
|
access to the virtual host called
|
|
.Qq my-vhost ,
|
|
with configured permissions on all resources whose names start with
|
|
.Qq janeway- ,
|
|
and write and read permissions on all resources:
|
|
.sp
|
|
.Dl rabbitmqctl set_permissions -p my-vhost janeway Qo ^janeway-.* Qc Qo .* Qc Qq .*
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm set_permissions_globally Ar username Ar conf Ar write Ar read
|
|
.Bl -tag -width Ds
|
|
.It Ar username
|
|
The name of the user to grant access to the specified virtual host.
|
|
.It Ar conf
|
|
A regular expression matching resource names for which the user is
|
|
granted configure permissions.
|
|
.It Ar write
|
|
A regular expression matching resource names for which the user is
|
|
granted write permissions.
|
|
.It Ar read
|
|
A regular expression matching resource names for which the user is
|
|
granted read permissions.
|
|
.El
|
|
.Pp
|
|
Sets user permissions in all vhosts.
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to grant the
|
|
user named
|
|
.Qq janeway
|
|
access to all virtual hosts with configure permissions on all resources whose names starts with
|
|
.Qq janeway- ,
|
|
and write and read permissions on all resources:
|
|
.sp
|
|
.Dl rabbitmqctl set_permissions_globally janeway Qo ^janeway-.* Qc Qo .* Qc Qq .*
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm set_topic_permissions Oo Fl p Ar vhost Oc Ar user Ar exchange Ar write Ar read
|
|
.Bl -tag -width Ds
|
|
.It Ar vhost
|
|
The name of the virtual host to which to grant the user access,
|
|
defaulting to
|
|
.Qq / .
|
|
.It Ar user
|
|
The name of the user the permissions apply to in the target virtual host.
|
|
.It Ar exchange
|
|
The name of the topic exchange to which the authorisation check will be applied.
|
|
.It Ar write
|
|
A regular expression matching the routing key of the published message.
|
|
.It Ar read
|
|
A regular expression matching the routing key of the consumed message.
|
|
.El
|
|
.Pp
|
|
Sets user topic permissions.
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to let the
|
|
user named
|
|
.Qq janeway
|
|
publish and consume messages going through the
|
|
.Qq amp.topic
|
|
exchange of the
|
|
.Qq my-vhost
|
|
virtual host with a routing key starting with
|
|
.Qq janeway- :
|
|
.sp
|
|
.Dl rabbitmqctl set_topic_permissions -p my-vhost janeway amq.topic Qo ^janeway-.* Qc Qo ^janeway-.* Qc
|
|
.Pp
|
|
Topic permissions support variable expansion for the following variables:
|
|
username, vhost, and client_id. Note that client_id is expanded only when using MQTT.
|
|
The previous example could be made more generic by using
|
|
.Qq ^{username}-.* :
|
|
.sp
|
|
.Dl rabbitmqctl set_topic_permissions -p my-vhost janeway amq.topic Qo ^{username}-.* Qc Qo ^{username}-.* Qc
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.\" ## Monitoring and Observability
|
|
.\" ------------------------------------------------------------------
|
|
.Ss Monitoring, observability and health checks
|
|
.Bl -tag -width Ds
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm environment
|
|
.Pp
|
|
Displays the name and value of each variable in the application
|
|
environment for each running application.
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_bindings Oo Fl p Ar vhost Oc Op Ar bindinginfoitem ...
|
|
.Pp
|
|
Returns binding details.
|
|
By default, the bindings for the
|
|
.Qq /
|
|
virtual host are returned.
|
|
The
|
|
.Fl p
|
|
flag can be used to override this default.
|
|
.Pp
|
|
The
|
|
.Ar bindinginfoitem
|
|
parameter is used to indicate which binding information items to include
|
|
in the results.
|
|
The column order in the results will match the order of the parameters.
|
|
.Ar bindinginfoitem
|
|
can take any value from the list that follows:
|
|
.Bl -tag -width Ds
|
|
.It Cm source_name
|
|
The name of the source of messages to which the binding is attached.
|
|
With non-ASCII characters escaped as in C.
|
|
.It Cm source_kind
|
|
The kind of the source of messages to which the binding is attached.
|
|
Currently always exchange.
|
|
With non-ASCII characters escaped as in C.
|
|
.It Cm destination_name
|
|
The name of the destination of messages to which the binding is
|
|
attached.
|
|
With non-ASCII characters escaped as in C.
|
|
.It Cm destination_kind
|
|
The kind of destination of messages to which the binding is attached.
|
|
With non-ASCII characters escaped as in C.
|
|
.It Cm routing_key
|
|
The binding's routing key with non-ASCII characters escaped as in C.
|
|
.It Cm arguments
|
|
The binding's arguments.
|
|
.El
|
|
.Pp
|
|
If no
|
|
.Ar bindinginfoitem s
|
|
are specified then all the above items are displayed.
|
|
.Pp
|
|
For example, this command displays the exchange name and queue name of
|
|
the bindings in the virtual host named
|
|
.Qq my-vhost
|
|
.sp
|
|
.Dl rabbitmqctl list_bindings -p my-vhost exchange_name queue_name
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_channels Op Ar channelinfoitem ...
|
|
.Pp
|
|
Returns information on all current channels, the logical containers
|
|
executing most AMQP commands.
|
|
This includes channels that are part of ordinary AMQP connections and
|
|
channels created by various plug-ins and other extensions.
|
|
.Pp
|
|
The
|
|
.Ar channelinfoitem
|
|
parameter is used to indicate which channel information items to include
|
|
in the results.
|
|
The column order in the results will match the order of the parameters.
|
|
.Ar channelinfoitem
|
|
can take any value from the list that follows:
|
|
.Bl -tag -width Ds
|
|
.It Cm pid
|
|
Id of the Erlang process associated with the connection.
|
|
.It Cm connection
|
|
Id of the Erlang process associated with the connection to which the
|
|
channel belongs.
|
|
.It Cm name
|
|
Readable name for the channel.
|
|
.It Cm number
|
|
The number of the channel uniquely identifying it within a
|
|
connection.
|
|
.It Cm user
|
|
The username associated with the channel.
|
|
.It Cm vhost
|
|
Virtual host in which the channel operates.
|
|
.It Cm transactional
|
|
True if the channel is in transactional mode, false otherwise.
|
|
.It Cm confirm
|
|
True if the channel is in confirm mode, false otherwise.
|
|
.It Cm consumer_count
|
|
The number of logical AMQP consumers retrieving messages via the channel.
|
|
.It Cm messages_unacknowledged
|
|
The number of messages delivered via this channel but not yet acknowledged.
|
|
.It Cm messages_uncommitted
|
|
The number of messages received in an as-yet uncommitted transaction.
|
|
.It Cm acks_uncommitted
|
|
The number of acknowledgements received in an as-yet uncommitted transaction.
|
|
.It Cm messages_unconfirmed
|
|
The number of not yet confirmed published messages.
|
|
On channels not in confirm mode, this remains 0.
|
|
.It Cm prefetch_count
|
|
QoS prefetch limit for new consumers, 0 if unlimited.
|
|
.El
|
|
.Pp
|
|
If no
|
|
.Ar channelinfoitem s
|
|
are specified then pid, user, consumer_count, and
|
|
messages_unacknowledged are assumed.
|
|
.Pp
|
|
For example, this command displays the connection process and count of
|
|
unacknowledged messages for each channel:
|
|
.sp
|
|
.Dl rabbitmqctl list_channels connection messages_unacknowledged
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_ciphers
|
|
.Pp
|
|
Lists cipher suites supported by encoding commands.
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to list all
|
|
cipher suites supported by encoding commands:
|
|
.sp
|
|
.Dl rabbitmqctl list_ciphers
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_connections Op Ar connectioninfoitem ...
|
|
.Pp
|
|
Returns TCP/IP connection statistics.
|
|
.Pp
|
|
The
|
|
.Ar connectioninfoitem
|
|
parameter is used to indicate which connection information items to
|
|
include in the results.
|
|
The column order in the results will match the order of the parameters.
|
|
.Ar connectioninfoitem
|
|
can take any value from the list that follows:
|
|
.Bl -tag -width Ds
|
|
.It Cm pid
|
|
Id of the Erlang process associated with the connection.
|
|
.It Cm name
|
|
Readable name for the connection.
|
|
.It Cm port
|
|
Server port.
|
|
.It Cm host
|
|
Server hostname obtained via reverse DNS, or its IP address if reverse
|
|
DNS failed or was turned off.
|
|
.It Cm peer_port
|
|
Peer port.
|
|
.It Cm peer_host
|
|
Peer hostname obtained via reverse DNS, or its IP address if reverse DNS
|
|
failed or was not enabled.
|
|
.It Cm ssl
|
|
Boolean indicating whether the connection is secured with SSL.
|
|
.It Cm ssl_protocol
|
|
SSL protocol (e.g.\&
|
|
.Qq tlsv1 ) .
|
|
.It Cm ssl_key_exchange
|
|
SSL key exchange algorithm (e.g.\&
|
|
.Qq rsa ) .
|
|
.It Cm ssl_cipher
|
|
SSL cipher algorithm (e.g.\&
|
|
.Qq aes_256_cbc ) .
|
|
.It Cm ssl_hash
|
|
SSL hash function (e.g.\&
|
|
.Qq sha ) .
|
|
.It Cm peer_cert_subject
|
|
The subject of the peer's SSL certificate in RFC4514 form.
|
|
.It Cm peer_cert_issuer
|
|
The issuer of the peer's SSL certificate, in RFC4514 form.
|
|
.It Cm peer_cert_validity
|
|
The period for which the peer's SSL certificate is valid.
|
|
.It Cm state
|
|
Connection state; one of:
|
|
.Bl -bullet -compact
|
|
.It
|
|
starting
|
|
.It
|
|
tuning
|
|
.It
|
|
opening
|
|
.It
|
|
running
|
|
.It
|
|
flow
|
|
.It
|
|
blocking
|
|
.It
|
|
blocked
|
|
.It
|
|
closing
|
|
.It
|
|
closed
|
|
.El
|
|
.It Cm channels
|
|
The number of channels using the connection.
|
|
.It Cm protocol
|
|
The version of the AMQP protocol in use -- currently one of:
|
|
.Bl -bullet -compact
|
|
.It
|
|
{0,9,1}
|
|
.It
|
|
{0,8,0}
|
|
.El
|
|
.Pp
|
|
Note that if a client requests an AMQP 0-9 connection, we treat it as
|
|
AMQP 0-9-1.
|
|
.It Cm auth_mechanism
|
|
SASL authentication mechanism used, such as
|
|
.Qq PLAIN .
|
|
.It Cm user
|
|
The username associated with the connection.
|
|
.It Cm vhost
|
|
Virtual hostname with non-ASCII characters escaped as in C.
|
|
.It Cm timeout
|
|
Connection timeout / negotiated heartbeat interval, in seconds.
|
|
.It Cm frame_max
|
|
Maximum frame size (bytes).
|
|
.It Cm channel_max
|
|
Maximum number of channels on this connection.
|
|
.It Cm client_properties
|
|
Informational properties transmitted by the client during connection
|
|
establishment.
|
|
.It Cm recv_oct
|
|
Octets received.
|
|
.It Cm recv_cnt
|
|
Packets received.
|
|
.It Cm send_oct
|
|
Octets send.
|
|
.It Cm send_cnt
|
|
Packets sent.
|
|
.It Cm send_pend
|
|
Send queue size.
|
|
.It Cm connected_at
|
|
Date and time this connection was established, as a timestamp.
|
|
.El
|
|
.Pp
|
|
If no
|
|
.Ar connectioninfoitem s
|
|
are specified then user, peer host, peer port, time since flow
|
|
control, and memory block state are displayed.
|
|
.Pp
|
|
For example, this command displays the send queue size and server port
|
|
for each connection:
|
|
.sp
|
|
.Dl rabbitmqctl list_connections send_pend port
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_consumers Op Fl p Ar vhost
|
|
.Pp
|
|
Lists consumers, i.e. subscriptions to a queue\'s message stream.
|
|
Each line printed shows, separated by tab characters, the name of
|
|
the queue subscribed to, the id of the channel process via which the
|
|
subscription was created and is managed, the consumer tag which uniquely
|
|
identifies the subscription within a channel, a boolean indicating
|
|
whether acknowledgements are expected for messages delivered to this
|
|
consumer, an integer indicating the prefetch limit (with 0 meaning
|
|
.Qq none ) ,
|
|
and any arguments for this consumer.
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_exchanges Oo Fl p Ar vhost Oc Op Ar exchangeinfoitem ...
|
|
.Pp
|
|
Returns exchange details.
|
|
Exchange details of the
|
|
.Qq /
|
|
virtual host are returned if the
|
|
.Fl p
|
|
flag is absent.
|
|
The
|
|
.Fl p
|
|
flag can be used to override this default.
|
|
.Pp
|
|
The
|
|
.Ar exchangeinfoitem
|
|
parameter is used to indicate which exchange information items to
|
|
include in the results.
|
|
The column order in the results will match the order of the parameters.
|
|
.Ar exchangeinfoitem
|
|
can take any value from the list that follows:
|
|
.Bl -tag -width Ds
|
|
.It Cm name
|
|
The name of the exchange with non-ASCII characters escaped as in C.
|
|
.It Cm type
|
|
The exchange type, such as:
|
|
.Bl -bullet -compact
|
|
.It
|
|
direct
|
|
.It
|
|
topic
|
|
.It
|
|
headers
|
|
.It
|
|
fanout
|
|
.El
|
|
.It Cm durable
|
|
Whether or not the exchange survives server restarts.
|
|
.It Cm auto_delete
|
|
Whether the exchange will be deleted automatically when no longer used.
|
|
.It Cm internal
|
|
Whether the exchange is internal, i.e. clients cannot publish to it
|
|
directly.
|
|
.It Cm arguments
|
|
Exchange arguments.
|
|
.It Cm policy
|
|
Policy name for applying to the exchange.
|
|
.El
|
|
.Pp
|
|
If no
|
|
.Ar exchangeinfoitem s
|
|
are specified then exchange name and type are displayed.
|
|
.Pp
|
|
For example, this command displays the name and type for each exchange
|
|
of the virtual host named
|
|
.Qq my-vhost :
|
|
.sp
|
|
.Dl rabbitmqctl list_exchanges -p my-vhost name type
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_hashes
|
|
.Pp
|
|
Lists hash functions supported by encoding commands.
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to list all hash
|
|
functions supported by encoding commands:
|
|
.sp
|
|
.Dl rabbitmqctl list_hashes
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_queues Oo Fl p Ar vhost Oc Oo Fl -offline | Fl -online | Fl -local Oc Op Ar queueinfoitem ...
|
|
.Pp
|
|
Returns queue details.
|
|
Queue details of the
|
|
.Qq /
|
|
virtual host are returned if the
|
|
.Fl p
|
|
flag is absent.
|
|
The
|
|
.Fl p
|
|
flag can be used to override this default.
|
|
.Pp
|
|
Displayed queues can be filtered by their status or location using one
|
|
of the following mutually exclusive options:
|
|
.Bl -tag -width Ds
|
|
.It Fl -offline
|
|
List only those durable queues that are not currently available (more
|
|
specifically, their leader node isn't).
|
|
.It Fl -online
|
|
List queues that are currently available (their leader node is).
|
|
.It Fl -local
|
|
List only those queues whose leader replica is located on the current
|
|
node.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ar queueinfoitem
|
|
parameter is used to indicate which queue information items to include
|
|
in the results.
|
|
The column order in the results will match the order of the parameters.
|
|
.Ar queueinfoitem
|
|
can take any value from the list that follows:
|
|
.Bl -tag -width Ds
|
|
.It Cm name
|
|
The name of the queue with non\-ASCII characters escaped as in C.
|
|
.It Cm durable
|
|
Whether or not the queue survives server restarts.
|
|
.It Cm auto_delete
|
|
Whether the queue will be deleted automatically when no longer used.
|
|
.It Cm arguments
|
|
Queue arguments.
|
|
.It Cm policy
|
|
Name of the user policy that is applied to the queue.
|
|
.It Cm operator_policy
|
|
Name of the operator policy that is applied to the queue.
|
|
.It Cm effective_policy_definition
|
|
Effective policy definition for the queue: both user and operator policy definitions merged.
|
|
.It Cm pid
|
|
Erlang process identifier of the queue.
|
|
.It Cm owner_pid
|
|
Id of the Erlang process of the connection which is the
|
|
exclusive owner of the queue.
|
|
Empty if the queue is non-exclusive.
|
|
.It Cm exclusive
|
|
True if the queue is exclusive (i.e. has owner_pid), false otherwise.
|
|
.It Cm exclusive_consumer_pid
|
|
Id of the Erlang process representing the channel of the exclusive
|
|
consumer subscribed to this queue.
|
|
Empty if there is no exclusive consumer.
|
|
.It Cm exclusive_consumer_tag
|
|
The consumer tag of the exclusive consumer subscribed to this queue.
|
|
Empty if there is no exclusive consumer.
|
|
.It Cm messages_ready
|
|
The number of messages ready to be delivered to clients.
|
|
.It Cm messages_unacknowledged
|
|
The number of messages delivered to clients but not yet acknowledged.
|
|
.It Cm messages
|
|
The sum of ready and unacknowledged messages (queue depth).
|
|
.It Cm messages_ready_ram
|
|
The number of messages from messages_ready which are resident in ram.
|
|
.It Cm messages_unacknowledged_ram
|
|
The number of messages from messages_unacknowledged which are resident in
|
|
ram.
|
|
.It Cm messages_ram
|
|
Total number of messages which are resident in ram.
|
|
.It Cm messages_persistent
|
|
Total number of persistent messages in the queue (will always be 0 for
|
|
transient queues).
|
|
.It Cm message_bytes
|
|
The sum of the size of all message bodies in the queue.
|
|
This does not include the message properties (including headers) or any
|
|
overhead.
|
|
.It Cm message_bytes_ready
|
|
Like
|
|
.Cm message_bytes
|
|
but counting only those messages ready to be delivered to clients.
|
|
.It Cm message_bytes_unacknowledged
|
|
Like
|
|
.Cm message_bytes
|
|
but counting only those messages delivered to clients but not yet
|
|
acknowledged.
|
|
.It Cm message_bytes_ram
|
|
Like
|
|
.Cm message_bytes
|
|
but counting only those messages that are currently held in RAM.
|
|
.It Cm message_bytes_persistent
|
|
Like
|
|
.Cm message_bytes
|
|
but counting only those messages which are persistent.
|
|
.It Cm head_message_timestamp
|
|
The timestamp property of the first message in the queue, if present.
|
|
Timestamps of messages only appear when they are in the paged-in state.
|
|
.It Cm disk_reads
|
|
Total number of times messages have been read from disk by this queue
|
|
since it started.
|
|
.It Cm disk_writes
|
|
Total number of times messages have been written to disk by this queue
|
|
since it started.
|
|
.It Cm consumers
|
|
The number of consumers.
|
|
.It Cm consumer_utilisation
|
|
Fraction of the time (between 0.0 and 1.0) that the queue is able to
|
|
immediately deliver messages to consumers.
|
|
This can be less than 1.0 if consumers are limited by network congestion
|
|
or prefetch count.
|
|
.It Cm memory
|
|
Bytes of memory allocated by the runtime for the
|
|
queue, including stack, heap, and internal structures.
|
|
.It Cm mirror_pids
|
|
If the queue is mirrored, this lists the IDs of the mirrors (follower replicas).
|
|
To learn more, see the
|
|
.Lk https://www.rabbitmq.com/docs/3.13/ha "RabbitMQ Mirroring guide"
|
|
.It Cm synchronised_mirror_pids
|
|
If the queue is mirrored, this gives the IDs of the mirrors (follower replicas) which
|
|
are in sync with the leader replica. To learn more, see the
|
|
.Lk https://www.rabbitmq.com/docs/3.13/ha "RabbitMQ Mirroring guide"
|
|
.It Cm state
|
|
The state of the queue.
|
|
Normally
|
|
.Qq running ,
|
|
but may be
|
|
.Qq Bro syncing, Ar message_count Brc
|
|
if the queue is synchronising.
|
|
.Pp
|
|
Queues that are located on cluster nodes that are currently down will
|
|
be shown with a status of
|
|
.Qq down
|
|
(and most other
|
|
.Ar queueinfoitem
|
|
will be unavailable).
|
|
.It Cm type
|
|
Queue type, one of: quorum, stream, classic.
|
|
.El
|
|
.Pp
|
|
If no
|
|
.Ar queueinfoitem s
|
|
are specified then queue name and depth are displayed.
|
|
.Pp
|
|
For example, this command displays the depth and number of consumers for
|
|
each queue of the virtual host named
|
|
.Qq my-vhost
|
|
.sp
|
|
.Dl rabbitmqctl list_queues -p my-vhost messages consumers
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_unresponsive_queues Oo Fl -local Oc Oo Fl -queue-timeout Ar seconds Oc Oo Ar queueinfoitem ... Oc Op Fl -no-table-headers
|
|
.Pp
|
|
Tests queue leader replicas to respond within the given timeout. Lists those that did not respond in time.
|
|
.Pp
|
|
Displayed queues can be filtered by their status or location using one
|
|
of the following mutually exclusive options:
|
|
.Bl -tag -width Ds
|
|
.It Fl -all
|
|
List all queues.
|
|
.It Fl -local
|
|
List only those queues whose leader replica is located on the current
|
|
node.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ar queueinfoitem
|
|
parameter is used to indicate which queue information items to include
|
|
in the results.
|
|
The column order in the results will match the order of the parameters.
|
|
.Ar queueinfoitem
|
|
can take any value from the list that follows:
|
|
.Bl -tag -width Ds
|
|
.It Cm name
|
|
The name of the queue with non\-ASCII characters escaped as in C.
|
|
.It Cm durable
|
|
Whether or not the queue should survive server restarts.
|
|
.It Cm auto_delete
|
|
Whether the queue will be deleted automatically when all of its explicit bindings are deleted.
|
|
.It Cm arguments
|
|
Queue arguments.
|
|
.It Cm policy
|
|
Effective policy name for the queue.
|
|
.It Cm pid
|
|
Erlang process identifier of the leader replica.
|
|
.It Cm recoverable_mirrors
|
|
Erlang process identifiers of the mirror replicas that are considered reachable (available).
|
|
.It Cm type
|
|
Queue type, one of: quorum, stream, classic.
|
|
.El
|
|
.Pp
|
|
For example, this command lists only those unresponsive queues whose leader replica
|
|
is hosted on the target node.
|
|
.Sp
|
|
.Dl rabbitmqctl list_unresponsive_queues --local name
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm ping
|
|
.Pp
|
|
Checks that the node OS process is up, registered with EPMD, and CLI tools can authenticate with it
|
|
.Pp
|
|
Example:
|
|
.Dl rabbitmqctl ping -n rabbit@hostname
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm report
|
|
.Pp
|
|
Generate a server status report containing a concatenation of all server
|
|
status information for support purposes.
|
|
The output should be redirected to a file when accompanying a support
|
|
request.
|
|
.Pp
|
|
For example, this command creates a server report which may be attached
|
|
to a support request email:
|
|
.sp
|
|
.Dl rabbitmqctl report > server_report.txt
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm schema_info Oo Fl -no-table-headers Oc Op Ar column ...
|
|
.Pp
|
|
Lists schema database tables and their properties
|
|
.Pp
|
|
For example, this command lists the table names and their active replicas:
|
|
.sp
|
|
.Dl rabbitmqctl schema_info name active_replicas
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm status
|
|
.Pp
|
|
Displays broker status information such as the running applications on
|
|
the current Erlang node, RabbitMQ and Erlang versions, OS name, and
|
|
memory and file descriptor statistics.
|
|
(See the
|
|
.Cm cluster_status
|
|
command to find out which nodes are clustered and running.)
|
|
.Pp
|
|
For example, this command displays information about the RabbitMQ
|
|
broker:
|
|
.sp
|
|
.Dl rabbitmqctl status
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.\" ## Runtime Parameters and Policies
|
|
.\" ------------------------------------------------------------------
|
|
.Ss Runtime Parameters and Policies
|
|
Certain features of RabbitMQ (such as the Federation plugin) are
|
|
controlled by dynamic, cluster-wide
|
|
.Em parameters.
|
|
There are 2 kinds of parameters: parameters scoped to a virtual host and
|
|
global parameters.
|
|
Each vhost-scoped parameter consists of a component name, a name, and a
|
|
value.
|
|
The component name and name are strings, and the value is a valid JSON document.
|
|
A global parameter consists of a name and value.
|
|
The name is a string and the value is an arbitrary Erlang data structure.
|
|
Parameters can be set, cleared, and listed.
|
|
In general, you should refer to the documentation for the feature in
|
|
question to see how to set parameters.
|
|
.Pp
|
|
Policies is a feature built on top of runtime parameters.
|
|
Policies are used to control and modify the behaviour of queues and
|
|
exchanges on a cluster-wide basis.
|
|
Policies apply within a given vhost and consist of a name, pattern,
|
|
definition, and an optional priority.
|
|
Policies can be set, cleared, and listed.
|
|
.Bl -tag -width Ds
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm clear_global_parameter Ar name
|
|
.Pp
|
|
Clears a global runtime parameter.
|
|
This is similar to
|
|
.Cm clear_parameter
|
|
but the key-value pair isn't tied to a virtual host.
|
|
.Bl -tag -width Ds
|
|
.It Ar name
|
|
The name of the global runtime parameter being cleared.
|
|
.El
|
|
.Pp
|
|
For example, this command clears the global runtime parameter
|
|
.Qq mqtt_default_vhosts :
|
|
.sp
|
|
.Dl rabbitmqctl clear_global_parameter mqtt_default_vhosts
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm clear_parameter Oo Fl p Ar vhost Oc Ar component_name Ar key
|
|
.Pp
|
|
Clears a parameter.
|
|
.Bl -tag -width Ds
|
|
.It Ar component_name
|
|
The name of the component for which the parameter is being cleared.
|
|
.It Ar name
|
|
The name of the parameter being cleared.
|
|
.El
|
|
.Pp
|
|
For example, this command clears the parameter
|
|
.Qq node01
|
|
for the
|
|
.Qq federation-upstream
|
|
component in the default virtual host:
|
|
.sp
|
|
.Dl rabbitmqctl clear_parameter federation-upstream node01
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_global_parameters
|
|
.Pp
|
|
Lists all global runtime parameters.
|
|
This is similar to
|
|
.Cm list_parameters
|
|
but the global runtime parameters are not tied to any virtual host.
|
|
.Pp
|
|
For example, this command lists all global parameters:
|
|
.sp
|
|
.Dl rabbitmqctl list_global_parameters
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_parameters Op Fl p Ar vhost
|
|
.Pp
|
|
Lists all parameters for a virtual host.
|
|
.Pp
|
|
For example, this command lists all parameters in the default virtual
|
|
host:
|
|
.sp
|
|
.Dl rabbitmqctl list_parameters
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm set_global_parameter Ar name Ar value
|
|
.Pp
|
|
Sets a global runtime parameter.
|
|
This is similar to
|
|
.Cm set_parameter
|
|
but the key-value pair isn't tied to a virtual host.
|
|
.Bl -tag -width Ds
|
|
.It Ar name
|
|
The name of the global runtime parameter being set.
|
|
.It Ar value
|
|
The value for the global runtime parameter, as a JSON document.
|
|
In most shells you are very likely to need to quote this.
|
|
.El
|
|
.Pp
|
|
For example, this command sets the global runtime parameter
|
|
.Qq mqtt_default_vhosts
|
|
to the JSON document {"O=client,CN=guest":"/"}:
|
|
.sp
|
|
.Dl rabbitmqctl set_global_parameter mqtt_default_vhosts '{"O=client,CN=guest":"/"}'
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm set_parameter Oo Fl p Ar vhost Oc Ar component_name Ar name Ar value
|
|
.Pp
|
|
Sets a parameter.
|
|
.Bl -tag -width Ds
|
|
.It Ar component_name
|
|
The name of the component for which the parameter is being set.
|
|
.It Ar name
|
|
The name of the parameter being set.
|
|
.It Ar value
|
|
The value for the parameter, as a JSON document.
|
|
In most shells you are very likely to need to quote this.
|
|
.El
|
|
.Pp
|
|
For example, this command sets the parameter
|
|
.Qq node01
|
|
for the
|
|
.Qq federation-upstream
|
|
component in the default virtual host to the following JSON
|
|
.Qq guest :
|
|
.sp
|
|
.Dl rabbitmqctl set_parameter federation-upstream node01 '{"uri":"amqp://user:password@server/%2F","ack-mode":"on-publish"}'
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_policies Op Fl p Ar vhost
|
|
.Pp
|
|
Lists all policies for a virtual host.
|
|
.Pp
|
|
For example, this command lists all policies in the default virtual
|
|
host:
|
|
.sp
|
|
.Dl rabbitmqctl list_policies
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm set_operator_policy Oo Fl p Ar vhost Oc Oo Fl -priority Ar priority Oc Oo Fl -apply-to Ar apply-to Oc Ar name Ar pattern Ar definition
|
|
.Pp
|
|
Sets an operator policy that overrides a subset of arguments in user
|
|
policies.
|
|
Arguments are identical to those of
|
|
.Cm set_policy .
|
|
.Pp
|
|
Supported arguments are:
|
|
.Bl -bullet -compact
|
|
.It
|
|
expires
|
|
.It
|
|
message-ttl
|
|
.It
|
|
max-length
|
|
.It
|
|
max-length-bytes
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm set_policy Oo Fl p Ar vhost Oc Oo Fl -priority Ar priority Oc Oo Fl -apply-to Ar apply-to Oc Ar name Ar pattern Ar definition
|
|
.Pp
|
|
Sets a policy.
|
|
.Bl -tag -width Ds
|
|
.It Ar name
|
|
The name of the policy.
|
|
.It Ar pattern
|
|
The regular expression allows the policy to apply if it matches a resource name.
|
|
.It Ar definition
|
|
The definition of the policy, as a JSON document.
|
|
In most shells you are very likely to need to quote this.
|
|
.It Ar priority
|
|
The priority of the policy as an integer.
|
|
Higher numbers indicate greater precedence.
|
|
The default is 0.
|
|
.It Ar apply-to
|
|
Which types of objects this policy should apply to.
|
|
Possible values are:
|
|
.Bl -bullet -compact
|
|
.It
|
|
queues (all queue types, including streams)
|
|
.It
|
|
classic_queues (classic queues only)
|
|
.It
|
|
quorum_queues (quorum queues only)
|
|
.It
|
|
streams (streams only)
|
|
.It
|
|
exchanges
|
|
.It
|
|
all
|
|
.El
|
|
The default is
|
|
.Cm all .
|
|
.El
|
|
.Pp
|
|
For example, this command sets the policy
|
|
.Qq federate-me
|
|
in the default virtual host so that built-in exchanges are federated:
|
|
.sp
|
|
.Dl rabbitmqctl set_policy federate-me "^amq." '{"federation-upstream-set":"all"}'
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm clear_policy Oo Fl p Ar vhost Oc Ar name
|
|
.Pp
|
|
Clears a policy.
|
|
.Bl -tag -width Ds
|
|
.It Ar name
|
|
The name of the policy being cleared.
|
|
.El
|
|
.Pp
|
|
For example, this command clears the
|
|
.Qq federate-me
|
|
policy in the default virtual host:
|
|
.sp
|
|
.Dl rabbitmqctl clear_policy federate-me
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm clear_operator_policy Oo Fl p Ar vhost Oc Ar name
|
|
.Pp
|
|
Clears an operator policy.
|
|
Arguments are identical to those of
|
|
.Cm clear_policy .
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_operator_policies Op Fl p Ar vhost
|
|
.Pp
|
|
Lists operator policy overrides for a virtual host.
|
|
Arguments are identical to those of
|
|
.Cm list_policies .
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.\" ## Virtual Host Management
|
|
.\" ------------------------------------------------------------------
|
|
.Ss Virtual hosts
|
|
Note that
|
|
.Nm
|
|
manages the RabbitMQ internal user database.
|
|
Permissions for users from any alternative authorisation backend will
|
|
not be visible to
|
|
.Nm .
|
|
.Bl -tag -width Ds
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm add_vhost Ar vhost Op Fl -description Ar desc Fl -tags Ar tags Fl -default-queue-type Ar default-q-type
|
|
.Bl -tag -width Ds
|
|
.It Ar vhost
|
|
The name of the virtual host entry to create.
|
|
.It Ar desc
|
|
Arbitrary virtual host description, e.g. its purpose, for the operator's
|
|
convenience.
|
|
.It Ar tags
|
|
A comma-separated list of virtual host tags for the operator's convenience.
|
|
.It Ar default-q-type
|
|
If clients do not specify queue type explicitly, this type will be used. One of: quorum, stream.
|
|
.El
|
|
.Pp
|
|
Creates a virtual host.
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to create a new
|
|
virtual host called
|
|
.Qq project9_dev_18 :
|
|
.Pp
|
|
.Dl rabbitmqctl add_vhost project9_dev_18 --description 'Dev environment no. 18' --tags "dev,project9"
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm clear_vhost_limits Op Fl p Ar vhost
|
|
.Pp
|
|
Clears virtual host limits.
|
|
.Pp
|
|
For example, this command clears vhost limits in vhost
|
|
.Qq qa_env :
|
|
.sp
|
|
.Dl rabbitmqctl clear_vhost_limits -p qa_env
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm delete_vhost Ar vhost
|
|
.Bl -tag -width Ds
|
|
.It Ar vhost
|
|
The name of the virtual host entry to delete.
|
|
.El
|
|
.Pp
|
|
Deletes a virtual host.
|
|
.Pp
|
|
Deleting a virtual host deletes all its exchanges, queues, bindings,
|
|
user permissions, parameters, and policies.
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to delete the
|
|
virtual host called
|
|
.Qq test :
|
|
.sp
|
|
.Dl rabbitmqctl delete_vhost a-vhost
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_vhost_limits Oo Fl p Ar vhost Oc Oo Fl -global Oc Op Fl -no-table-headers
|
|
.Pp
|
|
Displays configured virtual host limits.
|
|
.Bl -tag -width Ds
|
|
.It Fl -global
|
|
Show limits for all vhosts.
|
|
Suppresses the
|
|
.Fl p
|
|
parameter.
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm restart_vhost Oo Fl p Ar vhost Oc
|
|
.Bl -tag -width Ds
|
|
.It Ar vhost
|
|
The name of the virtual host entry to restart, defaulting to "/".
|
|
.El
|
|
.Pp
|
|
Restarts a failed vhost data stores and queues.
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to restart a
|
|
virtual host called
|
|
.Qq test :
|
|
.Pp
|
|
.Dl rabbitmqctl restart_vhost test
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm set_vhost_limits Oo Fl p Ar vhost Oc Ar definition
|
|
.Pp
|
|
Sets virtual host limits.
|
|
.Bl -tag -width Ds
|
|
.It Ar definition
|
|
The definition of the limits, as a JSON document.
|
|
In most shells you are very likely to need to quote this.
|
|
.Pp
|
|
Recognised limits are:
|
|
.Bl -bullet -compact
|
|
.It
|
|
max-connections
|
|
.It
|
|
max-queues
|
|
.El
|
|
.Pp
|
|
Use a negative value to specify "no limit".
|
|
.El
|
|
.Pp
|
|
For example, this command limits the maximum number of concurrent
|
|
connections in vhost
|
|
.Qq qa_env
|
|
to 64:
|
|
.sp
|
|
.Dl rabbitmqctl set_vhost_limits -p qa_env '{"max-connections": 64}'
|
|
.Pp
|
|
This command limits the maximum number of queues in vhost
|
|
.Qq qa_env
|
|
to 256:
|
|
.sp
|
|
.Dl rabbitmqctl set_vhost_limits -p qa_env '{"max-queues": 256}'
|
|
.Pp
|
|
This command clears the maximum number of connections limit in vhost
|
|
.Qq qa_env :
|
|
.sp
|
|
.Dl rabbitmqctl set_vhost_limits -p qa_env '{"max\-connections": \-1}'
|
|
.Pp
|
|
This command disables client connections in vhost
|
|
.Qq qa_env :
|
|
.sp
|
|
.Dl rabbitmqctl set_vhost_limits -p qa_env '{"max-connections": 0}'
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm set_user_limits Oc Ar username Oc Ar definition
|
|
.Pp
|
|
Sets user limits.
|
|
.Bl -tag -width Ds
|
|
.It Ar username
|
|
The name of the user to apply limits to
|
|
.It Ar definition
|
|
The definition of the limits, as a JSON document.
|
|
In most shells you are very likely to need to quote this.
|
|
.Pp
|
|
Recognised limits are:
|
|
.Bl -bullet -compact
|
|
.It
|
|
max-connections
|
|
.It
|
|
max-channels
|
|
.El
|
|
.Pp
|
|
Use a negative value to specify "no limit".
|
|
.El
|
|
.Pp
|
|
For example, this command limits the maximum number of concurrent
|
|
connections a user is allowed to open
|
|
.Qq limited_user
|
|
to 64:
|
|
.sp
|
|
.Dl rabbitmqctl set_user_limits limited_user '{"max-connections": 64}'
|
|
.Pp
|
|
This command limits the maximum number of channels a user is allowed to open
|
|
on a connection
|
|
.Qq limited_user
|
|
to 16:
|
|
.sp
|
|
.Dl rabbitmqctl set_user_limits limited_user '{"max-channels": 16}'
|
|
.Pp
|
|
This command clears the maximum number of connections limit for user
|
|
.Qq limited_user :
|
|
.sp
|
|
.Dl rabbitmqctl clear_user_limits limited_user 'max-connections'
|
|
.Pp
|
|
This command disables client connections for user
|
|
.Qq limited_user :
|
|
.sp
|
|
.Dl rabbitmqctl set_user_limits limited_user '{"max-connections": 0}'
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm clear_user_limits Oc Ar username Oc Ar limit
|
|
.Pp
|
|
Clears user limits.
|
|
.Bl -tag -width Ds
|
|
.It Ar username
|
|
The name of the user to clear the limits of
|
|
.It Ar limit
|
|
The name of the limit or "all" to clear all limits at once.
|
|
.El
|
|
.Pp
|
|
Recognised limits are:
|
|
.Bl -bullet -compact
|
|
.It
|
|
max-connections
|
|
.It
|
|
max-channels
|
|
.El
|
|
.Pp
|
|
For example, this command clears the maximum connection limits of user
|
|
.Qq limited_user :
|
|
.sp
|
|
.Dl rabbitmqctl clear_user_limits limited_user 'max-connections'
|
|
.Pp
|
|
This command clears all limits of user
|
|
.Qq limited_user :
|
|
.sp
|
|
.Dl rabbitmqctl clear_user_limits limited_user all
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm trace_off Op Fl p Ar vhost
|
|
.Bl -tag -width Ds
|
|
.It Ar vhost
|
|
The name of the virtual host for which to stop tracing.
|
|
.El
|
|
.Pp
|
|
Stops tracing.
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm trace_on Op Fl p Ar vhost
|
|
.Bl -tag -width Ds
|
|
.It Ar vhost
|
|
The name of the virtual host for which to start tracing.
|
|
.El
|
|
.Pp
|
|
Starts tracing.
|
|
Note that the trace state is not persistent; it will revert to being off
|
|
if the node is restarted.
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.\" ## Configuration
|
|
.\" ------------------------------------------------------------------
|
|
.Ss Configuration
|
|
.Bl -tag -width Ds
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm decode Ar value Ar passphrase Oo Fl -cipher Ar cipher Oc Oo Fl -hash Ar hash Oc Op Fl -iterations Ar iterations
|
|
.Bl -tag -width Ds
|
|
.It Ar value Ar passphrase
|
|
Value to decrypt (as produced by the encode command) and passphrase.
|
|
.Pp
|
|
For example:
|
|
.sp
|
|
.Dl rabbitmqctl decode '{encrypted, <<"...">>}' mypassphrase
|
|
.It Fl -cipher Ar cipher Fl -hash Ar hash Fl -iterations Ar iterations
|
|
Options to specify the decryption settings.
|
|
They can be used independently.
|
|
.Pp
|
|
For example:
|
|
.sp
|
|
.Dl rabbitmqctl decode --cipher blowfish_cfb64 --hash sha256 --iterations 10000 '{encrypted,<<"...">>} mypassphrase
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm encode Ar value Ar passphrase Oo Fl -cipher Ar cipher Oc Oo Fl -hash Ar hash Oc Op Fl -iterations Ar iterations
|
|
.Bl -tag -width Ds
|
|
.It Ar value Ar passphrase
|
|
Value to encrypt and passphrase.
|
|
.Pp
|
|
For example:
|
|
.sp
|
|
.Dl rabbitmqctl encode '<<"guest">>' mypassphrase
|
|
.It Fl -cipher Ar cipher Fl -hash Ar hash Fl -iterations Ar iterations
|
|
Options to specify the encryption settings.
|
|
They can be used independently.
|
|
.Pp
|
|
For example:
|
|
.sp
|
|
.Dl rabbitmqctl encode --cipher blowfish_cfb64 --hash sha256 --iterations 10000 '<<"guest">>' mypassphrase
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm set_cluster_name Ar name
|
|
.Pp
|
|
Sets the cluster name to
|
|
.Ar name .
|
|
The cluster name is announced to clients on connection, and used by the
|
|
federation and shovel plugins to record where a message has been.
|
|
The cluster name is by default derived from the hostname of the first
|
|
node in the cluster but can be changed.
|
|
.Pp
|
|
For example, this sets the cluster name to
|
|
.Qq london :
|
|
.sp
|
|
.Dl rabbitmqctl set_cluster_name london
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm set_disk_free_limit Ar disk_limit
|
|
.Bl -tag -width Ds
|
|
.It Ar disk_limit
|
|
Lower bound limit as an integer in bytes or a string with a memory unit
|
|
symbol (see vm_memory_high_watermark), e.g. 512M or 1G.
|
|
Once free disk space reaches the limit, a disk alarm will be set.
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm set_disk_free_limit mem_relative Ar fraction
|
|
.Bl -tag -width Ds
|
|
.It Ar fraction
|
|
Limit relative to the total amount available RAM as a non-negative
|
|
floating point number.
|
|
Values lower than 1.0 can be dangerous and should be used carefully.
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm set_log_level Op Ar log_level
|
|
.Pp
|
|
Sets log level in the running node
|
|
.Pp
|
|
Supported
|
|
.Ar log_level
|
|
values are:
|
|
.Bl -bullet -compact
|
|
.It
|
|
debug
|
|
.It
|
|
info
|
|
.It
|
|
warning
|
|
.It
|
|
error
|
|
.It
|
|
critical
|
|
.It
|
|
none
|
|
.El
|
|
.Pp
|
|
Example:
|
|
.Sp
|
|
.Dl rabbitmqctl set_log_level debug
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm set_vm_memory_high_watermark Ar fraction
|
|
.Bl -tag -width Ds
|
|
.It Ar fraction
|
|
The new memory threshold fraction at which flow control is triggered, as
|
|
a floating point number greater than or equal to 0.
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm set_vm_memory_high_watermark Oo absolute Oc Ar memory_limit
|
|
.Bl -tag -width Ds
|
|
.It Ar memory_limit
|
|
The new memory limit at which flow control is triggered, expressed in
|
|
bytes as an integer number greater than or equal to 0 or as a string
|
|
with memory unit symbol(e.g. 512M or 1G).
|
|
Available unit symbols are:
|
|
.Bl -tag -width Ds
|
|
.It Cm k , Cm kiB
|
|
kibibytes (2^10 bytes)
|
|
.It Cm M , Cm MiB
|
|
mebibytes (2^20 bytes)
|
|
.It Cm G , Cm GiB
|
|
gibibytes (2^30 bytes)
|
|
.It Cm kB
|
|
kilobytes (10^3 bytes)
|
|
.It Cm MB
|
|
megabytes (10^6 bytes)
|
|
.It Cm GB
|
|
gigabytes (10^9 bytes)
|
|
.El
|
|
.El
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.\" ## Feature Flags
|
|
.\" ------------------------------------------------------------------
|
|
.Ss Feature flags
|
|
.Bl -tag -width Ds
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm enable_feature_flag Ar feature_flag
|
|
.Pp
|
|
Enables a feature flag on the target node.
|
|
.Pp
|
|
Example:
|
|
.Sp
|
|
.Dl rabbitmqctl enable_feature_flag restart_streams
|
|
.Pp
|
|
You can also enable all feature flags by specifying "all":
|
|
.Sp
|
|
.Dl rabbitmqctl enable_feature_flag "all"
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_feature_flags Op Ar column ...
|
|
.Pp
|
|
Lists feature flags
|
|
.Pp
|
|
Supported
|
|
.Ar column
|
|
values are:
|
|
.Bl -bullet -compact
|
|
.It
|
|
name
|
|
.It
|
|
state
|
|
.It
|
|
stability
|
|
.It
|
|
provided_by
|
|
.It
|
|
desc
|
|
.It
|
|
doc_url
|
|
.El
|
|
.Pp
|
|
Example:
|
|
.Sp
|
|
.Dl rabbitmqctl list_feature_flags name state
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.\" ## Misc Operations
|
|
.\" ------------------------------------------------------------------
|
|
.Ss Connection Operations
|
|
.Bl -tag -width Ds
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm close_all_connections Oo Fl p Ar vhost Oc Oo Fl -global Oc Oo Fl -per-connection-delay Ar delay Oc Oo Fl -limit Ar limit Oc Ar explanation
|
|
.Bl -tag -width Ds
|
|
.It Fl p Ar vhost
|
|
The name of the virtual host for which connections should be closed.
|
|
Ignored when
|
|
.Fl -global
|
|
is specified.
|
|
.It Fl -global
|
|
If connections should be closed for all vhosts.
|
|
Overrides
|
|
.Fl p
|
|
.It Fl -per-connection-delay Ar delay
|
|
Time in milliseconds to wait after each connection closing.
|
|
.It Fl -limit Ar limit
|
|
The number of connections to close.
|
|
Only works per vhost.
|
|
Ignored when
|
|
.Fl -global
|
|
is specified.
|
|
.It Ar explanation
|
|
Explanation string.
|
|
.El
|
|
.Pp
|
|
Instructs the broker to close all connections for the specified vhost or entire RabbitMQ node.
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to close 10 connections on
|
|
.Qq qa_env
|
|
vhost, passing the explanation
|
|
.Qq Please close :
|
|
.sp
|
|
.Dl rabbitmqctl close_all_connections -p qa_env --limit 10 'Please close'
|
|
.Pp
|
|
This command instructs broker to close all connections to the node:
|
|
.sp
|
|
.Dl rabbitmqctl close_all_connections --global
|
|
.sp
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm close_connection Ar connectionpid Ar explanation
|
|
.Bl -tag -width Ds
|
|
.It Ar connectionpid
|
|
Id of the Erlang process associated with the connection to close.
|
|
.It Ar explanation
|
|
Explanation string.
|
|
.El
|
|
.Pp
|
|
Instructs the broker to close the connection associated with the Erlang
|
|
process id
|
|
.Ar connectionpid
|
|
(see also the
|
|
.Cm list_connections
|
|
command), passing the
|
|
.Ar explanation
|
|
string to the connected client as part of the AMQP connection shutdown
|
|
protocol.
|
|
.Pp
|
|
For example, this command instructs the RabbitMQ broker to close the connection associated with the Erlang process id
|
|
.Qq <rabbit@tanto.4262.0> ,
|
|
passing the explanation
|
|
.Qq go away
|
|
to the connected client:
|
|
.sp
|
|
.Dl rabbitmqctl close_connection Qo <rabbit@tanto.4262.0> Qc Qq go away
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.\" ## Misc
|
|
.\" ------------------------------------------------------------------
|
|
.Ss Misc
|
|
.Bl -tag -width Ds
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm eval Ar expression
|
|
.Pp
|
|
Evaluates an Erlang expression on the target node
|
|
.\" ------------------------------------------------------------------
|
|
.\" ## Queue Operations
|
|
.\" ------------------------------------------------------------------
|
|
.Ss Queue Operations
|
|
.Bl -tag -width Ds
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm delete_queue Ar queue_name Oo Fl -if-empty | Fl e Oc Op Fl -if-unused | Fl u
|
|
.Bl -tag -width Ds
|
|
.It Ar queue_name
|
|
The name of the queue to delete.
|
|
.It Ar --if-empty
|
|
Delete the queue if it is empty (has no messages ready for delivery)
|
|
.It Ar --if-unused
|
|
Delete the queue only if it has no consumers
|
|
.El
|
|
.Pp
|
|
Deletes a queue.
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm purge_queue Oo Fl p Ar vhost Oc Ar queue
|
|
.Bl -tag -width Ds
|
|
.It Ar queue
|
|
The name of the queue to purge.
|
|
.El
|
|
.Pp
|
|
Purges a queue (removes all messages in it).
|
|
.El
|
|
.\" ------------------------------------------------------------------------------------------------
|
|
.Sh PLUGIN COMMANDS
|
|
.\" ------------------------------------------------------------------------------------------------
|
|
RabbitMQ plugins can extend the rabbitmqctl tool to add new commands
|
|
when enabled.
|
|
Currently available commands can be found in the
|
|
.Cm rabbitmqctl help
|
|
output.
|
|
The following commands are added by RabbitMQ plugins, available in
|
|
the default distribution:
|
|
.\" ------------------------------------------------------------------
|
|
.\" ## Shovel
|
|
.\" ------------------------------------------------------------------
|
|
.Ss Shovel plugin
|
|
.Bl -tag -width Ds
|
|
.It Cm shovel_status
|
|
Prints a list of configured Shovels
|
|
.It Cm delete_shovel Oo Fl p Ar vhost Oc Ar name
|
|
Instructs the RabbitMQ node to delete the configured shovel by
|
|
.Ar name .
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.\" ## Federation
|
|
.\" ------------------------------------------------------------------
|
|
.Ss Federation plugin
|
|
.Bl -tag -width Ds
|
|
.It Cm federation_status Op Fl -only-down
|
|
Prints a list of federation links.
|
|
.Bl -tag -width Ds
|
|
.It Fl -only-down
|
|
Only list federation links that are not running.
|
|
.El
|
|
.It Cm restart_federation_link Ar link_id
|
|
Instructs the RabbitMQ node to restart the federation link with the
|
|
specified
|
|
.Ar link_id .
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.\" ## AMQP 1.0
|
|
.\" ------------------------------------------------------------------
|
|
.Ss AMQP 1.0 plugin
|
|
.Bl -tag -width Ds
|
|
.It Cm list_amqp10_connections Op Ar amqp10_connectioninfoitem ...
|
|
Similar to the
|
|
.Cm list_connections
|
|
command, but returns fields that make sense for AMQP-1.0 connections.
|
|
.Ar amqp10_connectioninfoitem
|
|
parameter is used to indicate which connection information items to
|
|
include in the results.
|
|
The column order in the results will match the order of the parameters.
|
|
.Ar amqp10_connectioninfoitem
|
|
can take any value from the list that follows:
|
|
.Bl -tag -width Ds
|
|
.It Cm pid
|
|
Id of the Erlang process associated with the connection.
|
|
.It Cm auth_mechanism
|
|
SASL authentication mechanism used, such as
|
|
.Qq PLAIN .
|
|
.It Cm host
|
|
Server hostname obtained via reverse DNS, or its IP address if reverse
|
|
DNS failed or was turned off.
|
|
.It Cm frame_max
|
|
Maximum frame size (bytes).
|
|
.It Cm timeout
|
|
Connection timeout / negotiated heartbeat interval, in seconds.
|
|
.It Cm user
|
|
Username associated with the connection.
|
|
.It Cm state
|
|
Connection state; one of:
|
|
.Bl -bullet -compact
|
|
.It
|
|
starting
|
|
.It
|
|
waiting_amqp0100
|
|
.It
|
|
securing
|
|
.It
|
|
running
|
|
.It
|
|
blocking
|
|
.It
|
|
blocked
|
|
.It
|
|
closing
|
|
.It
|
|
closed
|
|
.El
|
|
.It Cm recv_oct
|
|
Octets received.
|
|
.It Cm recv_cnt
|
|
Packets received.
|
|
.It Cm send_oct
|
|
Octets send.
|
|
.It Cm send_cnt
|
|
Packets sent.
|
|
.It Cm ssl
|
|
Boolean indicating whether the connection is secured with SSL.
|
|
.It Cm ssl_protocol
|
|
SSL protocol (e.g.\&
|
|
.Qq tlsv1 ) .
|
|
.It Cm ssl_key_exchange
|
|
SSL key exchange algorithm (e.g.\&
|
|
.Qq rsa ) .
|
|
.It Cm ssl_cipher
|
|
SSL cipher algorithm (e.g.\&
|
|
.Qq aes_256_cbc ) .
|
|
.It Cm ssl_hash
|
|
SSL hash function (e.g.\&
|
|
.Qq sha ) .
|
|
.It Cm peer_cert_subject
|
|
The subject of the peer's SSL certificate, in RFC4514 form.
|
|
.It Cm peer_cert_issuer
|
|
The issuer of the peer's SSL certificate, in RFC4514 form.
|
|
.It Cm peer_cert_validity
|
|
The period for which the peer's SSL certificate is valid.
|
|
.It Cm node
|
|
The node name of the RabbitMQ node to which the connection is
|
|
established.
|
|
.El
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.\" ## MQTT
|
|
.\" ------------------------------------------------------------------
|
|
.Ss MQTT plugin
|
|
.Bl -tag -width Ds
|
|
.It Cm list_mqtt_connections Op Ar mqtt_connectioninfoitem
|
|
Similar to the
|
|
.Cm list_connections
|
|
command, but returns fields that make sense for MQTT connections.
|
|
.Ar mqtt_connectioninfoitem
|
|
parameter is used to indicate which connection information items to
|
|
include in the results.
|
|
The column order in the results will match the order of the parameters.
|
|
.Ar mqtt_connectioninfoitem
|
|
can take any value from the list that follows:
|
|
.Bl -tag -width Ds
|
|
.It Cm host
|
|
Server hostname obtained via reverse DNS, or its IP address if reverse
|
|
DNS failed or was turned off.
|
|
.It Cm port
|
|
Server port.
|
|
.It Cm peer_host
|
|
Peer hostname obtained via reverse DNS, or its IP address if reverse DNS
|
|
failed or was not enabled.
|
|
.It Cm peer_port
|
|
Peer port.
|
|
.It Cm protocol
|
|
MQTT protocol version, which can be one of the following:
|
|
.Bl -bullet -compact
|
|
.It
|
|
{'MQTT', N/A}
|
|
.It
|
|
{'MQTT', 3.1.0}
|
|
.It
|
|
{'MQTT', 3.1.1}
|
|
.El
|
|
.It Cm channels
|
|
The number of channels using the connection.
|
|
.It Cm channel_max
|
|
Maximum number of channels on this connection.
|
|
.It Cm frame_max
|
|
Maximum frame size (bytes).
|
|
.It Cm client_properties
|
|
Informational properties transmitted by the client during connection
|
|
establishment.
|
|
.It Cm ssl
|
|
Boolean indicating whether the connection is secured with SSL.
|
|
.It Cm ssl_protocol
|
|
SSL protocol (e.g.\&
|
|
.Qq tlsv1 ) .
|
|
.It Cm ssl_key_exchange
|
|
SSL key exchange algorithm (e.g.\&
|
|
.Qq rsa ) .
|
|
.It Cm ssl_cipher
|
|
SSL cipher algorithm (e.g.\&
|
|
.Qq aes_256_cbc ) .
|
|
.It Cm ssl_hash
|
|
SSL hash function (e.g.\&
|
|
.Qq sha ) .
|
|
.It Cm conn_name
|
|
Readable name for the connection.
|
|
.It Cm connection_state
|
|
Connection state; one of:
|
|
.Bl -bullet -compact
|
|
.It
|
|
starting
|
|
.It
|
|
running
|
|
.It
|
|
blocked
|
|
.El
|
|
.It Cm connection
|
|
Id of the Erlang process associated with the internal amqp direct connection.
|
|
.It Cm consumer_tags
|
|
A tuple of consumer tags for QOS0 and QOS1.
|
|
.It Cm message_id
|
|
The last Packet ID sent in a control message.
|
|
.It Cm client_id
|
|
MQTT client identifier for the connection.
|
|
.It Cm clean_sess
|
|
MQTT clean session flag.
|
|
.It Cm will_msg
|
|
MQTT Will message sent in CONNECT frame.
|
|
.It Cm exchange
|
|
Exchange to route MQTT messages configured in rabbitmq_mqtt application environment.
|
|
.It Cm ssl_login_name
|
|
SSL peer cert auth name
|
|
.It Cm retainer_pid
|
|
Id of the Erlang process associated with retain storage for the connection.
|
|
.It Cm user
|
|
Username associated with the connection.
|
|
.It Cm vhost
|
|
Virtual host name with non-ASCII characters escaped as in C.
|
|
.El
|
|
.It Cm decommission_mqtt_node
|
|
Before the plugin is disabled on a node, or a node removed from the cluster,
|
|
it must be decommissioned.
|
|
.Pp
|
|
For example, this command will remove the node rabbit@stringer:
|
|
.sp
|
|
.Dl rabbitmqctl decommission_mqtt_node rabbit@stringer
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.\" ## STOMP
|
|
.\" ------------------------------------------------------------------
|
|
.Ss STOMP plugin
|
|
.Bl -tag -width Ds
|
|
.It Cm list_stomp_connections Op Ar stomp_connectioninfoitem
|
|
Similar to the
|
|
.Cm list_connections
|
|
command, but returns fields that make sense for STOMP connections.
|
|
.Ar stomp_connectioninfoitem
|
|
parameter is used to indicate which connection information items to
|
|
include in the results.
|
|
The column order in the results will match the order of the parameters.
|
|
.Ar stomp_connectioninfoitem
|
|
can take any value from the list that follows:
|
|
.Bl -tag -width Ds
|
|
.It Cm conn_name
|
|
Readable name for the connection.
|
|
.It Cm connection
|
|
Id of the Erlang process associated with the internal amqp direct connection.
|
|
.It Cm connection_state
|
|
Connection state; one of:
|
|
.Bl -bullet -compact
|
|
.It
|
|
running
|
|
.It
|
|
blocking
|
|
.It
|
|
blocked
|
|
.El
|
|
.It Cm session_id
|
|
STOMP protocol session identifier
|
|
.It Cm channel
|
|
AMQP channel associated with the connection
|
|
.It Cm version
|
|
Negotiated STOMP protocol version for the connection.
|
|
.It Cm implicit_connect
|
|
Indicates if the connection was established using implicit connect (without CONNECT frame)
|
|
.It Cm auth_login
|
|
Effective username for the connection.
|
|
.It Cm auth_mechanism
|
|
STOMP authorization mechanism.
|
|
Can be one of:
|
|
.Bl -bullet -compact
|
|
.It
|
|
config
|
|
.It
|
|
ssl
|
|
.It
|
|
stomp_headers
|
|
.El
|
|
.It Cm port
|
|
Server port.
|
|
.It Cm host
|
|
Server hostname obtained via reverse DNS, or its IP address if reverse
|
|
DNS failed or was not enabled.
|
|
.It Cm peer_port
|
|
Peer port.
|
|
.It Cm peer_host
|
|
Peer hostname obtained via reverse DNS, or its IP address if reverse DNS
|
|
failed or was not enabled.
|
|
.It Cm protocol
|
|
STOMP protocol version, which can be one of the following:
|
|
.Bl -bullet -compact
|
|
.It
|
|
{'STOMP', 0}
|
|
.It
|
|
{'STOMP', 1}
|
|
.It
|
|
{'STOMP', 2}
|
|
.El
|
|
.It Cm channels
|
|
The number of channels using the connection.
|
|
.It Cm channel_max
|
|
Maximum number of channels on this connection.
|
|
.It Cm frame_max
|
|
Maximum frame size (bytes).
|
|
.It Cm client_properties
|
|
Informational properties transmitted by the client during connection
|
|
.It Cm ssl
|
|
Boolean indicating whether the connection is secured with SSL.
|
|
.It Cm ssl_protocol
|
|
TLS protocol (e.g.\&
|
|
.Qq tlsv1 ) .
|
|
.It Cm ssl_key_exchange
|
|
TLS key exchange algorithm (e.g.\&
|
|
.Qq rsa ) .
|
|
.It Cm ssl_cipher
|
|
TLS cipher algorithm (e.g.\&
|
|
.Qq aes_256_cbc ) .
|
|
.It Cm ssl_hash
|
|
SSL hash function (e.g.\&
|
|
.Qq sha ) .
|
|
.El
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.\" ## Management Agent
|
|
.\" ------------------------------------------------------------------
|
|
.Ss Management agent plugin
|
|
.Bl -tag -width Ds
|
|
.It Cm reset_stats_db Op Fl -all
|
|
Reset the management stats database for the RabbitMQ node.
|
|
.Bl -tag -width Ds
|
|
.It Fl -all
|
|
Reset the stats database for all nodes in the cluster.
|
|
.El
|
|
.El
|
|
.\" ------------------------------------------------------------------------------------------------
|
|
.Sh SEE ALSO
|
|
.\" ------------------------------------------------------------------------------------------------
|
|
.Xr rabbitmq-diagnostics 8 ,
|
|
.Xr rabbitmq-plugins 8 ,
|
|
.Xr rabbitmq-server 8 ,
|
|
.Xr rabbitmq-queues 8 ,
|
|
.Xr rabbitmq-streams 8 ,
|
|
.Xr rabbitmq-upgrade 8 ,
|
|
.Xr rabbitmq-service 8 ,
|
|
.Xr rabbitmq-env.conf 5 ,
|
|
.Xr rabbitmq-echopid 8
|
|
.\" ------------------------------------------------------------------------------------------------
|
|
.Sh AUTHOR
|
|
.\" ------------------------------------------------------------------------------------------------
|
|
.An The RabbitMQ Team Aq Mt contact-tanzu-data.pdl@broadcom.com
|