1RABBITMQCTL(1) RabbitMQ Service RABBITMQCTL(1)
2
6 rabbitmqctl - command line tool for managing a RabbitMQ broker
7
9 rabbitmqctl [-n node] [-q] {command} [command options...]
10
12 RabbitMQ is an implementation of AMQP, the emerging standard for high
13 performance enterprise messaging. The RabbitMQ server is a robust and
14 scalable implementation of an AMQP broker.
15 rabbitmqctl is a command line tool for managing a RabbitMQ broker. It
17 performs all actions by connecting to one of the broker's nodes.
18 Diagnostic information is displayed if the broker was not running,
20 could not be reached, or rejected the connection due to mismatching
21 Erlang cookies.
22
24 [-n node]
25 Default node is "rabbit@server", where server is the local host. On
26 a host named "server.example.com", the node name of the RabbitMQ
27 Erlang node will usually be rabbit@server (unless RABBITMQ_NODENAME
28 has been set to some non-default value at broker startup time). The
29 output of hostname -s is usually the correct suffix to use after
30 the "@" sign. See rabbitmq-server(1) for details of configuring the
31 RabbitMQ broker.
32 [-q]
34 Quiet output mode is selected with the "-q" flag. Informational
35 messages are suppressed when quiet mode is in effect.
36
38 Application and Cluster Management
39 stop
40 Stops the Erlang node on which RabbitMQ is running. To restart the
41 node follow the instructions for Running the Server in the
42 installation guide[1].
43 stop_app
45 Stops the RabbitMQ application, leaving the Erlang node running.
46 This command is typically run prior to performing other management
48 actions that require the RabbitMQ application to be stopped, e.g.
49 reset.
50 start_app
52 Starts the RabbitMQ application.
53 This command is typically run after performing other management
55 actions that required the RabbitMQ application to be stopped, e.g.
56 reset.
57 wait {pid_file}
59 Wait for the RabbitMQ application to start.
60 This command will wait for the RabbitMQ application to start at the
62 node. It will wait for the pid file to be created, then for a
63 process with a pid specified in the pid file to start, and then for
64 the RabbitMQ application to start in that process. It will fail if
65 the process terminates without starting the RabbitMQ application.
66 A suitable pid file is created by the rabbitmq-server script. By
68 default this is located in the Mnesia directory. Modify the
69 RABBITMQ_PID_FILE environment variable to change the location.
70 reset
72 Return a RabbitMQ node to its virgin state.
73 Removes the node from any cluster it belongs to, removes all data
75 from the management database, such as configured users and vhosts,
76 and deletes all persistent messages.
77 For reset and force_reset to succeed the RabbitMQ application must
79 have been stopped, e.g. with stop_app.
80 force_reset
82 Forcefully return a RabbitMQ node to its virgin state.
83 The force_reset command differs from reset in that it resets the
85 node unconditionally, regardless of the current management database
86 state and cluster configuration. It should only be used as a last
87 resort if the database or cluster configuration has been corrupted.
88 For reset and force_reset to succeed the RabbitMQ application must
90 have been stopped, e.g. with stop_app.
91 rotate_logs {suffix}
93 Instruct the RabbitMQ node to rotate the log files.
94 The RabbitMQ broker will attempt to append the current contents of
96 the log file to the file with name composed of the original name
97 and the suffix. It will create a new file if such a file does not
98 already exist. When no suffix is specified, the empty log file is
99 simply created at the original location; no rotation takes place.
100 When an error occurs while appending the contents of the old log
102 file, the operation behaves in the same way as if no suffix was
103 specified.
104 This command might be helpful when you are e.g. writing your own
106 logrotate script and you do not want to restart the RabbitMQ node.
107 Cluster management
109 cluster {clusternode ...}
110 clusternode
112 Subset of the nodes of the cluster to which this node should be
113 connected.
114 Instruct the node to become member of a cluster with the specified
116 nodes. To cluster with currently offline nodes, use force_cluster.
117 Cluster nodes can be of two types: disk or ram. Disk nodes
119 replicate data in ram and on disk, thus providing redundancy in the
120 event of node failure and recovery from global events such as power
121 failure across all nodes. Ram nodes replicate data in ram only and
122 are mainly used for scalability. A cluster must always have at
123 least one disk node.
124 If the current node is to become a disk node it needs to appear in
126 the cluster node list. Otherwise it becomes a ram node. If the node
127 list is empty or only contains the current node then the node
128 becomes a standalone, i.e. non-clustered, (disk) node.
129 After executing the cluster command, whenever the RabbitMQ
131 application is started on the current node it will attempt to
132 connect to the specified nodes, thus becoming an active node in the
133 cluster comprising those nodes (and possibly others).
134 The list of nodes does not have to contain all the cluster's nodes;
136 a subset is sufficient. Also, clustering generally succeeds as long
137 as at least one of the specified nodes is active. Hence adjustments
138 to the list are only necessary if the cluster configuration is to
139 be altered radically.
140 For this command to succeed the RabbitMQ application must have been
142 stopped, e.g. with stop_app. Furthermore, turning a standalone node
143 into a clustered node requires the node be reset first, in order to
144 avoid accidental destruction of data with the cluster command.
145 For more details see the clustering guide[2].
147 force_cluster {clusternode ...}
149 clusternode
151 Subset of the nodes of the cluster to which this node should be
152 connected.
153 Instruct the node to become member of a cluster with the specified
155 nodes. This will succeed even if the specified nodes are offline.
156 For a more detailed description, see cluster.
157 Note that this variant of the cluster command just ignores the
159 current status of the specified nodes. Clustering may still fail
160 for a variety of other reasons.
161 cluster_status
163 Displays all the nodes in the cluster grouped by node type,
164 together with the currently running nodes.
165 Closing individual connections
167 close_connection {connectionpid} {explanation}
168 connectionpid
170 Id of the Erlang process associated with the connection to
171 close.
172 explanation
174 Explanation string.
175 Instruct the broker to close the connection associated with the
177 Erlang process id connectionpid (see also the list_connections
178 command), passing the explanation string to the connected client as
179 part of the AMQP connection shutdown protocol.
180 User management
182 Note that rabbitmqctl manages the RabbitMQ internal user database.
183 Users from any alternative authentication backend will not be visible
184 to rabbitmqctl.
185 add_user {username} {password}
187 username
189 The name of the user to create.
190 password
192 The password the created user will use to log in to the broker.
193 delete_user {username}
195 username
197 The name of the user to delete.
198 change_password {username} {newpassword}
200 username
202 The name of the user whose password is to be changed.
203 newpassword
205 The new password for the user.
206 clear_password {username}
208 username
210 The name of the user whose password is to be cleared.
211 set_user_tags {username} {tag ...}
213 username
215 The name of the user whose tags are to be set.
216 tag
218 Zero, one or more tags to set. Any existing tags will be
219 removed.
220 list_users
222 Lists users. Each result row will contain the user name followed by
223 a list of the tags set for that user.
224 Access control
226 Note that rabbitmqctl manages the RabbitMQ internal user database.
227 Permissions for users from any alternative authorisation backend will
228 not be visible to rabbitmqctl.
229 add_vhost {vhostpath}
231 vhostpath
233 The name of the virtual host entry to create.
234 Creates a virtual host.
236 delete_vhost {vhostpath}
238 vhostpath
240 The name of the virtual host entry to delete.
241 Deletes a virtual host.
243 Deleting a virtual host deletes all its exchanges, queues, user
245 mappings and associated permissions.
246 list_vhosts [vhostinfoitem ...]
248 Lists virtual hosts.
249 The vhostinfoitem parameter is used to indicate which virtual host
251 information items to include in the results. The column order in
252 the results will match the order of the parameters. vhostinfoitem
253 can take any value from the list that follows:
254 name
256 The name of the virtual host with non-ASCII characters escaped
257 as in C.
258 tracing
260 Whether tracing is enabled for this virtual host.
261 If no vhostinfoitems are specified then the vhost name is
263 displayed.
264 set_permissions [-p vhostpath] {user} {conf} {write} {read}
266 vhostpath
268 The name of the virtual host to which to grant the user access,
269 defaulting to /.
270 user
272 The name of the user to grant access to the specified virtual
273 host.
274 conf
276 A regular expression matching resource names for which the user
277 is granted configure permissions.
278 write
280 A regular expression matching resource names for which the user
281 is granted write permissions.
282 read
284 A regular expression matching resource names for which the user
285 is granted read permissions.
286 Sets user permissions.
288 clear_permissions [-p vhostpath] {username}
290 vhostpath
292 The name of the virtual host to which to deny the user access,
293 defaulting to /.
294 username
296 The name of the user to deny access to the specified virtual
297 host.
298 Sets user permissions.
300 list_permissions [-p vhostpath]
302 vhostpath
304 The name of the virtual host for which to list the users that
305 have been granted access to it, and their permissions. Defaults
306 to /.
307 Lists permissions in a virtual host.
309 list_user_permissions [-p vhostpath] {username}
311 username
313 The name of the user for which to list the permissions.
314 Lists user permissions.
316 Server Status
318 The server status queries interrogate the server and return a list of
319 results with tab-delimited columns. Some queries (list_queues,
320 list_exchanges, list_bindings, and list_consumers) accept an optional
321 vhost parameter. This parameter, if present, must be specified
322 immediately after the query.
323 The list_queues, list_exchanges and list_bindings commands accept an
325 optional virtual host parameter for which to display results. The
326 default value is "/".
327 list_queues [-p vhostpath] [queueinfoitem ...]
329 Returns queue details. Queue details of the / virtual host are
330 returned if the "-p" flag is absent. The "-p" flag can be used to
331 override this default.
332 The queueinfoitem parameter is used to indicate which queue
334 information items to include in the results. The column order in
335 the results will match the order of the parameters. queueinfoitem
336 can take any value from the list that follows:
337 name
339 The name of the queue with non-ASCII characters escaped as in
340 C.
341 durable
343 Whether or not the queue survives server restarts.
344 auto_delete
346 Whether the queue will be deleted automatically when no longer
347 used.
348 arguments
350 Queue arguments.
351 pid
353 Id of the Erlang process associated with the queue.
354 owner_pid
356 Id of the Erlang process representing the connection which is
357 the exclusive owner of the queue. Empty if the queue is
358 non-exclusive.
359 exclusive_consumer_pid
361 Id of the Erlang process representing the channel of the
362 exclusive consumer subscribed to this queue. Empty if there is
363 no exclusive consumer.
364 exclusive_consumer_tag
366 Consumer tag of the exclusive consumer subscribed to this
367 queue. Empty if there is no exclusive consumer.
368 messages_ready
370 Number of messages ready to be delivered to clients.
371 messages_unacknowledged
373 Number of messages delivered to clients but not yet
374 acknowledged.
375 messages
377 Sum of ready and unacknowledged messages (queue depth).
378 consumers
380 Number of consumers.
381 memory
383 Bytes of memory consumed by the Erlang process associated with
384 the queue, including stack, heap and internal structures.
385 slave_pids
387 If the queue is mirrored, this gives the IDs of the current
388 slaves.
389 synchronised_slave_pids
391 If the queue is mirrored, this gives the IDs of the current
392 slaves which are synchronised with the master - i.e. those
393 which could take over from the master without message loss.
394 If no queueinfoitems are specified then queue name and depth are
396 displayed.
397 list_exchanges [-p vhostpath] [exchangeinfoitem ...]
399 Returns exchange details. Exchange details of the / virtual host
400 are returned if the "-p" flag is absent. The "-p" flag can be used
401 to override this default.
402 The exchangeinfoitem parameter is used to indicate which exchange
404 information items to include in the results. The column order in
405 the results will match the order of the parameters.
406 exchangeinfoitem can take any value from the list that follows:
407 name
409 The name of the exchange with non-ASCII characters escaped as
410 in C.
411 type
413 The exchange type (one of [direct, topic, headers, fanout]).
414 durable
416 Whether or not the exchange survives server restarts.
417 auto_delete
419 Whether the exchange will be deleted automatically when no
420 longer used.
421 internal
423 Whether the exchange is internal, i.e. cannot be directly
424 published to by a client.
425 arguments
427 Exchange arguments.
428 If no exchangeinfoitems are specified then exchange name and type
430 are displayed.
431 list_bindings [-p vhostpath] [bindinginfoitem ...]
433 Returns binding details. By default the bindings for the / virtual
434 host are returned. The "-p" flag can be used to override this
435 default.
436 The bindinginfoitem parameter is used to indicate which binding
438 information items to include in the results. The column order in
439 the results will match the order of the parameters.
440 bindinginfoitem can take any value from the list that follows:
441 source_name
443 The name of the source of messages to which the binding is
444 attached. With non-ASCII characters escaped as in C.
445 source_kind
447 The kind of the source of messages to which the binding is
448 attached. Currently always queue. With non-ASCII characters
449 escaped as in C.
450 destination_name
452 The name of the destination of messages to which the binding is
453 attached. With non-ASCII characters escaped as in C.
454 destination_kind
456 The kind of the destination of messages to which the binding is
457 attached. With non-ASCII characters escaped as in C.
458 routing_key
460 The binding's routing key, with non-ASCII characters escaped as
461 in C.
462 arguments
464 The binding's arguments.
465 If no bindinginfoitems are specified then all above items are
467 displayed.
468 list_connections [connectioninfoitem ...]
470 Returns TCP/IP connection statistics.
471 The connectioninfoitem parameter is used to indicate which
473 connection information items to include in the results. The column
474 order in the results will match the order of the parameters.
475 connectioninfoitem can take any value from the list that follows:
476 pid
478 Id of the Erlang process associated with the connection.
479 address
481 Server IP address.
482 port
484 Server port.
485 peer_address
487 Peer address.
488 peer_port
490 Peer port.
491 ssl
493 Boolean indicating whether the connection is secured with SSL.
494 ssl_protocol
496 SSL protocol (e.g. tlsv1)
497 ssl_key_exchange
499 SSL key exchange algorithm (e.g. rsa)
500 ssl_cipher
502 SSL cipher algorithm (e.g. aes_256_cbc)
503 ssl_hash
505 SSL hash function (e.g. sha)
506 peer_cert_subject
508 The subject of the peer's SSL certificate, in RFC4514 form.
509 peer_cert_issuer
511 The issuer of the peer's SSL certificate, in RFC4514 form.
512 peer_cert_validity
514 The period for which the peer's SSL certificate is valid.
515 state
517 Connection state (one of [starting, tuning, opening, running,
518 closing, closed]).
519 channels
521 Number of channels using the connection.
522 protocol
524 Version of the AMQP protocol in use (currently one of {0,9,1}
525 or {0,8,0}). Note that if a client requests an AMQP 0-9
526 connection, we treat it as AMQP 0-9-1.
527 auth_mechanism
529 SASL authentication mechanism used, such as PLAIN.
530 user
532 Username associated with the connection.
533 vhost
535 Virtual host name with non-ASCII characters escaped as in C.
536 timeout
538 Connection timeout.
539 frame_max
541 Maximum frame size (bytes).
542 client_properties
544 Informational properties transmitted by the client during
545 connection establishment.
546 recv_oct
548 Octets received.
549 recv_cnt
551 Packets received.
552 send_oct
554 Octets send.
555 send_cnt
557 Packets sent.
558 send_pend
560 Send queue size.
561 If no connectioninfoitems are specified then user, peer address,
563 peer port and connection state are displayed.
564 list_channels [channelinfoitem ...]
566 Returns information on all current channels, the logical containers
567 executing most AMQP commands. This includes channels that are part
568 of ordinary AMQP connections, and channels created by various
569 plug-ins and other extensions.
570 The channelinfoitem parameter is used to indicate which channel
572 information items to include in the results. The column order in
573 the results will match the order of the parameters.
574 channelinfoitem can take any value from the list that follows:
575 pid
577 Id of the Erlang process associated with the connection.
578 connection
580 Id of the Erlang process associated with the connection to
581 which the channel belongs.
582 number
584 The number of the channel, which uniquely identifies it within
585 a connection.
586 user
588 Username associated with the channel.
589 vhost
591 Virtual host in which the channel operates.
592 transactional
594 True if the channel is in transactional mode, false otherwise.
595 confirm
597 True if the channel is in confirm mode, false otherwise.
598 consumer_count
600 Number of logical AMQP consumers retrieving messages via the
601 channel.
602 messages_unacknowledged
604 Number of messages delivered via this channel but not yet
605 acknowledged.
606 messages_uncommitted
608 Number of messages received in an as yet uncommitted
609 transaction.
610 acks_uncommitted
612 Number of acknowledgements received in an as yet uncommitted
613 transaction.
614 messages_unconfirmed
616 Number of published messages not yet confirmed. On channels not
617 in confirm mode, this remains 0.
618 prefetch_count
620 QoS prefetch count limit in force, 0 if unlimited.
621 client_flow_blocked
623 True if the client issued a channel.flow{active=false} command,
624 blocking the server from delivering messages to the channel's
625 consumers.
626 If no channelinfoitems are specified then pid, user,
628 consumer_count, and messages_unacknowledged are assumed.
629 list_consumers [-p vhostpath]
631 List consumers, i.e. subscriptions to a queue's message stream.
632 Each line printed shows, separated by tab characters, the name of
633 the queue subscribed to, the id of the channel process via which
634 the subscription was created and is managed, the consumer tag which
635 uniquely identifies the subscription within a channel, and a
636 boolean indicating whether acknowledgements are expected for
637 messages delivered to this consumer.
638 The output is a list of rows containing, in order, the queue name,
640 channel process id, consumer tag, and a boolean indicating whether
641 acknowledgements are expected from the consumer.
642 status
644 Displays broker status information such as the running applications
645 on the current Erlang node, RabbitMQ and Erlang versions and OS
646 name. (See the cluster_status command to find out which nodes are
647 clustered and running.)
648 environment
650 Display the name and value of each variable in the application
651 environment.
652 report
654 Generate a server status report containing a concatenation of all
655 server status information for support purposes. The output should
656 be redirected to a file when accompanying a support request.
657 Message Tracing
659 trace_on [-p vhost]
660 vhost
662 The name of the virtual host for which to start tracing.
663 Starts tracing.
665 trace_off [-p vhost]
667 vhost
669 The name of the virtual host for which to stop tracing.
670 Stops tracing.
672
674 rabbitmqctl stop
675 This command instructs the RabbitMQ node to terminate.
676 rabbitmqctl stop_app
678 This command instructs the RabbitMQ node to stop the RabbitMQ
679 application.
680 rabbitmqctl start_app
682 This command instructs the RabbitMQ node to start the RabbitMQ
683 application.
684 rabbitmqctl wait /var/run/rabbitmq/pid
686 This command will return when the RabbitMQ node has started up.
687 rabbitmqctl reset
689 This command resets the RabbitMQ node.
690 rabbitmqctl force_reset
692 This command resets the RabbitMQ node.
693 rabbitmqctl rotate_logs .1
695 This command instructs the RabbitMQ node to append the current
696 content of the log files to the files with names consisting of the
697 original logs' names and ".1" suffix, e.g. rabbit.log.1. Finally,
698 the old log files are reopened.
699 rabbitmqctl cluster rabbit@tanto hare@elena
701 This command instructs the RabbitMQ node to join the cluster with
702 nodes rabbit@tanto and hare@elena. If the node is one of these then
703 it becomes a disk node, otherwise a ram node.
704 rabbitmqctl cluster_status
706 This command displays the nodes in the cluster.
707 rabbitmqctl close_connection "<rabbit@tanto.4262.0>" "go away"
709 This command instructs the RabbitMQ broker to close the connection
710 associated with the Erlang process id <rabbit@tanto.4262.0>,
711 passing the explanation go away to the connected client.
712 rabbitmqctl add_user tonyg changeit
714 This command instructs the RabbitMQ broker to create a
715 (non-administrative) user named tonyg with (initial) password
716 changeit.
717 rabbitmqctl delete_user tonyg
719 This command instructs the RabbitMQ broker to delete the user named
720 tonyg.
721 rabbitmqctl change_password tonyg newpass
723 This command instructs the RabbitMQ broker to change the password
724 for the user named tonyg to newpass.
725 rabbitmqctl clear_password tonyg
727 This command instructs the RabbitMQ broker to clear the password
728 for the user named tonyg. This user now cannot log in with a
729 password (but may be able to through e.g. SASL EXTERNAL if
730 configured).
731 rabbitmqctl set_user_tags tonyg administrator
733 This command instructs the RabbitMQ broker to ensure the user named
734 tonyg is an administrator. This has no effect when the user logs in
735 via AMQP, but can be used to permit the user to manage users,
736 virtual hosts and permissions when the user logs in via some other
737 means (for example with the management plugin).
738 This command instructs the RabbitMQ broker to remove any tags from
740 the user named tonyg.
741 rabbitmqctl set_user_tags tonyg
743 This command instructs the RabbitMQ broker to remove any tags from
744 the user named tonyg.
745 rabbitmqctl list_users
747 This command instructs the RabbitMQ broker to list all users.
748 rabbitmqctl add_vhost test
750 This command instructs the RabbitMQ broker to create a new virtual
751 host called test.
752 rabbitmqctl delete_vhost test
754 This command instructs the RabbitMQ broker to delete the virtual
755 host called test.
756 rabbitmqctl list_vhosts name tracing
758 This command instructs the RabbitMQ broker to list all virtual
759 hosts.
760 rabbitmqctl set_permissions -p /myvhost tonyg "^tonyg-.*" ".*" ".*"
762 This command instructs the RabbitMQ broker to grant the user named
763 tonyg access to the virtual host called /myvhost, with configure
764 permissions on all resources whose names starts with "tonyg-", and
765 write and read permissions on all resources.
766 rabbitmqctl clear_permissions -p /myvhost tonyg
768 This command instructs the RabbitMQ broker to deny the user named
769 tonyg access to the virtual host called /myvhost.
770 rabbitmqctl list_permissions -p /myvhost
772 This command instructs the RabbitMQ broker to list all the users
773 which have been granted access to the virtual host called /myvhost,
774 and the permissions they have for operations on resources in that
775 virtual host. Note that an empty string means no permissions
776 granted.
777 rabbitmqctl list_user_permissions tonyg
779 This command instructs the RabbitMQ broker to list all the virtual
780 hosts to which the user named tonyg has been granted access, and
781 the permissions the user has for operations on resources in these
782 virtual hosts.
783 rabbitmqctl list_queues -p /myvhost messages consumers
785 This command displays the depth and number of consumers for each
786 queue of the virtual host named /myvhost.
787 rabbitmqctl list_exchanges -p /myvhost name type
789 This command displays the name and type for each exchange of the
790 virtual host named /myvhost.
791 rabbitmqctl list_bindings -p /myvhost exchange_name queue_name
793 This command displays the exchange name and queue name of the
794 bindings in the virtual host named /myvhost.
795 rabbitmqctl list_connections send_pend port
797 This command displays the send queue size and server port for each
798 connection.
799 rabbitmqctl list_channels connection messages_unacknowledged
801 This command displays the connection process and count of
802 unacknowledged messages for each channel.
803 rabbitmqctl status
805 This command displays information about the RabbitMQ broker.
806 rabbitmqctl report > server_report.txt
808 This command creates a server report which may be attached to a
809 support request email.
810
812 The RabbitMQ Team <info@rabbitmq.com>
813
815 1. installation guide
816 http://www.rabbitmq.com/install.html
817 2. clustering guide
819 http://www.rabbitmq.com/clustering.html
820RabbitMQ Server 11/08/2011 RABBITMQCTL(1)