/
rabbitmqctl.8
2559 lines (2558 loc) · 77.1 KB
/
rabbitmqctl.8
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.\" vim:ft=nroff:
.\" This Source Code Form is subject to the terms of the Mozilla Public
.\" License, v. 2.0. If a copy of the MPL was not distributed with this
.\" file, You can obtain one at https://mozilla.org/MPL/2.0/.
.\"
.\" Copyright (c) 2007-2022 VMware, Inc. or its affiliates. All rights reserved.
.\"
.Dd October 26, 2022
.Dt RABBITMQCTL 8
.Os "RabbitMQ Server"
.Sh NAME
.Nm rabbitmqctl
.Nd tool for managing RabbitMQ nodes
.\" ------------------------------------------------------------------------------------------------
.Sh SYNOPSIS
.\" ------------------------------------------------------------------------------------------------
.Nm
.Op Fl q
.Op Fl s
.Op Fl l
.Op Fl n Ar node
.Op Fl t Ar timeout
.Ar command
.Op Ar command_options
.\" ------------------------------------------------------------------------------------------------
.Sh DESCRIPTION
.\" ------------------------------------------------------------------------------------------------
RabbitMQ is an open source multi-protocol messaging broker.
.Pp
.Nm
is the main command line tool for managing a RabbitMQ server node,
together with
.Cm rabbitmq-diagnostics
,
.Cm rabbitmq-upgrade
, and others.
.Pp
It performs all actions by connecting to the target RabbitMQ node
on a dedicated CLI tool communication port and authenticating
using a shared secret (known as the cookie file).
.Pp
Diagnostic information is displayed if connection failed,
the target node was not running, or
.Nm
could not authenticate to
the target node successfully.
To learn more, see the
.Lk https://rabbitmq.com/cli.html "RabbitMQ CLI Tools guide"
.\" ------------------------------------------------------------------------------------------------
.Sh OPTIONS
.\" ------------------------------------------------------------------------------------------------
.Bl -tag -width Ds
.It Fl n Ar node
Default node is
.Qq Ar rabbit@target-hostname ,
where
.Ar target-hostname
is the local host.
On a host named
.Qq myserver.example.com ,
the node name will usually be
.Qq rabbit@myserver
(unless
.Ev RABBITMQ_NODENAME
has been overridden).
The output of
.Qq hostname -s
is usually the correct suffix to use after the
.Qq @
sign.
See
.Xr rabbitmq-server 8
for details of configuring a RabbitMQ node.
.It Fl q , -quiet
Quiet output mode is selected.
Informational messages are reduced when quiet mode is in effect.
.It Fl s , -silent
Silent output mode is selected.
Informational messages are reduced and table headers are suppressed when silent mode is in effect.
.It Fl -no-table-headers
Do not output headers for tabular data.
.It Fl -dry-run
Do not run the command.
Only print information message.
.It Fl t Ar timeout , Fl -timeout Ar timeout
Operation timeout in seconds.
Not all commands support timeouts.
Default is
.Cm infinity .
.It Fl l , Fl -longnames
Must be specified when the cluster is configured to use long (FQDN) node names.
To learn more, see the
.Lk https://www.rabbitmq.com/clustering.html "RabbitMQ Clustering guide"
.It Fl -erlang-cookie Ar cookie
Shared secret to use to authenticate to the target node.
Prefer using a local file or the
.Ev RABBITMQ_ERLANG_COOKIE
environment variable instead of specifying this option on the command line.
To learn more, see the
.Lk https://www.rabbitmq.com/cli.html "RabbitMQ CLI Tools guide"
.El
.\" ------------------------------------------------------------------------------------------------
.Sh COMMANDS
.\" ------------------------------------------------------------------------------------------------
.Bl -tag -width Ds
.It Cm help Oo Fl l Oc Op Ar command_name
.Pp
Prints usage for all available commands.
.Bl -tag -width Ds
.It Fl l , Fl -list-commands
List command usages only, without parameter explanation.
.It Ar command_name
Prints usage for the specified command.
.El
.\" ------------------------------------------------------------------
.It Cm version
.Pp
Displays CLI tools version
.El
.\" ------------------------------------------------------------------
.\" ## Nodes
.\" ------------------------------------------------------------------
.Ss Nodes
.Bl -tag -width Ds
.\" ------------------------------------------------------------------
.It Cm await_startup
.Pp
Waits for the RabbitMQ application to start on the target node
.Pp
For example, to wait for the RabbitMQ application to start:
.sp
.Dl rabbitmqctl await_startup
.\" ------------------------------------------------------------------
.It Cm reset
.Pp
Returns a RabbitMQ node to its virgin state.
.Pp
Removes the node from any cluster it belongs to, removes all data from
the management database, such as configured users and vhosts, and
deletes all persistent messages.
.Pp
For
.Cm reset
and
.Cm force_reset
to succeed the RabbitMQ application must have been stopped, e.g. with
.Cm stop_app .
.Pp
For example, to reset the RabbitMQ node:
.sp
.Dl rabbitmqctl reset
.\" ------------------------------------------------------------------
.It Cm rotate_logs
.Pp
Instructs the RabbitMQ node to perform internal log rotation.
.Pp
Log rotation is performed according to the logging settings specified in the configuration file.
The rotation operation is asynchronous, there is no guarantee that it has completed when this command returns.
.Pp
Note that there is no need to call this command in case of external log rotation (e.g. from logrotate(8)).
.Pp
For example, to initial log rotation:
.sp
.Dl rabbitmqctl rotate_logs
.\" ------------------------------------------------------------------
.It Cm shutdown
.Pp
Shuts down the node, both RabbitMQ and its runtime.
The command is blocking and will return after the runtime process exits.
If RabbitMQ fails to stop, it will return a non-zero exit code.
This command infers the OS PID of the target node and
therefore can only be used to shut down nodes running on the same
host (or broadly speaking, in the same operating system,
e.g. in the same VM or container)
.Pp
Unlike the stop command, the shutdown command:
.Bl -bullet
.It
does not require a
.Ar pid_file
to wait for the runtime process to exit
.It
returns a non-zero exit code if RabbitMQ node is not running
.El
.Pp
For example, this will shut down a locally running RabbitMQ node
with default node name:
.sp
.Dl rabbitmqctl shutdown
.\" ------------------------------------------------------------------
.It Cm start_app
.Pp
Starts the RabbitMQ application.
.Pp
This command is typically run after performing other management actions
that required the RabbitMQ application to be stopped, e.g.\&
.Cm reset .
.Pp
For example, to instruct the RabbitMQ node to start the RabbitMQ
application:
.sp
.Dl rabbitmqctl start_app
.\" ------------------------------------------------------------------
.It Cm stop Op Ar pid_file
.Pp
Stops the Erlang node on which RabbitMQ is running.
To restart the node follow the instructions for
.Qq Running the Server
in the
.Lk https://rabbitmq.com/download.html installation guide .
.Pp
If a
.Ar pid_file
is specified, also waits for the process specified there to terminate.
See the description of the
.Cm wait
command for details on this file.
.Pp
For example, to instruct the RabbitMQ node to terminate:
.sp
.Dl rabbitmqctl stop
.\" ------------------------------------------------------------------
.It Cm stop_app
.Pp
Stops the RabbitMQ application, leaving the runtime (Erlang VM) running.
.Pp
This command is typically run prior to performing other management
actions that require the RabbitMQ application to be stopped, e.g.\&
.Cm reset .
.Pp
For example, to instruct the RabbitMQ node to stop the RabbitMQ
application:
.sp
.Dl rabbitmqctl stop_app
.\" ------------------------------------------------------------------
.It Cm wait Ar pid_file , Cm wait Fl -pid Ar pid
.Pp
Waits for the RabbitMQ application to start.
.Pp
This command will wait for the RabbitMQ application to start at the
node.
It will wait for the pid file to be created if
.Ar pidfile
is specified, then for a process with a pid specified in the pid file or
the
.Fl -pid
argument, and then for the RabbitMQ application to start in that process.
It will fail if the process terminates without starting the RabbitMQ
application.
.Pp
If the specified pidfile is not created or erlang node is not started within
.Fl -timeout
the command will fail.
Default timeout is 10 seconds.
.Pp
A suitable pid file is created by the
.Xr rabbitmq-server 8
script.
By default this is located in the Mnesia directory.
Modify the
.Ev RABBITMQ_PID_FILE
environment variable to change the location.
.Pp
For example, this command will return when the RabbitMQ node has started
up:
.sp
.Dl rabbitmqctl wait /var/run/rabbitmq/pid
.El
.\" ------------------------------------------------------------------
.\" ## Cluster Operations
.\" ------------------------------------------------------------------
.Ss Cluster management
.Bl -tag -width Ds
.\" ------------------------------------------------------------------
.It Cm await_online_nodes Ar count
.Pp
Waits for
.Ar count
nodes to join the cluster
.Pp
For example, to wait for two RabbitMQ nodes to start:
.sp
.Dl rabbitmqctl await_online_nodes 2
.\" ------------------------------------------------------------------
.It Cm change_cluster_node_type Ar type
.Pp
Changes the type of the cluster node.
.Pp
The
.Ar type
must be one of the following:
.Bl -bullet -compact
.It
.Cm disc
.It
.Cm ram
.El
.Pp
The node must be stopped for this operation to succeed, and when turning
a node into a RAM node the node must not be the only disc node in the
cluster.
.Pp
For example, this command will turn a RAM node into a disc node:
.sp
.Dl rabbitmqctl change_cluster_node_type disc
.\" ------------------------------------------------------------------
.It Cm cluster_status
.Pp
Displays all the nodes in the cluster grouped by node type, together
with the currently running nodes.
.Pp
For example, this command displays the nodes in the cluster:
.sp
.Dl rabbitmqctl cluster_status
.\" ------------------------------------------------------------------
.It Cm force_boot
.Pp
Ensures that the node will start next time, even if it was not the last
to shut down.
.Pp
Normally when you shut down a RabbitMQ cluster altogether, the first
node you restart should be the last one to go down, since it may have
seen things happen that other nodes did not.
But sometimes that's not possible: for instance if the entire cluster
loses power then all nodes may think they were not the last to shut
down.
.Pp
In such a case you can invoke
.Cm force_boot
while the node is down.
This will tell the node to unconditionally start next time you ask it
to.
If any changes happened to the cluster after this node shut down, they
will be lost.
.Pp
If the last node to go down is permanently lost then you should use
.Cm forget_cluster_node Fl -offline
in preference to this command, as it will ensure that mirrored queues
which had their leader replica on the lost node get promoted.
.Pp
For example, this will force the node not to wait for other nodes next
time it is started:
.sp
.Dl rabbitmqctl force_boot
.\" ------------------------------------------------------------------
.It Cm force_reset
.Pp
Forcefully returns a RabbitMQ node to its virgin state.
.Pp
The
.Cm force_reset
command differs from
.Cm reset
in that it resets the node unconditionally, regardless of the current
management database state and cluster configuration.
It should only be used as a last resort if the database or cluster
configuration has been corrupted.
.Pp
For
.Cm reset
and
.Cm force_reset
to succeed the RabbitMQ application must have been stopped, e.g. with
.Cm stop_app .
.Pp
For example, to reset the RabbitMQ node:
.sp
.Dl rabbitmqctl force_reset
.\" ------------------------------------------------------------------
.It Cm forget_cluster_node Op Fl -offline
.Bl -tag -width Ds
.It Fl -offline
Enables node removal from an offline node.
This is only useful in the situation where all the nodes are offline and
the last node to go down cannot be brought online, thus preventing the
whole cluster from starting.
It should not be used in any other circumstances since it can lead to
inconsistencies.
.El
.Pp
Removes a cluster node remotely.
The node that is being removed must be offline, while the node we are
removing from must be online, except when using the
.Fl -offline
flag.
.Pp
When using the
.Fl -offline
flag ,
.Nm
will not attempt to connect to a node as normal; instead it will
temporarily become the node in order to make the change.
This is useful if the node cannot be started normally.
In this case the node will become the canonical source for cluster
metadata (e.g. which queues exist), even if it was not before.
Therefore you should use this command on the latest node to shut down if
at all possible.
.Pp
For example, this command will remove the node
.Qq rabbit@stringer
from the node
.Qq hare@mcnulty :
.sp
.Dl rabbitmqctl -n hare@mcnulty forget_cluster_node rabbit@stringer
.\" ------------------------------------------------------------------
.It Cm join_cluster Ar seed-node Op Fl -ram
.Bl -tag -width Ds
.It Ar seed-node
Existing cluster member (seed node) to cluster with.
.It Fl -ram
If provided, the node will join the cluster as a RAM node.
RAM node use is discouraged. Use only if you understand why
exactly you need to use them.
.El
.Pp
Instructs the node to become a member of the cluster that the specified
node is in.
Before clustering, the node is reset, so be careful when using this
command.
For this command to succeed the RabbitMQ application must have been
stopped, e.g. with
.Cm stop_app .
.Pp
Cluster nodes can be of two types: disc or RAM.
Disc nodes replicate data in RAM and on disc, thus providing redundancy
in the event of node failure and recovery from global events such as
power failure across all nodes.
RAM nodes replicate data in RAM only (with the exception of queue
contents, which can reside on disc if the queue is persistent or too big
to fit in memory) and are mainly used for scalability.
RAM nodes are more performant only when managing resources (e.g.\&
adding/removing queues, exchanges, or bindings).
A cluster must always have at least one disc node, and usually should
have more than one.
.Pp
The node will be a disc node by default.
If you wish to create a RAM node, provide the
.Fl -ram
flag.
.Pp
After executing the
.Cm join_cluster
command, whenever the RabbitMQ application is started on the current
node it will attempt to connect to the nodes that were in the cluster
when the node went down.
.Pp
To leave a cluster,
.Cm reset
the node.
You can also remove nodes remotely with the
.Cm forget_cluster_node
command.
.Pp
For example, this command instructs the RabbitMQ node to join the cluster that
.Qq hare@elena
is part of, as a ram node:
.sp
.Dl rabbitmqctl join_cluster hare@elena --ram
.Pp
To learn more, see the
.Lk https://www.rabbitmq.com/clustering.html "RabbitMQ Clustering guide".
.\" ------------------------------------------------------------------
.It Cm rename_cluster_node Ar oldnode1 Ar newnode1 Op Ar oldnode2 Ar newnode2 ...
.Pp
Supports renaming of cluster nodes in the local database.
.Pp
This subcommand causes
.Nm
to temporarily become the node in order to make the change.
The local cluster node must therefore be completely stopped; other nodes
can be online or offline.
.Pp
This subcommand takes an even number of arguments, in pairs representing
the old and new names for nodes.
You must specify the old and new names for this node and for any other
nodes that are stopped and being renamed at the same time.
.Pp
It is possible to stop all nodes and rename them all simultaneously (in
which case old and new names for all nodes must be given to every node)
or stop and rename nodes one at a time (in which case each node only
needs to be told how its own name is changing).
.Pp
For example, this command will rename the node
.Qq rabbit@misshelpful
to the node
.Qq rabbit@cordelia
.sp
.Dl rabbitmqctl rename_cluster_node rabbit@misshelpful rabbit@cordelia
.Pp
Note that this command only changes the local database.
It may also be necessary to rename the local database directories,
and to configure the new node name.
For example:
.sp
.Bl -enum -compact
.It
Stop the node:
.sp
.Dl rabbitmqctl stop rabbit@misshelpful
.sp
.It
Rename the node in the local database:
.sp
.Dl rabbitmqctl rename_cluster_node rabbit@misshelpful rabbit@cordelia
.sp
.It
Rename the local database directories (note, you do not need to do this
if you have set the RABBITMQ_MNESIA_DIR environment variable):
.sp
.Bd -literal -offset indent -compact
mv \\
/var/lib/rabbitmq/mnesia/rabbit\\@misshelpful \\
/var/lib/rabbitmq/mnesia/rabbit\\@cordelia
mv \\
/var/lib/rabbitmq/mnesia/rabbit\\@misshelpful-rename \\
/var/lib/rabbitmq/mnesia/rabbit\\@cordelia-rename
mv \\
/var/lib/rabbitmq/mnesia/rabbit\\@misshelpful-plugins-expand \\
/var/lib/rabbitmq/mnesia/rabbit\\@cordelia-plugins-expand
.Ed
.sp
.It
If node name is configured e.g. using
.Ar /etc/rabbitmq/rabbitmq-env.conf
it has also be updated there.
.sp
.It
Start the node when ready
.El
.\" ------------------------------------------------------------------
.It Cm update_cluster_nodes Ar clusternode
.Bl -tag -width Ds
.It Ar clusternode
The node to consult for up-to-date information.
.El
.Pp
Instructs an already clustered node to contact
.Ar clusternode
to cluster when booting up.
This is different from
.Cm join_cluster
since it does not join any cluster - it checks that the node is already
in a cluster with
.Ar clusternode .
.Pp
The need for this command is motivated by the fact that clusters can
change while a node is offline.
Consider a situation where node
.Va rabbit@A
and
.Va rabbit@B
are clustered.
.Va rabbit@A
goes down,
.Va rabbit@C
clusters with
.Va rabbit@B ,
and then
.Va rabbit@B
leaves the cluster.
When
.Va rabbit@A
starts back up, it'll try to contact
.Va rabbit@B ,
but this will fail since
.Va rabbit@B
is not in the cluster anymore.
The following command will rename node
.Va rabbit@B
to
.Va rabbit@C
on node
.Va rabbitA
.sp
.Dl update_cluster_nodes -n Va rabbit@A Va rabbit@B Va rabbit@C
.Pp
To learn more, see the
.Lk https://www.rabbitmq.com/clustering.html "RabbitMQ Clustering guide"
.El
.\" ------------------------------------------------------------------
.\" ## Classic Mirrored Queues
.\" ------------------------------------------------------------------
.Ss Replication
.Bl -tag -width Ds
.\" ------------------------------------------------------------------
.It Cm sync_queue Oo Fl p Ar vhost Oc Ar queue
.Bl -tag -width Ds
.It Ar queue
The name of the queue to synchronise.
.El
.Pp
Instructs a mirrored queue with unsynchronised mirrors (follower replicas)
to synchronise them.
The queue will block while synchronisation takes place (all publishers
to and consumers using the queue will block or temporarily see no activity).
This command can only be used with mirrored queues.
To learn more, see the
.Lk https://www.rabbitmq.com/ha.html "RabbitMQ Mirroring guide"
.Pp
Note that queues with unsynchronised replicas and active consumers
will become synchronised eventually (assuming that consumers make progress).
This command is primarily useful for queues which do not have active consumers.
.\" ------------------------------------------------------------------
.It Cm cancel_sync_queue Oo Fl p Ar vhost Oc Ar queue
.Bl -tag -width Ds
.It Ar queue
The name of the queue to cancel synchronisation for.
.El
.Pp
Instructs a synchronising mirrored queue to stop synchronising itself.
.El
.\" ------------------------------------------------------------------
.\" ## User management
.\" ------------------------------------------------------------------
.Ss User Management
Note that all user management commands
.Nm
only can manage users in the internal RabbitMQ database.
Users from any alternative authentication backends such as LDAP cannot be inspected
or managed with those commands.
.Nm .
.Bl -tag -width Ds
.\" ------------------------------------------------------------------
.It Cm add_user Ar username Ar password
.Bl -tag -width Ds
.It Ar username
The name of the user to create.
.It Ar password
The password the created user will use to log in to the broker.
.El
.Pp
For example, this command instructs the RabbitMQ broker to create a (non-administrative) user named
.Qq janeway
with (initial) password
.Qq changeit :
.sp
.Dl rabbitmqctl add_user janeway changeit
.\" ------------------------------------------------------------------
.It Cm authenticate_user Ar username Ar password
.Bl -tag -width Ds
.It Ar username
The name of the user.
.It Ar password
The password of the user.
.El
.Pp
For example, this command instructs the RabbitMQ broker to authenticate the user named
.Qq janeway
with password
.Qq verifyit :
.sp
.Dl rabbitmqctl authenticate_user janeway verifyit
.\" ------------------------------------------------------------------
.It Cm change_password Ar username Ar newpassword
.Bl -tag -width Ds
.It Ar username
The name of the user whose password is to be changed.
.It Ar newpassword
The new password for the user.
.El
.Pp
For example, this command instructs the RabbitMQ broker to change the
password for the user named
.Qq janeway
to
.Qq newpass :
.sp
.Dl rabbitmqctl change_password janeway newpass
.\" ------------------------------------------------------------------
.It Cm clear_password Ar username
.Bl -tag -width Ds
.It Ar username
The name of the user whose password is to be cleared.
.El
.Pp
For example, this command instructs the RabbitMQ broker to clear the
password for the user named
.Qq janeway :
.sp
.Dl rabbitmqctl clear_password janeway
.Pp
This user now cannot log in with a password (but may be able to through
e.g. SASL EXTERNAL if configured).
.\" ------------------------------------------------------------------
.It Cm delete_user Ar username
.Bl -tag -width Ds
.It Ar username
The name of the user to delete.
.El
.Pp
For example, this command instructs the RabbitMQ broker to delete the user named
.Qq janeway :
.sp
.Dl rabbitmqctl delete_user janeway
.\" ------------------------------------------------------------------
.It Cm list_users
.Pp
Lists users.
Each result row will contain the user name followed by a list of the
tags set for that user.
.Pp
For example, this command instructs the RabbitMQ broker to list all users:
.sp
.Dl rabbitmqctl list_users
.\" ------------------------------------------------------------------
.It Cm set_user_tags Ar username Op Ar tag ...
.Bl -tag -width Ds
.It Ar username
The name of the user whose tags are to be set.
.It Ar tag
Zero, one or more tags to set.
Any existing tags will be removed.
.El
.Pp
For example, this command instructs the RabbitMQ broker to ensure the user named
.Qq janeway
is an administrator:
.sp
.Dl rabbitmqctl set_user_tags janeway administrator
.Pp
This has no effect when the user authenticates using a messaging protocol, but can be used to
permit the user to manage users, virtual hosts and permissions when
the user logs in via some other means (for example with the management
plugin).
.Pp
This command instructs the RabbitMQ broker to remove any tags from the user named
.Qq janeway :
.sp
.Dl rabbitmqctl set_user_tags janeway
.El
.\" ------------------------------------------------------------------
.\" ## Access Control
.\" ------------------------------------------------------------------
.Ss Access control
.Bl -tag -width Ds
.\" ------------------------------------------------------------------
.It Cm clear_permissions Oo Fl p Ar vhost Oc Ar username
.Bl -tag -width Ds
.It Ar vhost
The name of the virtual host to which to deny the user access,
defaulting to
.Qq / .
.It Ar username
The name of the user to deny access to the specified virtual host.
.El
.Pp
Sets user permissions.
.Pp
For example, this command instructs the RabbitMQ broker to deny the user
named
.Qq janeway
access to the virtual host called
.Qq my-vhost :
.sp
.Dl rabbitmqctl clear_permissions -p my-vhost janeway
.\" ------------------------------------------------------------------
.It Cm clear_topic_permissions Oo Fl p Ar vhost Oc Ar username Oo Ar exchange Oc
.Bl -tag -width Ds
.It Ar vhost
The name of the virtual host to which to clear the topic permissions,
defaulting to
.Qq / .
.It Ar username
The name of the user to clear topic permissions to the specified virtual host.
.It Ar exchange
The name of the topic exchange to clear topic permissions, defaulting to all the
topic exchanges the given user has topic permissions for.
.El
.Pp
Clear user topic permissions.
.Pp
For example, this command instructs the RabbitMQ broker to remove topic permissions for user
named
.Qq janeway
for the topic exchange
.Qq amq.topic
in the virtual host called
.Qq my-vhost :
.sp
.Dl rabbitmqctl clear_topic_permissions -p my-vhost janeway amq.topic
.\" ------------------------------------------------------------------
.It Cm list_permissions Op Fl p Ar vhost
.Bl -tag -width Ds
.It Ar vhost
The name of the virtual host for which to list the users that have been
granted access to it, and their permissions.
Defaults to
.Qq / .
.El
.Pp
Lists permissions in a virtual host.
.Pp
For example, this command instructs the RabbitMQ broker to list all the
users which have been granted access to the virtual host called
.Qq my-vhost ,
and the permissions they have for operations on resources in that
virtual host.
Note that an empty string means no permissions granted:
.sp
.Dl rabbitmqctl list_permissions -p my-vhost
.\" ------------------------------------------------------------------
.It Cm list_topic_permissions Op Fl p Ar vhost
.Bl -tag -width Ds
.It Ar vhost
The name of the virtual host for which to list the users topic permissions.
Defaults to
.Qq / .
.El
.Pp
Lists topic permissions in a virtual host.
.Pp
For example, this command instructs the RabbitMQ broker to list all the
users which have been granted topic permissions in the virtual host called
.Qq my-vhost:
.sp
.Dl rabbitmqctl list_topic_permissions -p my-vhost
.\" ------------------------------------------------------------------
.It Cm list_user_permissions Ar username
.Bl -tag -width Ds
.It Ar username
The name of the user for which to list the permissions.
.El
.Pp
Lists user permissions.
.Pp
For example, this command instructs the RabbitMQ broker to list all the
virtual hosts to which the user named
.Qq janeway
has been granted access, and the permissions the user has for operations
on resources in these virtual hosts:
.sp
.Dl rabbitmqctl list_user_permissions janeway
.\" ------------------------------------------------------------------
.It Cm list_user_topic_permissions Ar username
.Bl -tag -width Ds
.It Ar username
The name of the user for which to list the topic permissions.
.El
.Pp
Lists user topic permissions.
.Pp
For example, this command instructs the RabbitMQ broker to list all the
virtual hosts to which the user named
.Qq janeway
has been granted access, and the topic permissions the user has in these virtual hosts:
.sp
.Dl rabbitmqctl list_user_topic_permissions janeway
.\" ------------------------------------------------------------------
.It Cm list_vhosts Op Ar vhostinfoitem ...
.Pp
Lists virtual hosts.
.Pp
The
.Ar vhostinfoitem
parameter is used to indicate which virtual host information items to
include in the results.
The column order in the results will match the order of the parameters.
.Ar vhostinfoitem
can take any value from the list that follows:
.Bl -tag -width Ds
.It Cm name
The name of the virtual host with non-ASCII characters escaped as in C.
.It Cm tracing
Whether tracing is enabled for this virtual host.
.It Cm default_queue_type
Default queue type for this vhost.
.It Cm description
Virtual host description.
.It Cm tags
Virtual host tags.
.It Cm cluster_state
Virtual host state: nodedown, running, stopped.
.El
.Pp
If no
.Ar vhostinfoitem
are specified then the vhost name is displayed.
.Pp
For example, this command instructs the RabbitMQ broker to list all
virtual hosts:
.sp
.Dl rabbitmqctl list_vhosts name tracing
.\" ------------------------------------------------------------------
.It Cm set_permissions Oo Fl p Ar vhost Oc Ar user Ar conf Ar write Ar read
.Bl -tag -width Ds
.It Ar vhost
The name of the virtual host to which to grant the user access,
defaulting to
.Qq / .
.It Ar user
The name of the user to grant access to the specified virtual host.
.It Ar conf
A regular expression matching resource names for which the user is
granted configure permissions.
.It Ar write
A regular expression matching resource names for which the user is
granted write permissions.
.It Ar read
A regular expression matching resource names for which the user is
granted read permissions.
.El
.Pp
Sets user permissions.
.Pp
For example, this command instructs the RabbitMQ broker to grant the
user named
.Qq janeway
access to the virtual host called
.Qq my-vhost ,
with configure permissions on all resources whose names starts with
.Qq janeway- ,
and write and read permissions on all resources:
.sp
.Dl rabbitmqctl set_permissions -p my-vhost janeway Qo ^janeway-.* Qc Qo .* Qc Qq .*
.\" ------------------------------------------------------------------
.It Cm set_topic_permissions Oo Fl p Ar vhost Oc Ar user Ar exchange Ar write Ar read
.Bl -tag -width Ds
.It Ar vhost
The name of the virtual host to which to grant the user access,
defaulting to
.Qq / .
.It Ar user
The name of the user the permissions apply to in the target virtual host.
.It Ar exchange
The name of the topic exchange the authorisation check will be applied to.
.It Ar write
A regular expression matching the routing key of the published message.
.It Ar read
A regular expression matching the routing key of the consumed message.
.El
.Pp
Sets user topic permissions.
.Pp
For example, this command instructs the RabbitMQ broker to let the
user named
.Qq janeway
publish and consume messages going through the
.Qq amp.topic
exchange of the
.Qq my-vhost
virtual host with a routing key starting with
.Qq janeway- :
.sp
.Dl rabbitmqctl set_topic_permissions -p my-vhost janeway amq.topic Qo ^janeway-.* Qc Qo ^janeway-.* Qc
.Pp
Topic permissions support variable expansion for the following variables:
username, vhost, and client_id. Note that client_id is expanded only when using MQTT.
The previous example could be made more generic by using
.Qq ^{username}-.* :
.sp
.Dl rabbitmqctl set_topic_permissions -p my-vhost janeway amq.topic Qo ^{username}-.* Qc Qo ^{username}-.* Qc
.El
.\" ------------------------------------------------------------------
.\" ## Monitoring and Observability
.\" ------------------------------------------------------------------
.Ss Monitoring, observability and health checks
.Bl -tag -width Ds
.\" ------------------------------------------------------------------
.It Cm environment
.Pp
Displays the name and value of each variable in the application
environment for each running application.
.\" ------------------------------------------------------------------
.It Cm list_bindings Oo Fl p Ar vhost Oc Op Ar bindinginfoitem ...
.Pp
Returns binding details.
By default the bindings for the
.Qq /
virtual host are returned.
The
.Fl p
flag can be used to override this default.
.Pp
The
.Ar bindinginfoitem
parameter is used to indicate which binding information items to include
in the results.
The column order in the results will match the order of the parameters.
.Ar bindinginfoitem
can take any value from the list that follows:
.Bl -tag -width Ds
.It Cm source_name
The name of the source of messages to which the binding is attached.
With non-ASCII characters escaped as in C.
.It Cm source_kind
The kind of the source of messages to which the binding is attached.
Currently always exchange.
With non-ASCII characters escaped as in C.
.It Cm destination_name
The name of the destination of messages to which the binding is
attached.
With non-ASCII characters escaped as in C.
.It Cm destination_kind
The kind of the destination of messages to which the binding is
attached.
With non-ASCII characters escaped as in C.
.It Cm routing_key
The binding's routing key, with non-ASCII characters escaped as in C.
.It Cm arguments