1RABBITMQCTL(8) BSD System Manager's Manual RABBITMQCTL(8)
2
4 rabbitmqctl — tool for managing RabbitMQ nodes
5
7 rabbitmqctl [-q] [-s] [-l] [-n node] [-t timeout] command
8 [command_options]
9
11 RabbitMQ is an open source multi-protocol messaging broker.
12 rabbitmqctl is the main command line tool for managing a RabbitMQ server
14 node, together with rabbitmq-diagnostics , rabbitmq-upgrade , and others.
15 It performs all actions by connecting to the target RabbitMQ node on a
17 dedicated CLI tool communication port and authenticating using a shared
18 secret (known as the cookie file).
19 Diagnostic information is displayed if connection failed, the target node
21 was not running, or rabbitmqctl could not authenticate to the target node
22 successfully.
23 To learn more, see the RabbitMQ CLI Tools guide:
25 https://rabbitmq.com/cli.html
26
28 -n node
29 Default node is "rabbit@target-hostname", where target-hostname
30 is the local host. On a host named "myserver.example.com", the
31 node name will usually be "rabbit@myserver" (unless
32 RABBITMQ_NODENAME has been overridden). The output of "hostname
33 -s" is usually the correct suffix to use after the "@" sign. See
34 rabbitmq-server(8) for details of configuring a RabbitMQ node.
35 -q, --quiet
37 Quiet output mode is selected. Informational messages are re‐
38 duced when quiet mode is in effect.
39 -s, --silent
41 Silent output mode is selected. Informational messages are re‐
42 duced and table headers are suppressed when silent mode is in ef‐
43 fect.
44 --no-table-headers
46 Do not output headers for tabular data.
47 --dry-run
49 Do not run the command. Only print information message.
50 -t timeout, --timeout timeout
52 Operation timeout in seconds. Not all commands support timeouts.
53 Default is infinity.
54 -l, --longnames
56 Must be specified when the cluster is configured to use long
57 (FQDN) node names. To learn more, see the RabbitMQ Clustering
58 guide: https://www.rabbitmq.com/clustering.html
59 --erlang-cookie cookie
61 Shared secret to use to authenticate to the target node. Prefer
62 using a local file or the RABBITMQ_ERLANG_COOKIE environment
63 variable instead of specifying this option on the command line.
64 To learn more, see the RabbitMQ CLI Tools guide:
65 https://www.rabbitmq.com/cli.html
66
68 help [-l] [command_name]
69 Prints usage for all available commands.
71 -l, --list-commands
73 List command usages only, without parameter explanation.
74 command_name
76 Prints usage for the specified command.
77 version
79 Displays CLI tools version
81 Nodes
83 await_startup
84 Waits for the RabbitMQ application to start on the target node
86 For example, to wait for the RabbitMQ application to start:
88 rabbitmqctl await_startup
90 reset
92 Returns a RabbitMQ node to its virgin state.
94 Removes the node from any cluster it belongs to, removes all data
96 from the management database, such as configured users and
97 vhosts, and deletes all persistent messages.
98 For reset and force_reset to succeed the RabbitMQ application
100 must have been stopped, e.g. with stop_app.
101 For example, to reset the RabbitMQ node:
103 rabbitmqctl reset
105 rotate_logs
107 Instructs the RabbitMQ node to perform internal log rotation.
109 Log rotation is performed according to the logging settings spec‐
111 ified in the configuration file. The rotation operation is asyn‐
112 chronous, there is no guarantee that it has completed when this
113 command returns.
114 Note that there is no need to call this command in case of exter‐
116 nal log rotation (e.g. from logrotate(8)).
117 For example, to initial log rotation:
119 rabbitmqctl rotate_logs
121 shutdown
123 Shuts down the node, both RabbitMQ and its runtime. The command
125 is blocking and will return after the runtime process exits. If
126 RabbitMQ fails to stop, it will return a non-zero exit code.
127 This command infers the OS PID of the target node and therefore
128 can only be used to shut down nodes running on the same host (or
129 broadly speaking, in the same operating system, e.g. in the same
130 VM or container)
131 Unlike the stop command, the shutdown command:
133 • does not require a pid_file to wait for the runtime process
135 to exit
136 • returns a non-zero exit code if RabbitMQ node is not running
138 For example, this will shut down a locally running RabbitMQ node
140 with default node name:
141 rabbitmqctl shutdown
143 start_app
145 Starts the RabbitMQ application.
147 This command is typically run after performing other management
149 actions that required the RabbitMQ application to be stopped,
150 e.g. reset.
151 For example, to instruct the RabbitMQ node to start the RabbitMQ
153 application:
154 rabbitmqctl start_app
156 stop [pid_file]
158 Stops the Erlang node on which RabbitMQ is running. To restart
160 the node follow the instructions for "Running the Server" in the
161 installation guide: https://rabbitmq.com/download.html
162 If a pid_file is specified, also waits for the process specified
164 there to terminate. See the description of the wait command for
165 details on this file.
166 For example, to instruct the RabbitMQ node to terminate:
168 rabbitmqctl stop
170 stop_app
172 Stops the RabbitMQ application, leaving the runtime (Erlang VM)
174 running.
175 This command is typically run prior to performing other manage‐
177 ment actions that require the RabbitMQ application to be stopped,
178 e.g. reset.
179 For example, to instruct the RabbitMQ node to stop the RabbitMQ
181 application:
182 rabbitmqctl stop_app
184 wait pid_file, wait --pid pid
186 Waits for the RabbitMQ application to start.
188 This command will wait for the RabbitMQ application to start at
190 the node. It will wait for the pid file to be created if pidfile
191 is specified, then for a process with a pid specified in the pid
192 file or the --pid argument, and then for the RabbitMQ application
193 to start in that process. It will fail if the process terminates
194 without starting the RabbitMQ application.
195 If the specified pidfile is not created or erlang node is not
197 started within --timeout the command will fail. Default timeout
198 is 10 seconds.
199 A suitable pid file is created by the rabbitmq-server(8) script.
201 By default this is located in the Mnesia directory. Modify the
202 RABBITMQ_PID_FILE environment variable to change the location.
203 For example, this command will return when the RabbitMQ node has
205 started up:
206 rabbitmqctl wait /var/run/rabbitmq/pid
208 Cluster management
210 await_online_nodes count
211 Waits for count nodes to join the cluster
213 For example, to wait for two RabbitMQ nodes to start:
215 rabbitmqctl await_online_nodes 2
217 change_cluster_node_type type
219 Changes the type of the cluster node.
221 The type must be one of the following:
223 • disc
224 • ram
225 The node must be stopped for this operation to succeed, and when
227 turning a node into a RAM node the node must not be the only disc
228 node in the cluster.
229 For example, this command will turn a RAM node into a disc node:
231 rabbitmqctl change_cluster_node_type disc
233 cluster_status
235 Displays all the nodes in the cluster grouped by node type, to‐
237 gether with the currently running nodes.
238 For example, this command displays the nodes in the cluster:
240 rabbitmqctl cluster_status
242 force_boot
244 Ensures that the node will start next time, even if it was not
246 the last to shut down.
247 Normally when you shut down a RabbitMQ cluster altogether, the
249 first node you restart should be the last one to go down, since
250 it may have seen things happen that other nodes did not. But
251 sometimes that's not possible: for instance if the entire cluster
252 loses power then all nodes may think they were not the last to
253 shut down.
254 In such a case you can invoke force_boot while the node is down.
256 This will tell the node to unconditionally start next time you
257 ask it to. If any changes happened to the cluster after this
258 node shut down, they will be lost.
259 If the last node to go down is permanently lost then you should
261 use forget_cluster_node --offline in preference to this command,
262 as it will ensure that mirrored queues which had their leader
263 replica on the lost node get promoted.
264 For example, this will force the node not to wait for other nodes
266 next time it is started:
267 rabbitmqctl force_boot
269 force_reset
271 Forcefully returns a RabbitMQ node to its virgin state.
273 The force_reset command differs from reset in that it resets the
275 node unconditionally, regardless of the current management data‐
276 base state and cluster configuration. It should only be used as
277 a last resort if the database or cluster configuration has been
278 corrupted.
279 For reset and force_reset to succeed the RabbitMQ application
281 must have been stopped, e.g. with stop_app.
282 For example, to reset the RabbitMQ node:
284 rabbitmqctl force_reset
286 forget_cluster_node [--offline]
288 --offline
290 Enables node removal from an offline node. This is only
291 useful in the situation where all the nodes are offline
292 and the last node to go down cannot be brought online,
293 thus preventing the whole cluster from starting. It
294 should not be used in any other circumstances since it
295 can lead to inconsistencies.
296 Removes a cluster node remotely. The node that is being removed
298 must be offline, while the node we are removing from must be on‐
299 line, except when using the --offline flag.
300 When using the --offline flag , rabbitmqctl will not attempt to
302 connect to a node as normal; instead it will temporarily become
303 the node in order to make the change. This is useful if the node
304 cannot be started normally. In this case the node will become
305 the canonical source for cluster metadata (e.g. which queues ex‐
306 ist), even if it was not before. Therefore you should use this
307 command on the latest node to shut down if at all possible.
308 For example, this command will remove the node "rabbit@stringer"
310 from the node "hare@mcnulty":
311 rabbitmqctl -n hare@mcnulty forget_cluster_node
313 rabbit@stringer
314 join_cluster seed-node [--ram]
316 seed-node
318 Existing cluster member (seed node) to cluster with.
319 --ram If provided, the node will join the cluster as a RAM
321 node. RAM node use is discouraged. Use only if you un‐
322 derstand why exactly you need to use them.
323 Instructs the node to become a member of the cluster that the
325 specified node is in. Before clustering, the node is reset, so
326 be careful when using this command. For this command to succeed
327 the RabbitMQ application must have been stopped, e.g. with
328 stop_app.
329 Cluster nodes can be of two types: disc or RAM. Disc nodes
331 replicate data in RAM and on disc, thus providing redundancy in
332 the event of node failure and recovery from global events such as
333 power failure across all nodes. RAM nodes replicate data in RAM
334 only (with the exception of queue contents, which can reside on
335 disc if the queue is persistent or too big to fit in memory) and
336 are mainly used for scalability. RAM nodes are more performant
337 only when managing resources (e.g. adding/removing queues, ex‐
338 changes, or bindings). A cluster must always have at least one
339 disc node, and usually should have more than one.
340 The node will be a disc node by default. If you wish to create a
342 RAM node, provide the --ram flag.
343 After executing the join_cluster command, whenever the RabbitMQ
345 application is started on the current node it will attempt to
346 connect to the nodes that were in the cluster when the node went
347 down.
348 To leave a cluster, reset the node. You can also remove nodes
350 remotely with the forget_cluster_node command.
351 For example, this command instructs the RabbitMQ node to join the
353 cluster that "hare@elena" is part of, as a ram node:
354 rabbitmqctl join_cluster hare@elena --ram
356 To learn more, see the RabbitMQ Clustering guide:
358 https://www.rabbitmq.com/clustering.html
359 rename_cluster_node oldnode1 newnode1 [oldnode2 newnode2 ...]
361 Supports renaming of cluster nodes in the local database.
363 This subcommand causes rabbitmqctl to temporarily become the node
365 in order to make the change. The local cluster node must there‐
366 fore be completely stopped; other nodes can be online or offline.
367 This subcommand takes an even number of arguments, in pairs rep‐
369 resenting the old and new names for nodes. You must specify the
370 old and new names for this node and for any other nodes that are
371 stopped and being renamed at the same time.
372 It is possible to stop all nodes and rename them all simultane‐
374 ously (in which case old and new names for all nodes must be
375 given to every node) or stop and rename nodes one at a time (in
376 which case each node only needs to be told how its own name is
377 changing).
378 For example, this command will rename the node
380 "rabbit@misshelpful" to the node "rabbit@cordelia"
381 rabbitmqctl rename_cluster_node rabbit@misshelpful
383 rabbit@cordelia
384 Note that this command only changes the local database. It may
386 also be necessary to rename the local database directories, and
387 to configure the new node name. For example:
388 1. Stop the node:
390 rabbitmqctl stop rabbit@misshelpful
392 2. Rename the node in the local database:
394 rabbitmqctl rename_cluster_node rabbit@misshelpful
396 rabbit@cordelia
397 3. Rename the local database directories (note, you do not need
399 to do this if you have set the RABBITMQ_MNESIA_DIR environ‐
400 ment variable):
401 mv \
403 /var/lib/rabbitmq/mnesia/rabbit\@misshelpful \
404 /var/lib/rabbitmq/mnesia/rabbit\@cordelia
405 mv \
406 /var/lib/rabbitmq/mnesia/rabbit\@misshelpful-rename \
407 /var/lib/rabbitmq/mnesia/rabbit\@cordelia-rename
408 mv \
409 /var/lib/rabbitmq/mnesia/rabbit\@misshelpful-plugins-expand \
410 /var/lib/rabbitmq/mnesia/rabbit\@cordelia-plugins-expand
411 4. If node name is configured e.g. using
413 /etc/rabbitmq/rabbitmq-env.conf it has also be updated
414 there.
415 5. Start the node when ready
417 update_cluster_nodes clusternode
419 clusternode
421 The node to consult for up-to-date information.
422 Instructs an already clustered node to contact clusternode to
424 cluster when booting up. This is different from join_cluster
425 since it does not join any cluster - it checks that the node is
426 already in a cluster with clusternode.
427 The need for this command is motivated by the fact that clusters
429 can change while a node is offline. Consider a situation where
430 node rabbit@A and rabbit@B are clustered. rabbit@A goes down,
431 rabbit@C clusters with rabbit@B, and then rabbit@B leaves the
432 cluster. When rabbit@A starts back up, it'll try to contact
433 rabbit@B, but this will fail since rabbit@B is not in the cluster
434 anymore. The following command will rename node rabbit@B to
435 rabbit@C on node rabbitA
436 update_cluster_nodes -n rabbit@A rabbit@B rabbit@C
438 To learn more, see the RabbitMQ Clustering guide:
440 https://www.rabbitmq.com/clustering.html
441 Replication
443 sync_queue [-p vhost] queue
444 queue The name of the queue to synchronise.
446 Instructs a mirrored queue with unsynchronised mirrors (follower
448 replicas) to synchronise them. The queue will block while syn‐
449 chronisation takes place (all publishers to and consumers using
450 the queue will block or temporarily see no activity). This com‐
451 mand can only be used with mirrored queues. To learn more, see
452 the RabbitMQ Mirroring guide: https://www.rabbitmq.com/ha.html
453 Note that queues with unsynchronised replicas and active con‐
455 sumers will become synchronised eventually (assuming that con‐
456 sumers make progress). This command is primarily useful for
457 queues which do not have active consumers.
458 cancel_sync_queue [-p vhost] queue
460 queue The name of the queue to cancel synchronisation for.
462 Instructs a synchronising mirrored queue to stop synchronising
464 itself.
465 User Management
467 Note that all user management commands rabbitmqctl only can manage users
468 in the internal RabbitMQ database. Users from any alternative authenti‐
469 cation backends such as LDAP cannot be inspected or managed with those
470 commands. rabbitmqctl.
471 add_user username password
473 username
475 The name of the user to create.
476 password
478 The password the created user will use to log in to the
479 broker.
480 For example, this command instructs the RabbitMQ broker to create
482 a (non-administrative) user named "janeway" with (initial) pass‐
483 word "changeit":
484 rabbitmqctl add_user janeway changeit
486 authenticate_user username password
488 username
490 The name of the user.
491 password
493 The password of the user.
494 For example, this command instructs the RabbitMQ broker to au‐
496 thenticate the user named "janeway" with password "verifyit":
497 rabbitmqctl authenticate_user janeway verifyit
499 change_password username newpassword
501 username
503 The name of the user whose password is to be changed.
504 newpassword
506 The new password for the user.
507 For example, this command instructs the RabbitMQ broker to change
509 the password for the user named "janeway" to "newpass":
510 rabbitmqctl change_password janeway newpass
512 clear_password username
514 username
516 The name of the user whose password is to be cleared.
517 For example, this command instructs the RabbitMQ broker to clear
519 the password for the user named "janeway":
520 rabbitmqctl clear_password janeway
522 This user now cannot log in with a password (but may be able to
524 through e.g. SASL EXTERNAL if configured).
525 hash_password plaintext
527 plaintext
529 The plaintext password to hash
530 Hashes a plaintext password according to the currently configured
532 password hashing algorithm
533 delete_user username
535 username
537 The name of the user to delete.
538 For example, this command instructs the RabbitMQ broker to delete
540 the user named "janeway":
541 rabbitmqctl delete_user janeway
543 list_users
545 Lists users. Each result row will contain the user name followed
547 by a list of the tags set for that user.
548 For example, this command instructs the RabbitMQ broker to list
550 all users:
551 rabbitmqctl list_users
553 set_user_tags username [tag ...]
555 username
557 The name of the user whose tags are to be set.
558 tag Zero, one or more tags to set. Any existing tags will be
560 removed.
561 For example, this command instructs the RabbitMQ broker to ensure
563 the user named "janeway" is an administrator:
564 rabbitmqctl set_user_tags janeway administrator
566 This has no effect when the user authenticates using a messaging
568 protocol, but can be used to permit the user to manage users,
569 virtual hosts and permissions when the user logs in via some
570 other means (for example with the management plugin).
571 This command instructs the RabbitMQ broker to remove any tags
573 from the user named "janeway":
574 rabbitmqctl set_user_tags janeway
576 Access control
578 clear_permissions [-p vhost] username
579 vhost The name of the virtual host to which to deny the user
581 access, defaulting to "/".
582 username
584 The name of the user to deny access to the specified vir‐
585 tual host.
586 Sets user permissions.
588 For example, this command instructs the RabbitMQ broker to deny
590 the user named "janeway" access to the virtual host called
591 "my-vhost":
592 rabbitmqctl clear_permissions -p my-vhost janeway
594 clear_topic_permissions [-p vhost] username [exchange]
596 vhost The name of the virtual host to which to clear the topic
598 permissions, defaulting to "/".
599 username
601 The name of the user to clear topic permissions to the
602 specified virtual host.
603 exchange
605 The name of the topic exchange to clear topic permis‐
606 sions, defaulting to all the topic exchanges the given
607 user has topic permissions for.
608 Clear user topic permissions.
610 For example, this command instructs the RabbitMQ broker to remove
612 topic permissions for user named "janeway" for the topic exchange
613 "amq.topic" in the virtual host called "my-vhost":
614 rabbitmqctl clear_topic_permissions -p my-vhost janeway
616 amq.topic
617 list_permissions [-p vhost]
619 vhost The name of the virtual host for which to list the users
621 that have been granted access to it, and their permis‐
622 sions. Defaults to "/".
623 Lists permissions in a virtual host.
625 For example, this command instructs the RabbitMQ broker to list
627 all the users which have been granted access to the virtual host
628 called "my-vhost", and the permissions they have for operations
629 on resources in that virtual host. Note that an empty string
630 means no permissions granted:
631 rabbitmqctl list_permissions -p my-vhost
633 list_topic_permissions [-p vhost]
635 vhost The name of the virtual host for which to list the users
637 topic permissions. Defaults to "/".
638 Lists topic permissions in a virtual host.
640 For example, this command instructs the RabbitMQ broker to list
642 all the users which have been granted topic permissions in the
643 virtual host called "my-vhost:"
644 rabbitmqctl list_topic_permissions -p my-vhost
646 list_user_permissions username
648 username
650 The name of the user for which to list the permissions.
651 Lists user permissions.
653 For example, this command instructs the RabbitMQ broker to list
655 all the virtual hosts to which the user named "janeway" has been
656 granted access, and the permissions the user has for operations
657 on resources in these virtual hosts:
658 rabbitmqctl list_user_permissions janeway
660 list_user_topic_permissions username
662 username
664 The name of the user for which to list the topic permis‐
665 sions.
666 Lists user topic permissions.
668 For example, this command instructs the RabbitMQ broker to list
670 all the virtual hosts to which the user named "janeway" has been
671 granted access, and the topic permissions the user has in these
672 virtual hosts:
673 rabbitmqctl list_user_topic_permissions janeway
675 list_vhosts [vhostinfoitem ...]
677 Lists virtual hosts.
679 The vhostinfoitem parameter is used to indicate which virtual
681 host information items to include in the results. The column or‐
682 der in the results will match the order of the parameters.
683 vhostinfoitem can take any value from the list that follows:
684 name The name of the virtual host with non-ASCII characters
686 escaped as in C.
687 tracing
689 Whether tracing is enabled for this virtual host.
690 default_queue_type
692 Default queue type for this vhost.
693 description
695 Virtual host description.
696 tags Virtual host tags.
698 cluster_state
700 Virtual host state: nodedown, running, stopped.
701 If no vhostinfoitem are specified then the vhost name is dis‐
703 played.
704 For example, this command instructs the RabbitMQ broker to list
706 all virtual hosts:
707 rabbitmqctl list_vhosts name tracing
709 set_permissions [-p vhost] user conf write read
711 vhost The name of the virtual host to which to grant the user
713 access, defaulting to "/".
714 user The name of the user to grant access to the specified
716 virtual host.
717 conf A regular expression matching resource names for which
719 the user is granted configure permissions.
720 write A regular expression matching resource names for which
722 the user is granted write permissions.
723 read A regular expression matching resource names for which
725 the user is granted read permissions.
726 Sets user permissions.
728 For example, this command instructs the RabbitMQ broker to grant
730 the user named "janeway" access to the virtual host called
731 "my-vhost", with configure permissions on all resources whose
732 names starts with "janeway-", and write and read permissions on
733 all resources:
734 rabbitmqctl set_permissions -p my-vhost janeway
736 "^janeway-.*" ".*" ".*"
737 set_topic_permissions [-p vhost] user exchange write read
739 vhost The name of the virtual host to which to grant the user
741 access, defaulting to "/".
742 user The name of the user the permissions apply to in the tar‐
744 get virtual host.
745 exchange
747 The name of the topic exchange the authorisation check
748 will be applied to.
749 write A regular expression matching the routing key of the pub‐
751 lished message.
752 read A regular expression matching the routing key of the con‐
754 sumed message.
755 Sets user topic permissions.
757 For example, this command instructs the RabbitMQ broker to let
759 the user named "janeway" publish and consume messages going
760 through the "amp.topic" exchange of the "my-vhost" virtual host
761 with a routing key starting with "janeway-":
762 rabbitmqctl set_topic_permissions -p my-vhost janeway
764 amq.topic "^janeway-.*" "^janeway-.*"
765 Topic permissions support variable expansion for the following
767 variables: username, vhost, and client_id. Note that client_id is
768 expanded only when using MQTT. The previous example could be
769 made more generic by using "^{username}-.*":
770 rabbitmqctl set_topic_permissions -p my-vhost janeway
772 amq.topic "^{username}-.*" "^{username}-.*"
773 Monitoring, observability and health checks
775 environment
776 Displays the name and value of each variable in the application
778 environment for each running application.
779 list_bindings [-p vhost] [bindinginfoitem ...]
781 Returns binding details. By default the bindings for the "/"
783 virtual host are returned. The -p flag can be used to override
784 this default.
785 The bindinginfoitem parameter is used to indicate which binding
787 information items to include in the results. The column order in
788 the results will match the order of the parameters.
789 bindinginfoitem can take any value from the list that follows:
790 source_name
792 The name of the source of messages to which the binding
793 is attached. With non-ASCII characters escaped as in C.
794 source_kind
796 The kind of the source of messages to which the binding
797 is attached. Currently always exchange. With non-ASCII
798 characters escaped as in C.
799 destination_name
801 The name of the destination of messages to which the
802 binding is attached. With non-ASCII characters escaped
803 as in C.
804 destination_kind
806 The kind of the destination of messages to which the
807 binding is attached. With non-ASCII characters escaped
808 as in C.
809 routing_key
811 The binding's routing key, with non-ASCII characters es‐
812 caped as in C.
813 arguments
815 The binding's arguments.
816 If no bindinginfoitem are specified then all above items are dis‐
818 played.
819 For example, this command displays the exchange name and queue
821 name of the bindings in the virtual host named "my-vhost"
822 rabbitmqctl list_bindings -p my-vhost exchange_name
824 queue_name
825 list_channels [channelinfoitem ...]
827 Returns information on all current channels, the logical contain‐
829 ers executing most AMQP commands. This includes channels that
830 are part of ordinary AMQP connections, and channels created by
831 various plug-ins and other extensions.
832 The channelinfoitem parameter is used to indicate which channel
834 information items to include in the results. The column order in
835 the results will match the order of the parameters.
836 channelinfoitem can take any value from the list that follows:
837 pid Id of the Erlang process associated with the connection.
839 connection
841 Id of the Erlang process associated with the connection
842 to which the channel belongs.
843 name Readable name for the channel.
845 number The number of the channel, which uniquely identifies it
847 within a connection.
848 user Username associated with the channel.
850 vhost Virtual host in which the channel operates.
852 transactional
854 True if the channel is in transactional mode, false oth‐
855 erwise.
856 confirm
858 True if the channel is in confirm mode, false otherwise.
859 consumer_count
861 Number of logical AMQP consumers retrieving messages via
862 the channel.
863 messages_unacknowledged
865 Number of messages delivered via this channel but not yet
866 acknowledged.
867 messages_uncommitted
869 Number of messages received in an as yet uncommitted
870 transaction.
871 acks_uncommitted
873 Number of acknowledgements received in an as yet uncom‐
874 mitted transaction.
875 messages_unconfirmed
877 Number of published messages not yet confirmed. On chan‐
878 nels not in confirm mode, this remains 0.
879 prefetch_count
881 QoS prefetch limit for new consumers, 0 if unlimited.
882 global_prefetch_count
884 QoS prefetch limit for the entire channel, 0 if unlim‐
885 ited.
886 If no channelinfoitem are specified then pid, user, con‐
888 sumer_count, and messages_unacknowledged are assumed.
889 For example, this command displays the connection process and
891 count of unacknowledged messages for each channel:
892 rabbitmqctl list_channels connection
894 messages_unacknowledged
895 list_ciphers
897 Lists cipher suites supported by encoding commands.
899 For example, this command instructs the RabbitMQ broker to list
901 all cipher suites supported by encoding commands:
902 rabbitmqctl list_ciphers
904 list_connections [connectioninfoitem ...]
906 Returns TCP/IP connection statistics.
908 The connectioninfoitem parameter is used to indicate which con‐
910 nection information items to include in the results. The column
911 order in the results will match the order of the parameters.
912 connectioninfoitem can take any value from the list that follows:
913 pid Id of the Erlang process associated with the connection.
915 name Readable name for the connection.
917 port Server port.
919 host Server hostname obtained via reverse DNS, or its IP ad‐
921 dress if reverse DNS failed or was turned off.
922 peer_port
924 Peer port.
925 peer_host
927 Peer hostname obtained via reverse DNS, or its IP address
928 if reverse DNS failed or was not enabled.
929 ssl Boolean indicating whether the connection is secured with
931 SSL.
932 ssl_protocol
934 SSL protocol (e.g. "tlsv1").
935 ssl_key_exchange
937 SSL key exchange algorithm (e.g. "rsa").
938 ssl_cipher
940 SSL cipher algorithm (e.g. "aes_256_cbc").
941 ssl_hash
943 SSL hash function (e.g. "sha").
944 peer_cert_subject
946 The subject of the peer's SSL certificate, in RFC4514
947 form.
948 peer_cert_issuer
950 The issuer of the peer's SSL certificate, in RFC4514
951 form.
952 peer_cert_validity
954 The period for which the peer's SSL certificate is valid.
955 state Connection state; one of:
957 • starting
958 • tuning
959 • opening
960 • running
961 • flow
962 • blocking
963 • blocked
964 • closing
965 • closed
966 channels
968 Number of channels using the connection.
969 protocol
971 Version of the AMQP protocol in use; currently one of:
972 • {0,9,1}
973 • {0,8,0}
974 Note that if a client requests an AMQP 0-9 connection, we
976 treat it as AMQP 0-9-1.
977 auth_mechanism
979 SASL authentication mechanism used, such as "PLAIN".
980 user Username associated with the connection.
982 vhost Virtual host name with non-ASCII characters escaped as in
984 C.
985 timeout
987 Connection timeout / negotiated heartbeat interval, in
988 seconds.
989 frame_max
991 Maximum frame size (bytes).
992 channel_max
994 Maximum number of channels on this connection.
995 client_properties
997 Informational properties transmitted by the client during
998 connection establishment.
999 recv_oct
1001 Octets received.
1002 recv_cnt
1004 Packets received.
1005 send_oct
1007 Octets send.
1008 send_cnt
1010 Packets sent.
1011 send_pend
1013 Send queue size.
1014 connected_at
1016 Date and time this connection was established, as time‐
1017 stamp.
1018 If no connectioninfoitem are specified then user, peer host, peer
1020 port, time since flow control and memory block state are dis‐
1021 played.
1022 For example, this command displays the send queue size and server
1024 port for each connection:
1025 rabbitmqctl list_connections send_pend port
1027 list_consumers [-p vhost]
1029 Lists consumers, i.e. subscriptions to a queue´s message stream.
1031 Each line printed shows, separated by tab characters, the name of
1032 the queue subscribed to, the id of the channel process via which
1033 the subscription was created and is managed, the consumer tag
1034 which uniquely identifies the subscription within a channel, a
1035 boolean indicating whether acknowledgements are expected for mes‐
1036 sages delivered to this consumer, an integer indicating the
1037 prefetch limit (with 0 meaning "none"), and any arguments for
1038 this consumer.
1039 list_exchanges [-p vhost] [exchangeinfoitem ...]
1041 Returns exchange details. Exchange details of the "/" virtual
1043 host are returned if the -p flag is absent. The -p flag can be
1044 used to override this default.
1045 The exchangeinfoitem parameter is used to indicate which exchange
1047 information items to include in the results. The column order in
1048 the results will match the order of the parameters.
1049 exchangeinfoitem can take any value from the list that follows:
1050 name The name of the exchange with non-ASCII characters es‐
1052 caped as in C.
1053 type The exchange type, such as:
1055 • direct
1056 • topic
1057 • headers
1058 • fanout
1059 durable
1061 Whether or not the exchange survives server restarts.
1062 auto_delete
1064 Whether the exchange will be deleted automatically when
1065 no longer used.
1066 internal
1068 Whether the exchange is internal, i.e. cannot be directly
1069 published to by a client.
1070 arguments
1072 Exchange arguments.
1073 policy Policy name for applying to the exchange.
1075 If no exchangeinfoitem are specified then exchange name and type
1077 are displayed.
1078 For example, this command displays the name and type for each ex‐
1080 change of the virtual host named "my-vhost":
1081 rabbitmqctl list_exchanges -p my-vhost name type
1083 list_hashes
1085 Lists hash functions supported by encoding commands.
1087 For example, this command instructs the RabbitMQ broker to list
1089 all hash functions supported by encoding commands:
1090 rabbitmqctl list_hashes
1092 list_queues [-p vhost] [--offline | --online | --local] [queueinfoitem
1094 ...]
1095 Returns queue details. Queue details of the "/" virtual host are
1097 returned if the -p flag is absent. The -p flag can be used to
1098 override this default.
1099 Displayed queues can be filtered by their status or location us‐
1101 ing one of the following mutually exclusive options:
1102 --offline
1104 List only those durable queues that are not currently
1105 available (more specifically, their leader node isn't).
1106 --online
1108 List queues that are currently available (their leader
1109 node is).
1110 --local
1112 List only those queues whose leader replica is located on
1113 the current node.
1114 The queueinfoitem parameter is used to indicate which queue in‐
1116 formation items to include in the results. The column order in
1117 the results will match the order of the parameters.
1118 queueinfoitem can take any value from the list that follows:
1119 name The name of the queue with non-ASCII characters escaped
1121 as in C.
1122 durable
1124 Whether or not the queue survives server restarts.
1125 auto_delete
1127 Whether the queue will be deleted automatically when no
1128 longer used.
1129 arguments
1131 Queue arguments.
1132 policy Name of the user policy that is applied to the queue.
1134 operator_policy
1136 Name of the operator policy that is applied to the queue.
1137 effective_policy_definition
1139 Effective policy definition for the queue: both user and
1140 operator policy definitions merged.
1141 pid Erlang process identifier of the queue.
1143 owner_pid
1145 Id of the Erlang process of the connection which is the
1146 exclusive owner of the queue. Empty if the queue is non-
1147 exclusive.
1148 exclusive
1150 True if queue is exclusive (i.e. has owner_pid), false
1151 otherwise.
1152 exclusive_consumer_pid
1154 Id of the Erlang process representing the channel of the
1155 exclusive consumer subscribed to this queue. Empty if
1156 there is no exclusive consumer.
1157 exclusive_consumer_tag
1159 Consumer tag of the exclusive consumer subscribed to this
1160 queue. Empty if there is no exclusive consumer.
1161 messages_ready
1163 Number of messages ready to be delivered to clients.
1164 messages_unacknowledged
1166 Number of messages delivered to clients but not yet ac‐
1167 knowledged.
1168 messages
1170 Sum of ready and unacknowledged messages (queue depth).
1171 messages_ready_ram
1173 Number of messages from messages_ready which are resident
1174 in ram.
1175 messages_unacknowledged_ram
1177 Number of messages from messages_unacknowledged which are
1178 resident in ram.
1179 messages_ram
1181 Total number of messages which are resident in ram.
1182 messages_persistent
1184 Total number of persistent messages in the queue (will
1185 always be 0 for transient queues).
1186 message_bytes
1188 Sum of the size of all message bodies in the queue. This
1189 does not include the message properties (including head‐
1190 ers) or any overhead.
1191 message_bytes_ready
1193 Like message_bytes but counting only those messages ready
1194 to be delivered to clients.
1195 message_bytes_unacknowledged
1197 Like message_bytes but counting only those messages de‐
1198 livered to clients but not yet acknowledged.
1199 message_bytes_ram
1201 Like message_bytes but counting only those messages which
1202 are currently held in RAM.
1203 message_bytes_persistent
1205 Like message_bytes but counting only those messages which
1206 are persistent.
1207 head_message_timestamp
1209 The timestamp property of the first message in the queue,
1210 if present. Timestamps of messages only appear when they
1211 are in the paged-in state.
1212 disk_reads
1214 Total number of times messages have been read from disk
1215 by this queue since it started.
1216 disk_writes
1218 Total number of times messages have been written to disk
1219 by this queue since it started.
1220 consumers
1222 Number of consumers.
1223 consumer_utilisation
1225 Fraction of the time (between 0.0 and 1.0) that the queue
1226 is able to immediately deliver messages to consumers.
1227 This can be less than 1.0 if consumers are limited by
1228 network congestion or prefetch count.
1229 memory Bytes of memory allocated by the runtime for the queue,
1231 including stack, heap and internal structures.
1232 mirror_pids
1234 If the queue is mirrored, this lists the IDs of the mir‐
1235 rors (follower replicas). To learn more, see the
1236 RabbitMQ Mirroring guide:
1237 https://www.rabbitmq.com/ha.html
1238 synchronised_mirror_pids
1240 If the queue is mirrored, this gives the IDs of the mir‐
1241 rors (follower replicas) which are in sync with the
1242 leader replica. To learn more, see the RabbitMQ Mirroring
1243 guide: https://www.rabbitmq.com/ha.html
1244 state The state of the queue. Normally "running", but may be
1246 "{syncing, message_count}" if the queue is synchronising.
1247 Queues which are located on cluster nodes that are cur‐
1249 rently down will be shown with a status of "down" (and
1250 most other queueinfoitem will be unavailable).
1251 type Queue type, one of: quorum, stream, classic.
1253 If no queueinfoitem are specified then queue name and depth are
1255 displayed.
1256 For example, this command displays the depth and number of con‐
1258 sumers for each queue of the virtual host named "my-vhost"
1259 rabbitmqctl list_queues -p my-vhost messages consumers
1261 list_unresponsive_queues [--local] [--queue-timeout milliseconds]
1263 [queueinfoitem ...] [--no-table-headers]
1264 Tests queue leader replicas to respond within the given timeout.
1266 Lists those which did not respond in time.
1267 Displayed queues can be filtered by their status or location us‐
1269 ing one of the following mutually exclusive options:
1270 --all List all queues.
1272 --local
1274 List only those queues whose leader replica is located on
1275 the current node.
1276 The queueinfoitem parameter is used to indicate which queue in‐
1278 formation items to include in the results. The column order in
1279 the results will match the order of the parameters.
1280 queueinfoitem can take any value from the list that follows:
1281 name The name of the queue with non-ASCII characters escaped
1283 as in C.
1284 durable
1286 Whether or not the queue should survive server restarts.
1287 auto_delete
1289 Whether the queue will be deleted automatically when all
1290 of its explicit bindings are deleted.
1291 arguments
1293 Queue arguments.
1294 policy Effective policy name for the queue.
1296 pid Erlang process identifier of the leader replica.
1298 recoverable_mirrors
1300 Erlang process identifiers of the mirror replicas that
1301 are considered reachable (available).
1302 type Queue type, one of: quorum, stream, classic.
1304 For example, this command lists only those unresponsive queues
1306 whose leader replica is hosted on the target node.
1307 rabbitmqctl list_unresponsive_queues --local name
1308 ping
1310 Checks that the node OS process is up, registered with EPMD and
1312 CLI tools can authenticate with it
1313 Example:
1315 rabbitmqctl ping -n rabbit@hostname
1316 report
1318 Generate a server status report containing a concatenation of all
1320 server status information for support purposes. The output
1321 should be redirected to a file when accompanying a support re‐
1322 quest.
1323 For example, this command creates a server report which may be
1325 attached to a support request email:
1326 rabbitmqctl report > server_report.txt
1328 schema_info [--no-table-headers] [column ...]
1330 Lists schema database tables and their properties
1332 For example, this command lists the table names and their active
1334 replicas:
1335 rabbitmqctl schema_info name active_replicas
1337 status
1339 Displays broker status information such as the running applica‐
1341 tions on the current Erlang node, RabbitMQ and Erlang versions,
1342 OS name, memory and file descriptor statistics. (See the
1343 cluster_status command to find out which nodes are clustered and
1344 running.)
1345 For example, this command displays information about the RabbitMQ
1347 broker:
1348 rabbitmqctl status
1350 Runtime Parameters and Policies
1352 Certain features of RabbitMQ (such as the Federation plugin) are con‐
1353 trolled by dynamic, cluster-wide parameters. There are 2 kinds of parame‐
1354 ters: parameters scoped to a virtual host and global parameters. Each
1355 vhost-scoped parameter consists of a component name, a name and a value.
1356 The component name and name are strings, and the value is a valid JSON
1357 document. A global parameter consists of a name and value. The name is
1358 a string and the value is an arbitrary Erlang data structure. Parameters
1359 can be set, cleared and listed. In general you should refer to the docu‐
1360 mentation for the feature in question to see how to set parameters.
1361 Policies is a feature built on top of runtime parameters. Policies are
1363 used to control and modify the behaviour of queues and exchanges on a
1364 cluster-wide basis. Policies apply within a given vhost, and consist of
1365 a name, pattern, definition and an optional priority. Policies can be
1366 set, cleared and listed.
1367 clear_global_parameter name
1369 Clears a global runtime parameter. This is similar to
1371 clear_parameter but the key-value pair isn't tied to a virtual
1372 host.
1373 name The name of the global runtime parameter being cleared.
1375 For example, this command clears the global runtime parameter
1377 "mqtt_default_vhosts":
1378 rabbitmqctl clear_global_parameter mqtt_default_vhosts
1380 clear_parameter [-p vhost] component_name key
1382 Clears a parameter.
1384 component_name
1386 The name of the component for which the parameter is be‐
1387 ing cleared.
1388 name The name of the parameter being cleared.
1390 For example, this command clears the parameter "node01" for the
1392 "federation-upstream" component in the default virtual host:
1393 rabbitmqctl clear_parameter federation-upstream node01
1395 list_global_parameters
1397 Lists all global runtime parameters. This is similar to
1399 list_parameters but the global runtime parameters are not tied to
1400 any virtual host.
1401 For example, this command lists all global parameters:
1403 rabbitmqctl list_global_parameters
1405 list_parameters [-p vhost]
1407 Lists all parameters for a virtual host.
1409 For example, this command lists all parameters in the default
1411 virtual host:
1412 rabbitmqctl list_parameters
1414 set_global_parameter name value
1416 Sets a global runtime parameter. This is similar to
1418 set_parameter but the key-value pair isn't tied to a virtual
1419 host.
1420 name The name of the global runtime parameter being set.
1422 value The value for the global runtime parameter, as a JSON
1424 document. In most shells you are very likely to need to
1425 quote this.
1426 For example, this command sets the global runtime parameter
1428 "mqtt_default_vhosts" to the JSON document
1429 {"O=client,CN=guest":"/"}:
1430 rabbitmqctl set_global_parameter mqtt_default_vhosts
1432 '{"O=client,CN=guest":"/"}'
1433 set_parameter [-p vhost] component_name name value
1435 Sets a parameter.
1437 component_name
1439 The name of the component for which the parameter is be‐
1440 ing set.
1441 name The name of the parameter being set.
1443 value The value for the parameter, as a JSON document. In most
1445 shells you are very likely to need to quote this.
1446 For example, this command sets the parameter "node01" for the
1448 "federation-upstream" component in the default virtual host to
1449 the following JSON "guest":
1450 rabbitmqctl set_parameter federation-upstream node01
1452 '{"uri":"amqp://user:password@server/%2F","ack-mode":"on-publish"}'
1453 list_policies [-p vhost]
1455 Lists all policies for a virtual host.
1457 For example, this command lists all policies in the default vir‐
1459 tual host:
1460 rabbitmqctl list_policies
1462 set_operator_policy [-p vhost] [--priority priority] [--apply-to
1464 apply-to] name pattern definition
1465 Sets an operator policy that overrides a subset of arguments in
1467 user policies. Arguments are identical to those of set_policy.
1468 Supported arguments are:
1470 • expires
1471 • message-ttl
1472 • max-length
1473 • max-length-bytes
1474 set_policy [-p vhost] [--priority priority] [--apply-to apply-to] name
1476 pattern definition
1477 Sets a policy.
1479 name The name of the policy.
1481 pattern
1483 The regular expression, which when matches on a given re‐
1484 sources causes the policy to apply.
1485 definition
1487 The definition of the policy, as a JSON document. In
1488 most shells you are very likely to need to quote this.
1489 priority
1491 The priority of the policy as an integer. Higher numbers
1492 indicate greater precedence. The default is 0.
1493 apply-to
1495 Which types of object this policy should apply to. Pos‐
1496 sible values are:
1497 • queues
1498 • exchanges
1499 • all
1500 The default is all ..
1501 For example, this command sets the policy "federate-me" in the
1503 default virtual host so that built-in exchanges are federated:
1504 rabbitmqctl set_policy federate-me ^amq.
1506 '{"federation-upstream-set":"all"}'
1507 clear_policy [-p vhost] name
1509 Clears a policy.
1511 name The name of the policy being cleared.
1513 For example, this command clears the "federate-me" policy in the
1515 default virtual host:
1516 rabbitmqctl clear_policy federate-me
1518 clear_operator_policy [-p vhost] name
1520 Clears an operator policy. Arguments are identical to those of
1522 clear_policy.
1523 list_operator_policies [-p vhost]
1525 Lists operator policy overrides for a virtual host. Arguments
1527 are identical to those of list_policies.
1528 Virtual hosts
1530 Note that rabbitmqctl manages the RabbitMQ internal user database. Per‐
1531 missions for users from any alternative authorisation backend will not be
1532 visible to rabbitmqctl.
1533 add_vhost vhost [--description desc --tags tags --default-queue-type
1535 default-q-type]
1536 vhost The name of the virtual host entry to create.
1538 desc Arbitrary virtual host description, e.g. its purpose, for
1540 operator's convenience.
1541 tags A comma-separated list of virtual host tags for opera‐
1543 tor's convenient
1544 default-q-type
1546 If clients do not specify queue type explicitly, this
1547 type will be used. One of: quorum, stream.
1548 Creates a virtual host.
1550 For example, this command instructs the RabbitMQ broker to create
1552 a new virtual host called "project9_dev_18":
1553 rabbitmqctl add_vhost project9_dev_18 --description 'Dev
1555 environment no. 18' --tags dev,project9
1556 clear_vhost_limits [-p vhost]
1558 Clears virtual host limits.
1560 For example, this command clears vhost limits in vhost "qa_env":
1562 rabbitmqctl clear_vhost_limits -p qa_env
1564 delete_vhost vhost
1566 vhost The name of the virtual host entry to delete.
1568 Deletes a virtual host.
1570 Deleting a virtual host deletes all its exchanges, queues, bind‐
1572 ings, user permissions, parameters and policies.
1573 For example, this command instructs the RabbitMQ broker to delete
1575 the virtual host called "test":
1576 rabbitmqctl delete_vhost a-vhost
1578 list_vhost_limits [-p vhost] [--global] [--no-table-headers]
1580 Displays configured virtual host limits.
1582 --global
1584 Show limits for all vhosts. Suppresses the -p parameter.
1585 restart_vhost [-p vhost]
1587 vhost The name of the virtual host entry to restart, defaulting
1589 to "/".
1590 Restarts a failed vhost data stores and queues.
1592 For example, this command instructs the RabbitMQ broker to
1594 restart a virtual host called "test":
1595 rabbitmqctl restart_vhost test
1597 set_vhost_limits [-p vhost] definition
1599 Sets virtual host limits.
1601 definition
1603 The definition of the limits, as a JSON document. In
1604 most shells you are very likely to need to quote this.
1605 Recognised limits are:
1607 • max-connections
1608 • max-queues
1609 Use a negative value to specify "no limit".
1611 For example, this command limits the max number of concurrent
1613 connections in vhost "qa_env" to 64:
1614 rabbitmqctl set_vhost_limits -p qa_env '{"max-connections":
1616 64}'
1617 This command limits the max number of queues in vhost "qa_env" to
1619 256:
1620 rabbitmqctl set_vhost_limits -p qa_env '{"max-queues":
1622 256}'
1623 This command clears the max number of connections limit in vhost
1625 "qa_env":
1626 rabbitmqctl set_vhost_limits -p qa_env '{"max-connections":
1628 -1}'
1629 This command disables client connections in vhost "qa_env":
1631 rabbitmqctl set_vhost_limits -p qa_env '{"max-connections":
1633 0}'
1634 ] username
1635 ] definition
1636 set_user_limits
1638 Sets user limits.
1640 username
1642 The name of the user to apply limits to
1643 definition
1645 The definition of the limits, as a JSON document. In
1646 most shells you are very likely to need to quote this.
1647 Recognised limits are:
1649 • max-connections
1650 • max-channels
1651 Use a negative value to specify "no limit".
1653 For example, this command limits the max number of concurrent
1655 connections a user is allowed to open "limited_user" to 64:
1656 rabbitmqctl set_user_limits limited_user
1658 '{"max-connections": 64}'
1659 This command limits the max number of channels a user is allowed
1661 to open on a connection "limited_user" to 16:
1662 rabbitmqctl set_user_limits limited_user '{"max-channels":
1664 16}'
1665 This command clears the max number of connections limit for user
1667 "limited_user":
1668 rabbitmqctl clear_user_limits limited_user
1670 'max-connections'
1671 This command disables client connections for user "limited_user":
1673 rabbitmqctl set_user_limits limited_user
1675 '{"max-connections": 0}'
1676 ] username
1677 ] limit
1678 clear_user_limits
1680 Clears user limits.
1682 username
1684 The name of the user to clear limits of
1685 limit The name of the limit or "all" to clear all limits at
1687 once.
1688 Recognised limits are:
1690 • max-connections
1691 • max-channels
1692 For example, this command clears max connection limits of user
1694 "limited_user":
1695 rabbitmqctl clear_user_limits limited_user
1697 'max-connections'
1698 This command clears all limits of user "limited_user":
1700 rabbitmqctl clear_user_limits limited_user all
1702 trace_off [-p vhost]
1704 vhost The name of the virtual host for which to stop tracing.
1706 Stops tracing.
1708 trace_on [-p vhost]
1710 vhost The name of the virtual host for which to start tracing.
1712 Starts tracing. Note that the trace state is not persistent; it
1714 will revert to being off if the node is restarted.
1715 Configuration
1717 decode value passphrase [--cipher cipher] [--hash hash] [--iterations
1718 iterations]
1719 value passphrase
1721 Value to decrypt (as produced by the encode command) and
1722 passphrase.
1723 For example:
1725 rabbitmqctl decode '{encrypted, <<"...">>}'
1727 mypassphrase
1728 --cipher cipher --hash hash --iterations iterations
1730 Options to specify the decryption settings. They can be
1731 used independently.
1732 For example:
1734 rabbitmqctl decode --cipher blowfish_cfb64 --hash
1736 sha256 --iterations 10000 '{encrypted,<<"...">>}
1737 mypassphrase
1738 encode value passphrase [--cipher cipher] [--hash hash] [--iterations
1740 iterations]
1741 value passphrase
1743 Value to encrypt and passphrase.
1744 For example:
1746 rabbitmqctl encode '<<"guest">>' mypassphrase
1748 --cipher cipher --hash hash --iterations iterations
1750 Options to specify the encryption settings. They can be
1751 used independently.
1752 For example:
1754 rabbitmqctl encode --cipher blowfish_cfb64 --hash
1756 sha256 --iterations 10000 '<<"guest">>'
1757 mypassphrase
1758 set_cluster_name name
1760 Sets the cluster name to name. The cluster name is announced to
1762 clients on connection, and used by the federation and shovel
1763 plugins to record where a message has been. The cluster name is
1764 by default derived from the hostname of the first node in the
1765 cluster, but can be changed.
1766 For example, this sets the cluster name to "london":
1768 rabbitmqctl set_cluster_name london
1770 set_disk_free_limit disk_limit
1772 disk_limit
1774 Lower bound limit as an integer in bytes or a string with
1775 memory unit symbols (see vm_memory_high_watermark), e.g.
1776 512M or 1G. Once free disk space reaches the limit, a
1777 disk alarm will be set.
1778 set_disk_free_limit mem_relative fraction
1780 fraction
1782 Limit relative to the total amount available RAM as a
1783 non-negative floating point number. Values lower than
1784 1.0 can be dangerous and should be used carefully.
1785 set_log_level [log_level]
1787 Sets log level in the running node
1789 Supported log_level values are:
1791 • debug
1792 • info
1793 • warning
1794 • error
1795 • critical
1796 • none
1797 Example:
1799 rabbitmqctl set_log_level debug
1800 set_vm_memory_high_watermark fraction
1802 fraction
1804 The new memory threshold fraction at which flow control
1805 is triggered, as a floating point number greater than or
1806 equal to 0.
1807 set_vm_memory_high_watermark [absolute] memory_limit
1809 memory_limit
1811 The new memory limit at which flow control is triggered,
1812 expressed in bytes as an integer number greater than or
1813 equal to 0 or as a string with memory unit symbol(e.g.
1814 512M or 1G). Available unit symbols are:
1815 k, kiB kibibytes (2^10 bytes)
1817 M, MiB mebibytes (2^20 bytes)
1819 G, GiB gibibytes (2^30 bytes)
1821 kB kilobytes (10^3 bytes)
1823 MB megabytes (10^6 bytes)
1825 GB gigabytes (10^9 bytes)
1827 Feature flags
1829 enable_feature_flag feature_flag
1830 Enables a feature flag on the target node.
1832 Example:
1834 rabbitmqctl enable_feature_flag stream_queue
1835 You can also enable all feature flags by specifying "all":
1837 rabbitmqctl enable_feature_flag all
1838 list_feature_flags [column ...]
1840 Lists feature flags
1842 Supported column values are:
1844 • name
1845 • state
1846 • stability
1847 • provided_by
1848 • desc
1849 • doc_url
1850 Example:
1852 rabbitmqctl list_feature_flags name state
1853 Connection Operations
1855 close_all_connections [-p vhost] [--global] [--per-connection-delay
1856 delay] [--limit limit] explanation
1857 -p vhost
1859 The name of the virtual host for which connections should
1860 be closed. Ignored when --global is specified.
1861 --global
1863 If connections should be close for all vhosts. Overrides
1864 -p
1865 --per-connection-delay delay
1867 Time in milliseconds to wait after each connection clos‐
1868 ing.
1869 --limit limit
1871 Number of connection to close. Only works per vhost.
1872 Ignored when --global is specified.
1873 explanation
1875 Explanation string.
1876 Instructs the broker to close all connections for the specified
1878 vhost or entire RabbitMQ node.
1879 For example, this command instructs the RabbitMQ broker to close
1881 10 connections on "qa_env" vhost, passing the explanation "Please
1882 close":
1883 rabbitmqctl close_all_connections -p qa_env --limit 10
1885 'Please close'
1886 This command instructs broker to close all connections to the
1888 node:
1889 rabbitmqctl close_all_connections --global
1891 close_connection connectionpid explanation
1894 connectionpid
1896 Id of the Erlang process associated with the connection
1897 to close.
1898 explanation
1900 Explanation string.
1901 Instructs the broker to close the connection associated with the
1903 Erlang process id connectionpid (see also the list_connections
1904 command), passing the explanation string to the connected client
1905 as part of the AMQP connection shutdown protocol.
1906 For example, this command instructs the RabbitMQ broker to close
1908 the connection associated with the Erlang process id
1909 "<rabbit@tanto.4262.0>", passing the explanation "go away" to the
1910 connected client:
1911 rabbitmqctl close_connection "<rabbit@tanto.4262.0>" "go
1913 away"
1914 Misc
1916 eval expression
1917 Evaluates an Erlang expression on the target node
1919 Queue Operations
1921 delete_queue queue_name [--if-empty | -e] [--if-unused | -u]
1922 queue_name
1924 The name of the queue to delete.
1925 --if-empty
1927 Delete the queue if it is empty (has no messages
1928 ready for delivery)
1929 --if-unused
1931 Delete the queue only if it has no consumers
1932 Deletes a queue.
1934 purge_queue [-p vhost] queue
1936 queue The name of the queue to purge.
1938 Purges a queue (removes all messages in it).
1940
1942 RabbitMQ plugins can extend rabbitmqctl tool to add new commands when en‐
1943 abled. Currently available commands can be found in rabbitmqctl help
1944 output. Following commands are added by RabbitMQ plugins, available in
1945 default distribution:
1946 Shovel plugin
1948 shovel_status
1949 Prints a list of configured Shovels
1950 delete_shovel [-p vhost] name
1952 Instructs the RabbitMQ node to delete the configured shovel by
1953 name.
1954 Federation plugin
1956 federation_status [--only-down]
1957 Prints a list of federation links.
1958 --only-down
1960 Only list federation links which are not running.
1961 restart_federation_link link_id
1963 Instructs the RabbitMQ node to restart the federation link with
1964 specified link_id.
1965 AMQP 1.0 plugin
1967 list_amqp10_connections [amqp10_connectioninfoitem ...]
1968 Similar to the list_connections command, but returns fields which
1969 make sense for AMQP-1.0 connections. amqp10_connectioninfoitem
1970 parameter is used to indicate which connection information items
1971 to include in the results. The column order in the results will
1972 match the order of the parameters. amqp10_connectioninfoitem can
1973 take any value from the list that follows:
1974 pid Id of the Erlang process associated with the connection.
1976 auth_mechanism
1978 SASL authentication mechanism used, such as "PLAIN".
1979 host Server hostname obtained via reverse DNS, or its IP ad‐
1981 dress if reverse DNS failed or was turned off.
1982 frame_max
1984 Maximum frame size (bytes).
1985 timeout
1987 Connection timeout / negotiated heartbeat interval, in
1988 seconds.
1989 user Username associated with the connection.
1991 state Connection state; one of:
1993 • starting
1994 • waiting_amqp0100
1995 • securing
1996 • running
1997 • blocking
1998 • blocked
1999 • closing
2000 • closed
2001 recv_oct
2003 Octets received.
2004 recv_cnt
2006 Packets received.
2007 send_oct
2009 Octets send.
2010 send_cnt
2012 Packets sent.
2013 ssl Boolean indicating whether the connection is secured with
2015 SSL.
2016 ssl_protocol
2018 SSL protocol (e.g. "tlsv1").
2019 ssl_key_exchange
2021 SSL key exchange algorithm (e.g. "rsa").
2022 ssl_cipher
2024 SSL cipher algorithm (e.g. "aes_256_cbc").
2025 ssl_hash
2027 SSL hash function (e.g. "sha").
2028 peer_cert_subject
2030 The subject of the peer's SSL certificate, in RFC4514
2031 form.
2032 peer_cert_issuer
2034 The issuer of the peer's SSL certificate, in RFC4514
2035 form.
2036 peer_cert_validity
2038 The period for which the peer's SSL certificate is valid.
2039 node The node name of the RabbitMQ node to which connection is
2041 established.
2042 MQTT plugin
2044 list_mqtt_connections [mqtt_connectioninfoitem]
2045 Similar to the list_connections command, but returns fields which
2046 make sense for MQTT connections. mqtt_connectioninfoitem parame‐
2047 ter is used to indicate which connection information items to in‐
2048 clude in the results. The column order in the results will match
2049 the order of the parameters. mqtt_connectioninfoitem can take
2050 any value from the list that follows:
2051 host Server hostname obtained via reverse DNS, or its IP ad‐
2053 dress if reverse DNS failed or was turned off.
2054 port Server port.
2056 peer_host
2058 Peer hostname obtained via reverse DNS, or its IP address
2059 if reverse DNS failed or was not enabled.
2060 peer_port
2062 Peer port.
2063 protocol
2065 MQTT protocol version, which can be on of the following:
2066 • {'MQTT', N/A}
2067 • {'MQTT', 3.1.0}
2068 • {'MQTT', 3.1.1}
2069 channels
2071 Number of channels using the connection.
2072 channel_max
2074 Maximum number of channels on this connection.
2075 frame_max
2077 Maximum frame size (bytes).
2078 client_properties
2080 Informational properties transmitted by the client during
2081 connection establishment.
2082 ssl Boolean indicating whether the connection is secured with
2084 SSL.
2085 ssl_protocol
2087 SSL protocol (e.g. "tlsv1").
2088 ssl_key_exchange
2090 SSL key exchange algorithm (e.g. "rsa").
2091 ssl_cipher
2093 SSL cipher algorithm (e.g. "aes_256_cbc").
2094 ssl_hash
2096 SSL hash function (e.g. "sha").
2097 conn_name
2099 Readable name for the connection.
2100 connection_state
2102 Connection state; one of:
2103 • starting
2104 • running
2105 • blocked
2106 connection
2108 Id of the Erlang process associated with the internal
2109 amqp direct connection.
2110 consumer_tags
2112 A tuple of consumer tags for QOS0 and QOS1.
2113 message_id
2115 The last Packet ID sent in a control message.
2116 client_id
2118 MQTT client identifier for the connection.
2119 clean_sess
2121 MQTT clean session flag.
2122 will_msg
2124 MQTT Will message sent in CONNECT frame.
2125 exchange
2127 Exchange to route MQTT messages configured in rab‐
2128 bitmq_mqtt application environment.
2129 ssl_login_name
2131 SSL peer cert auth name
2132 retainer_pid
2134 Id of the Erlang process associated with retain storage
2135 for the connection.
2136 user Username associated with the connection.
2138 vhost Virtual host name with non-ASCII characters escaped as in
2140 C.
2141 decommission_mqtt_node
2143 Before the plugin is disabled on a node, or a node removed from
2144 the cluster, it must be decommissioned.
2145 For example, this command will remove the node rabbit@stringer:
2147 rabbitmqctl decommission_mqtt_node rabbit@stringer
2149 STOMP plugin
2151 list_stomp_connections [stomp_connectioninfoitem]
2152 Similar to the list_connections command, but returns fields which
2153 make sense for STOMP connections. stomp_connectioninfoitem pa‐
2154 rameter is used to indicate which connection information items to
2155 include in the results. The column order in the results will
2156 match the order of the parameters. stomp_connectioninfoitem can
2157 take any value from the list that follows:
2158 conn_name
2160 Readable name for the connection.
2161 connection
2163 Id of the Erlang process associated with the internal
2164 amqp direct connection.
2165 connection_state
2167 Connection state; one of:
2168 • running
2169 • blocking
2170 • blocked
2171 session_id
2173 STOMP protocol session identifier
2174 channel
2176 AMQP channel associated with the connection
2177 version
2179 Negotiated STOMP protocol version for the connection.
2180 implicit_connect
2182 Indicates if the connection was established using im‐
2183 plicit connect (without CONNECT frame)
2184 auth_login
2186 Effective username for the connection.
2187 auth_mechanism
2189 STOMP authorization mechanism. Can be one of:
2190 • config
2191 • ssl
2192 • stomp_headers
2193 port Server port.
2195 host Server hostname obtained via reverse DNS, or its IP ad‐
2197 dress if reverse DNS failed or was not enabled.
2198 peer_port
2200 Peer port.
2201 peer_host
2203 Peer hostname obtained via reverse DNS, or its IP address
2204 if reverse DNS failed or was not enabled.
2205 protocol
2207 STOMP protocol version, which can be on of the following:
2208 • {'STOMP', 0}
2209 • {'STOMP', 1}
2210 • {'STOMP', 2}
2211 channels
2213 Number of channels using the connection.
2214 channel_max
2216 Maximum number of channels on this connection.
2217 frame_max
2219 Maximum frame size (bytes).
2220 client_properties
2222 Informational properties transmitted by the client during
2223 connection
2224 ssl Boolean indicating whether the connection is secured with
2226 SSL.
2227 ssl_protocol
2229 TLS protocol (e.g. "tlsv1").
2230 ssl_key_exchange
2232 TLS key exchange algorithm (e.g. "rsa").
2233 ssl_cipher
2235 TLS cipher algorithm (e.g. "aes_256_cbc").
2236 ssl_hash
2238 SSL hash function (e.g. "sha").
2239 Management agent plugin
2241 reset_stats_db [--all]
2242 Reset management stats database for the RabbitMQ node.
2243 --all Reset stats database for all nodes in the cluster.
2245
2247 rabbitmq-diagnostics(8), rabbitmq-plugins(8), rabbitmq-server(8),
2248 rabbitmq-queues(8), rabbitmq-streams(8), rabbitmq-upgrade(8),
2249 rabbitmq-service(8), rabbitmq-env.conf(5), rabbitmq-echopid(8)
2250
2252 The RabbitMQ Team <info@rabbitmq.com>
2253RabbitMQ Server October 26, 2022 RabbitMQ Server