diff --git a/docs/rabbitmq-diagnostics.8 b/docs/rabbitmq-diagnostics.8 index f805bb40b8..73c8649f51 100644 --- a/docs/rabbitmq-diagnostics.8 +++ b/docs/rabbitmq-diagnostics.8 @@ -130,18 +130,368 @@ results. The default value is .Qq / . .Bl -tag -width Ds +.El +.El +.Ss Help +.Bl -tag -width Ds .\" ------------------------------------ .It Cm help .Pp Displays general help and commands supported by .Nm . .\" ------------------------------------ -.It Cm ping +.It Cm version .Pp -Most basic health check. Succeeds if target node (runtime) is running -and -.Nm -can authenticate with it successfully. +Displays CLI tools version +.El +.El +.Ss Nodes +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm wait +See +.Cm wait +in +.Xr rabbitmqctl 8 +.El +.El +.Ss Cluster +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm cluster_status +See +.Cm cluster_status +in +.Xr rabbitmqctl 8 +.El +.El +.Ss Users +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm list_users +See +.Cm list_users +in +.Xr rabbitmqctl 8 +.El +.El +.Ss Access Control +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm list_permissions Op Fl p Ar vhost +See +.Cm list_permissions +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_topic_permissions Op Fl p Ar vhost +See +.Cm list_topic_permissions +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_user_permissions Ar username +See +.Cm list_user_permissions +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_user_topic_permissions Ar username +See +.Cm list_user_topic_permissions +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_vhosts Op Ar vhostinfoitem ... +See +.Cm list_vhosts +in +.Xr rabbitmqctl 8 +.El +.El +.Ss Monitoring, observability and health checks +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm alarms +.Pp +Lists resource alarms, if any, in the cluster. +.Pp +See +.Lk https://www.rabbitmq.com/alarms.html "RabbitMQ Resource Alarms guide" +to learn more. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics alarms +.\" ------------------------------------ +.It Cm check_alarms +.Pp +Health check that fails (returns with a non-zero code) if there are alarms +in effect on any of the cluster nodes. +.Pp +See +.Lk https://www.rabbitmq.com/alarms.html "RabbitMQ Resource Alarms guide" +to learn more. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics check_alarms +.\" ------------------------------------ +.It Cm check_local_alarms +.Pp +Health check that fails (returns with a non-zero code) if there are alarms +in effect on the target node. +.Pp +See +.Lk https://www.rabbitmq.com/alarms.html "RabbitMQ Resource Alarms guide" +to learn more. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics check_local_alarms +.\" ------------------------------------ +.It Cm check_port_connectivity +.Pp +Health check that fails (returns with a non-zero code) if any listener ports +on the target node cannot accept a new TCP connection opened by +.Nm. +The check only validates if a new TCP connection is accepted. It does not +perform messaging protocol handshake or authenticate. +.Pp +See +.Lk https://www.rabbitmq.com/networking.html "RabbitMQ Networking guide" +to learn more. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics check_port_connectivity +.\" ------------------------------------ +.It Cm check_port_listener +.Pp +Health check that fails (returns with a non-zero code) if the target node +is not listening on the specified port (there is no listener that +uses that port). +.Pp +See +.Lk https://www.rabbitmq.com/networking.html "RabbitMQ Networking guide" +to learn more. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics check_port_listener 5672 +.\" ------------------------------------ +.It Cm check_protocol_listener +.Pp +Health check that fails (returns with a non-zero code) if the target node +does not have a listener for the specified protocol. +.Pp +See +.Lk https://www.rabbitmq.com/networking.html "RabbitMQ Networking guide" +to learn more. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics check_protocol_listener mqtt +.\" ------------------------------------ +.It Cm check_running +.Pp +Health check that fails (returns with a non-zero code) if the RabbitMQ +application is not running on the target node. +.Pp +If +.Cm rabbitmqctl(8) +was used to stop the application, this check will fail. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics check_running +.\" ------------------------------------ +.It Cm check_virtual_hosts +.Pp +Health check that checks if all vhosts are running in the target node +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics check_virtual_hosts --timeout 60 +.\" ------------------------------------ +.It Cm cipher_suites +.Pp +Lists cipher suites enabled by default. To list all available cipher suites, add the --all argument. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics cipher_suites --format openssl --all +.\" ------------------------------------ +.It Cm command_line_arguments +.Pp +Displays target node's command-line arguments and flags as reported by the runtime. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics command_line_arguments -n rabbit@hostname +.\" ------------------------------------ +.It Cm consume_event_stream +.Pp +Streams internal events from a running node. Output is jq-compatible. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics consume_event_stream -n rabbit@hostname --duration 20 --pattern "queue_.*" +.\" ------------------------------------ +.It Cm discover_peers +.Pp +Runs a peer discovery on the target node and prints the discovered nodes, if any. +.Pp +See +.Lk https://www.rabbitmq.com/cluster-formation.html "RabbitMQ Cluster Formation guide" +to learn more. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics discover_peers --timeout 60 +.\" ------------------------------------ +.It Cm environment +See +.Cm environment +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm erlang_cookie_hash +.Pp +Outputs a hashed value of the shared secret used by the target node +to authenticate CLI tools and peers. The value can be compared with the hash +found in error messages of CLI tools. +.Pp +See +.Lk https://www.rabbitmq.com/clustering.html#erlang-cookie "RabbitMQ Clustering guide" +to learn more. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics erlang_cookie_hash -q +.\" ------------------------------------ +.It Cm erlang_version +.Pp +Reports target node's Erlang/OTP version. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics erlang_version -q +.\" ------------------------------------ +.It Cm is_booting +.Pp +Reports if RabbitMQ application is currently booting (not booted/running or stopped) on +the target node. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics is_booting +.\" ------------------------------------ +.It Cm is_running +.Pp +Reports if RabbitMQ application is fully booted and running (that is, not stopped) on +the target node. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics is_running +.\" ------------------------------------ +.It Cm list_bindings Oo Fl p Ar vhost Oc Op Ar bindinginfoitem ... +See +.Cm list_bindings +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.ll.It Cm list_channels Op Ar channelinfoitem ... +See +.Cm list_channels +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_ciphers +See +.Cm list_ciphers +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_connections Op Ar connectioninfoitem ... +See +.Cm list_connections +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_consumers Op Fl p Ar vhost +See +.Cm list_consumers +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_exchanges Oo Fl p Ar vhost Oc Op Ar exchangeinfoitem ... +See +.Cm list_exchanges +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_hashes +See +.Cm list_hashes +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_queues Oo Fl p Ar vhost Oc Oo Fl -offline | Fl -online | Fl -local Oc Op Ar queueinfoitem ... +See +.Cm list_queues +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_unresponsive_queues Oc Oo Fl -local Oc Oo Fl -queue_timeout Ar milliseconds Oc Oo Ar column ... Oc Op Fl -no-table-headers +See +.Cm list_unresponsive_queues +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm listeners +.Pp +Lists listeners (bound sockets) on this node. Use this to inspect +what protocols and ports the node is listening on for client, CLI tool +and peer connections. +.Pp +See +.Lk https://www.rabbitmq.com/networking.html "RabbitMQ Networking guide" +to learn more. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics listeners +.\" ------------------------------------ +.It Cm log_tail Oc Oo Fl -number Ar number | Fl N Ar number Oc Op Fl -timeout Ar milliseconds +.Pp +Prints the last N lines of the log on the node +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics log_tail -number 100 +.\" ------------------------------------ +.It Cm log_tail_stream Oc Oo Fl -duration Ar seconds | Fl d Ar seconds Oc Op Fl -timeout Ar milliseconds +.Pp +Streams logs from a running node for a period of time +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics log_tail_stream --duration 60 +.\" ------------------------------------ +.It Cm maybe_stuck +.Pp +Periodically samples stack traces of all Erlang processes +("lightweight threads") on the node. Reports the processes for which +stack trace samples are identical. +.Pp +Identical samples may indicate that the process is not making any progress +but is not necessarily an indication of a problem. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics maybe_stuck -q .\" ------------------------------------ .It Cm memory_breakdown Op Fl -unit Ar memory_unit .Pp @@ -166,34 +516,26 @@ Example: .sp .Dl rabbitmq-diagnostics memory_breakdown --unit gigabytes .\" ------------------------------------ -.It Cm server_version +.It Cm observer Op Fl -interval Ar seconds .Pp -Reports target node's version. +Starts a CLI observer interface on the target node .Pp Example: .Sp -.Dl rabbitmq-diagnostics server_version -q +.Dl rabbitmq-diagnostics observer --interval 10 .\" ------------------------------------ -.It Cm erlang_version +.It Cm ping .Pp -Reports target node's Erlang/OTP version. -.Pp -Example: -.Sp -.Dl rabbitmq-diagnostics erlang_version -q +Most basic health check. Succeeds if target node (runtime) is running +and +.Nm +can authenticate with it successfully. .\" ------------------------------------ -.It Cm maybe_stuck -.Pp -Periodically samples stack traces of all Erlang processes -("lightweight threads") on the node. Reports the processes for which -stack trace samples are identical. -.Pp -Identical samples may indicate that the process is not making any progress -but is not necessarily an indication of a problem. -.Pp -Example: -.Sp -.Dl rabbitmq-diagnostics maybe_stuck -q +.It Cm report +See +.Cm report +in +.Xr rabbitmqctl 8 .\" ------------------------------------ .It Cm runtime_thread_stats Op Fl -sample-interval Ar interval .Pp @@ -208,6 +550,27 @@ Example: .Sp .Dl rabbitmq-diagnostics runtime_thread_stats --sample-interval 15 .\" ------------------------------------ +.It Cm schema_info Oc Oo Fl -no_table_headers Oc Oo Ar column ... Oc Op Fl -timeout Ar milliseconds +.Pp +See +.Cm schema_info +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm server_version +.Pp +Reports target node's version. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics server_version -q +.\" ------------------------------------ +.It Cm status +See +.Cm status +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ .It Cm tls_versions .Pp Lists all TLS versions supported by the runtime on the target node. @@ -221,243 +584,10 @@ to learn more. Example: .Sp .Dl rabbitmq-diagnostics tls_versions -q -.\" ------------------------------------ -.It Cm erlang_cookie_hash -.Pp -Outputs a hashed value of the shared secret used by the target node -to authenticate CLI tools and peers. The value can be compared with the hash -found in error messages of CLI tools. -.Pp -See -.Lk https://www.rabbitmq.com/clustering.html#erlang-cookie "RabbitMQ Clustering guide" -to learn more. -.Pp -Example: -.Sp -.Dl rabbitmq-diagnostics erlang_cookie_hash -q -.\" ------------------------------------ -.It Cm discover_peers -.Pp -Runs a peer discovery on the target node and prints the discovered nodes, if any. -.Pp -See -.Lk https://www.rabbitmq.com/cluster-formation.html "RabbitMQ Cluster Formation guide" -to learn more. -.Pp -Example: -.Sp -.Dl rabbitmq-diagnostics discover_peers --timeout 60 -.\" ------------------------------------ -.It Cm list_channels Op Ar channelinfoitem ... -See -.Cm list_channels -in -.Xr rabbitmqctl 8 -.\" ------------------------------------ -.It Cm list_queues Oo Fl p Ar vhost Oc Oo Fl -offline | Fl -online | Fl -local Oc Op Ar queueinfoitem ... -See -.Cm list_queues -in -.Xr rabbitmqctl 8 -.\" ------------------------------------ -.It Cm list_exchanges Oo Fl p Ar vhost Oc Op Ar exchangeinfoitem ... -See -.Cm list_exchanges -in -.Xr rabbitmqctl 8 -.\" ------------------------------------ -.It Cm list_bindings Oo Fl p Ar vhost Oc Op Ar bindinginfoitem ... -See -.Cm list_bindings -in -.Xr rabbitmqctl 8 -.\" ------------------------------------ -.It Cm list_connections Op Ar connectioninfoitem ... -See -.Cm list_connections -in -.Xr rabbitmqctl 8 -.\" ------------------------------------ -.It Cm list_channels Op Ar channelinfoitem ... -See -.Cm list_channels -in -.Xr rabbitmqctl 8 -.\" ------------------------------------ -.It Cm list_consumers Op Fl p Ar vhost -See -.Cm list_consumers -in -.Xr rabbitmqctl 8 -.\" ------------------------------------ -.It Cm alarms -.Pp -Lists resource alarms, if any, in the cluster. -.Pp -See -.Lk https://www.rabbitmq.com/alarms.html "RabbitMQ Resource Alarms guide" -to learn more. -.Pp -Example: -.Sp -.Dl rabbitmq-diagnostics alarms -.\" ------------------------------------ -.It Cm listeners -.Pp -Lists listeners (bound sockets) on this node. Use this to inspect -what protocols and ports the node is listening on for client, CLI tool -and peer connections. -.Pp -See -.Lk https://www.rabbitmq.com/networking.html "RabbitMQ Networking guide" -to learn more. -.Pp -Example: -.Sp -.Dl rabbitmq-diagnostics listeners -.\" ------------------------------------ -.It Cm is_running -.Pp -Reports if RabbitMQ application is fully booted and running (that is, not stopped) on -the target node. -.Pp -Example: -.Sp -.Dl rabbitmq-diagnostics is_running -.\" ------------------------------------ -.It Cm is_booting -.Pp -Reports if RabbitMQ application is currently booting (not booted/running or stopped) on -the target node. -.Pp -Example: -.Sp -.Dl rabbitmq-diagnostics is_booting -.\" ------------------------------------ - -check_port_connectivity [-t ] -.\" ------------------------------------ -.It Cm check_running -.Pp -Health check that fails (returns with a non-zero code) if the RabbitMQ -application is not running on the target node. -.Pp -If -.Cm rabbitmqctl(8) -was used to stop the application, this check will fail. -.Pp -Example: -.Sp -.Dl rabbitmq-diagnostics check_running -.\" ------------------------------------ -.It Cm check_local_alarms -.Pp -Health check that fails (returns with a non-zero code) if there are alarms -in effect on the target node. -.Pp -See -.Lk https://www.rabbitmq.com/alarms.html "RabbitMQ Resource Alarms guide" -to learn more. -.Pp -Example: -.Sp -.Dl rabbitmq-diagnostics check_local_alarms -.\" ------------------------------------ -.It Cm check_alarms -.Pp -Health check that fails (returns with a non-zero code) if there are alarms -in effect on any of the cluster nodes. -.Pp -See -.Lk https://www.rabbitmq.com/alarms.html "RabbitMQ Resource Alarms guide" -to learn more. -.Pp -Example: -.Sp -.Dl rabbitmq-diagnostics check_alarms -.\" ------------------------------------ -.It Cm check_port_connectivity -.Pp -Health check that fails (returns with a non-zero code) if any listener ports -on the target node cannot accept a new TCP connection opened by -.Nm. -The check only validates if a new TCP connection is accepted. It does not -perform messaging protocol handshake or authenticate. -.Pp -See -.Lk https://www.rabbitmq.com/networking.html "RabbitMQ Networking guide" -to learn more. -.Pp -Example: -.Sp -.Dl rabbitmq-diagnostics check_port_connectivity -.\" ------------------------------------ -.It Cm check_protocol_listener -.Pp -Health check that fails (returns with a non-zero code) if the target node -does not have a listener for the specified protocol. -.Pp -See -.Lk https://www.rabbitmq.com/networking.html "RabbitMQ Networking guide" -to learn more. -.Pp -Example: -.Sp -.Dl rabbitmq-diagnostics check_protocol_listener mqtt -.\" ------------------------------------ -.It Cm check_port_listener -.Pp -Health check that fails (returns with a non-zero code) if the target node -is not listening on the specified port (there is no listener that -uses that port). -.Pp -See -.Lk https://www.rabbitmq.com/networking.html "RabbitMQ Networking guide" -to learn more. -.Pp -Example: -.Sp -.Dl rabbitmq-diagnostics check_port_listener 5672 -.\" ------------------------------------ -.It Cm consume_event_stream -.Pp -Streams internal events from a running node. Output is jq-compatible. -.Pp -Example: -.Sp -.Dl rabbitmq-diagnostics consume_event_stream -n rabbit@hostname --duration 20 --pattern "queue_.*" -.\" ------------------------------------ -.It Cm command_line_arguments -.Pp -Displays target node's command-line arguments and flags as reported by the runtime. -.Pp -Example: -.Sp -.Dl rabbitmq-diagnostics command_line_arguments -n rabbit@hostname -.\" ------------------------------------ -.It Cm status -See -.Cm status -in -.Xr rabbitmqctl 8 -.\" ------------------------------------ -.It Cm cluster_status -See -.Cm cluster_status -in -.Xr rabbitmqctl 8 -.\" ------------------------------------ -.It Cm environment -See -.Cm environment -in -.Xr rabbitmqctl 8 -.\" ------------------------------------ -.It Cm report -See -.Cm report -in -.Xr rabbitmqctl 8 +.El +.El +.Ss Parameters +.Bl -tag -width Ds .\" ------------------------------------ .It Cm list_global_parameters See @@ -465,21 +595,19 @@ See in .Xr rabbitmqctl 8 .\" ------------------------------------ -.It Cm list_operator_policies Op Fl p Ar vhost -See -.Cm list_operator_policies -in -.Xr rabbitmqctl 8 -.\" ------------------------------------ .It Cm list_parameters Op Fl p Ar vhost See .Cm list_parameters in .Xr rabbitmqctl 8 -.\" ------------------------------------------------------------------ -.It Cm list_permissions Op Fl p Ar vhost +.El +.El +.Ss Policies +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm list_operator_policies Op Fl p Ar vhost See -.Cm list_permissions +.Cm list_operator_policies in .Xr rabbitmqctl 8 .\" ------------------------------------ @@ -489,45 +617,49 @@ See in .Xr rabbitmqctl 8 .\" ------------------------------------ -.It Cm list_topic_permissions Op Fl p Ar vhost -See -.Cm list_topic_permissions -in -.Xr rabbitmqctl 8 +.El +.El +.Ss Virtual hosts +.Bl -tag -width Ds .\" ------------------------------------ -.It Cm list_user_permissions Ar username -See -.Cm list_user_permissions -in -.Xr rabbitmqctl 8 -.\" ------------------------------------ -.It Cm list_user_topic_permissions Ar username -See -.Cm list_user_topic_permissions -in -.Xr rabbitmqctl 8 -.\" ------------------------------------ -.It Cm list_users -See -.Cm list_users -in -.Xr rabbitmqctl 8 -.\" ------------------------------------ -.It Cm list_vhosts Op Ar vhostinfoitem ... -See -.Cm list_vhosts -in -.Xr rabbitmqctl 8 -.\" ------------------------------------ -.It Cm node_health_check -Performs several health checks of the target node. +.It Cm list_vhost_limits Oc Oo Fl -vhost Ar vhost Oc Oo Fl -global Oc Op Fl -no-table-headers .Pp -Verifies the rabbit application is running and alarms are not set, -then checks that every queue and channel on the node can emit basic stats. +See +.Cm list_vhost_limits +in +.Xr rabbitmqctl 8 +.El +.El +.Ss Node configuration +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm log_location Oc Oo Fl -all | Fl a Oc Op Fl -timeout Ar milliseconds +.Pp +Shows log file location(s) on target node .Pp Example: .Sp -.Dl rabbitmq-diagnostics node_health_check -n rabbit@hostname +.Dl rabbitmq-diagnostics log_location -a +.El +.El +.Ss Feature flags +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm list_feature_flags Oc Oo Ar column ... Oc Op Fl -timeout Ar milliseconds +See +.Cm list_feature_flags +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.El +.El +.Ss Queues +.Bl -tag -width Ds +.It Cm quorum_status Ar queue Oc Op Fl -vhost Ar vhost +See +.Cm quorum_status +in +.Xr rabbitmqctl 8 .\" ------------------------------------------------------------------ .Sh SEE ALSO .\" ------------------------------------------------------------------ diff --git a/docs/rabbitmqctl.8 b/docs/rabbitmqctl.8 index 53337d82e9..2e4563b1e3 100644 --- a/docs/rabbitmqctl.8 +++ b/docs/rabbitmqctl.8 @@ -115,54 +115,20 @@ Prints usage for all available commands. List command usages only, without parameter explanation. .It Ar command_name Prints usage for the specified command. +.\" ------------------------------------ +.It Cm version +Displays CLI tools version .El .El -.Ss Application Management +.Ss Nodes .Bl -tag -width Ds .\" ------------------------------------ -.It Cm force_reset -Forcefully returns a RabbitMQ node to its virgin state. +.It Cm await_startup +Waits for the RabbitMQ application to start on the target node .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: +For example, to wait for the RabbitMQ application to start: .sp -.Dl rabbitmqctl force_reset -.\" ------------------------------------ -.It Cm hipe_compile Ar directory -Performs HiPE-compilation and caches resulting -.Pa .beam Ns -files in the given directory. -.Pp -Parent directories are created if necessary. -Any existing -.Pa .beam -files from the directory are automatically deleted prior to compilation. -.Pp -To use this precompiled files, you should set -.Ev RABBITMQ_SERVER_CODE_PATH -environment variable to directory specified in -.Cm hipe_compile -invocation. -.Pp -For example, to HiPE-compile modules and store them to -.Pa /tmp/rabbit-hipe/ebin -directory: -.sp -.Dl rabbitmqctl hipe_compile /tmp/rabbit-hipe/ebin +.Dl rabbitmqctl await_startup .\" ------------------------------------ .It Cm reset Returns a RabbitMQ node to its virgin state. @@ -297,11 +263,139 @@ For example, this command will return when the RabbitMQ node has started up: .sp .Dl rabbitmqctl wait /var/run/rabbitmq/pid -.\" ------------------------------------ .El -.Ss Cluster Management +.El +.Ss Cluster management .Bl -tag -width Ds .\" ------------------------------------ +.It Cm await_online_nodes +Waits for 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 +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 +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 +.El +.El +.Ss Application Management +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm force_boot +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 were mastered 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 +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 clusternode Op Fl -ram .Bl -tag -width Ds .It Ar clusternode @@ -357,71 +451,6 @@ is part of, as a ram node: .sp .Dl rabbitmqctl join_cluster hare@elena --ram .\" ------------------------------------ -.It Cm cluster_status -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 change_cluster_node_type Ar type -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 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 rename_cluster_node Ar oldnode1 Ar newnode1 Op Ar oldnode2 Ar newnode2 ... Supports renaming of cluster nodes in the local database. .Pp @@ -529,35 +558,10 @@ is not in the cluster anymore. The following command will solve this situation: .sp .Dl update_cluster_nodes -n Va A Va C -.\" ------------------------------------ -.It Cm force_boot -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 were mastered 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 +.El +.El +.Ss Replication +.Bl -tag -width Ds .\" ------------------------------------ .It Cm sync_queue Oo Fl p Ar vhost Oc Ar queue .Bl -tag -width Ds @@ -584,27 +588,6 @@ The name of the queue to cancel synchronisation for. .El .Pp Instructs a synchronising mirrored queue to stop synchronising itself. -.\" ------------------------------------ -.It Cm purge_queue Oo Fl p Ar vhost Oc Ar queue -.Bl -tag -width Ds -.It Ar queue -The name of the queue to purge. -.El -.Pp -Purges a queue (removes all messages in it). -.\" ------------------------------------ -.It Cm set_cluster_name Ar name -Sets the cluster name to -.Ar name . -The cluster name is announced to clients on connection, and used by the -federation and shovel plugins to record where a message has been. -The cluster name is by default derived from the hostname of the first -node in the cluster, but can be changed. -.Pp -For example, this sets the cluster name to -.Qq london : -.sp -.Dl rabbitmqctl set_cluster_name london .El .Ss User Management Note that all user management commands @@ -630,16 +613,20 @@ with (initial) password .sp .Dl rabbitmqctl add_user janeway changeit .\" ------------------------------------ -.It Cm delete_user Ar username +.It Cm authenticate_user Ar username Ar password .Bl -tag -width Ds .It Ar username -The name of the user to delete. +The name of the user. +.It Ar password +The password of the user. .El .Pp -For example, this command instructs the RabbitMQ broker to delete the user named -.Qq janeway : +For example, this command instructs the RabbitMQ broker to authenticate the user named +.Qq janeway +with password +.Qq verifyit : .sp -.Dl rabbitmqctl delete_user janeway +.Dl rabbitmqctl authenticate_user janeway verifyit .\" ------------------------------------ .It Cm change_password Ar username Ar newpassword .Bl -tag -width Ds @@ -672,20 +659,25 @@ password for the user named This user now cannot log in with a password (but may be able to through e.g. SASL EXTERNAL if configured). .\" ------------------------------------ -.It Cm authenticate_user Ar username Ar password +.It Cm delete_user Ar username .Bl -tag -width Ds .It Ar username -The name of the user. -.It Ar password -The password of the user. +The name of the user to delete. .El .Pp -For example, this command instructs the RabbitMQ broker to authenticate the user named -.Qq janeway -with password -.Qq verifyit : +For example, this command instructs the RabbitMQ broker to delete the user named +.Qq janeway : .sp -.Dl rabbitmqctl authenticate_user janeway verifyit +.Dl rabbitmqctl delete_user janeway +.\" ------------------------------------ +.It Cm list_users +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 @@ -711,55 +703,138 @@ This command instructs the RabbitMQ broker to remove any tags from the user name .Qq janeway : .sp .Dl rabbitmqctl set_user_tags janeway -.\" ------------------------------------ -.It Cm list_users -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 .El -.Ss Access Control -Note that -.Nm -manages the RabbitMQ internal user database. -Permissions for users from any alternative authorisation backend will -not be visible to -.Nm . +.El +.Ss Access control .Bl -tag -width Ds .\" ------------------------------------ -.It Cm add_vhost Ar vhost +.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 entry to create. +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 -Creates a virtual host. +Sets user permissions. .Pp -For example, this command instructs the RabbitMQ broker to create a new -virtual host called -.Qq test : -.Pp -.Dl rabbitmqctl add_vhost test +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 delete_vhost Ar vhost +.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 entry to delete. +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 -Deletes a virtual host. +Clear user topic permissions. .Pp -Deleting a virtual host deletes all its exchanges, queues, bindings, -user permissions, parameters and policies. -.Pp -For example, this command instructs the RabbitMQ broker to delete the -virtual host called -.Qq test : +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 delete_vhost test +.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_topic_user_permissions janeway +.El +.Ss Parameter Management +Certain features of RabbitMQ (such as the Federation plugin) are +controlled by dynamic, cluster-wide +.Em parameters. +There are 2 kinds of parameters: parameters scoped to a virtual host and +global parameters. +Each vhost-scoped parameter consists of a component name, a name and a +value. +The component name and name are strings, and the value is a valid JSON document. +A global parameter consists of a name and value. +The name is a string and the value is an arbitrary Erlang data structure. +Parameters can be set, cleared and listed. +In general you should refer to the documentation for the feature in +question to see how to set parameters. +.Bl -tag -width Ds .\" ------------------------------------ .It Cm list_vhosts Op Ar vhostinfoitem ... Lists virtual hosts. @@ -819,62 +894,6 @@ 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 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 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_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 set_topic_permissions Oo Fl p Ar vhost Oc Ar user Ar exchange Ar write Ar read .Bl -tag -width Ds .It Ar vhost @@ -911,347 +930,325 @@ 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 -.\" ------------------------------------ -.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_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_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_topic_user_permissions janeway -.El -.Ss Parameter Management -Certain features of RabbitMQ (such as the Federation plugin) are -controlled by dynamic, cluster-wide -.Em parameters. -There are 2 kinds of parameters: parameters scoped to a virtual host and -global parameters. -Each vhost-scoped parameter consists of a component name, a name and a -value. -The component name and name are strings, and the value is a valid JSON document. -A global parameter consists of a name and value. -The name is a string and the value is an arbitrary Erlang data structure. -Parameters can be set, cleared and listed. -In general you should refer to the documentation for the feature in -question to see how to set parameters. +.Ss Monitoring, observability and health checks .Bl -tag -width Ds .\" ------------------------------------ -.It Cm set_parameter Oo Fl p Ar vhost Oc Ar component_name Ar name Ar value -Sets a parameter. -.Bl -tag -width Ds -.It Ar component_name -The name of the component for which the parameter is being set. -.It Ar name -The name of the parameter being set. -.It Ar value -The value for the parameter, as a JSON term. -In most shells you are very likely to need to quote this. -.El -.Pp -For example, this command sets the parameter -.Qq node01 -for the -.Qq federation-upstream -component in the default virtual host to the following JSON -.Qq guest : -.sp -.Dl rabbitmqctl set_parameter federation-upstream node01 '{"uri":"amqp://user:password@server/%2F","ack-mode":"on-publish"}' +.It Cm environment +Displays the name and value of each variable in the application +environment for each running application. .\" ------------------------------------ -.It Cm clear_parameter Oo Fl p Ar vhost Oc Ar component_name Ar key -Clears a parameter. -.Bl -tag -width Ds -.It Ar component_name -The name of the component for which the parameter is being cleared. -.It Ar name -The name of the parameter being cleared. -.El -.Pp -For example, this command clears the parameter -.Qq node01 -for the -.Qq federation-upstream -component in the default virtual host: -.sp -.Dl rabbitmqctl clear_parameter federation-upstream node01 -.\" ------------------------------------ -.It Cm list_parameters Op Fl p Ar vhost -Lists all parameters for a virtual host. -.Pp -For example, this command lists all parameters in the default virtual -host: -.sp -.Dl rabbitmqctl list_parameters -.\" ------------------------------------ -.It Cm set_global_parameter Ar name Ar value -Sets a global runtime parameter. -This is similar to -.Cm set_parameter -but the key-value pair isn't tied to a virtual host. -.Bl -tag -width Ds -.It Ar name -The name of the global runtime parameter being set. -.It Ar value -The value for the global runtime parameter, as a JSON term. -In most shells you are very likely to need to quote this. -.El -.Pp -For example, this command sets the global runtime parameter -.Qq mqtt_default_vhosts -to the JSON term {"O=client,CN=guest":"/"}: -.sp -.Dl rabbitmqctl set_global_parameter mqtt_default_vhosts '{"O=client,CN=guest":"/"}' -.\" ------------------------------------ -.It Cm clear_global_parameter Ar name -Clears a global runtime parameter. -This is similar to -.Cm clear_parameter -but the key-value pair isn't tied to a virtual host. -.Bl -tag -width Ds -.It Ar name -The name of the global runtime parameter being cleared. -.El -.Pp -For example, this command clears the global runtime parameter -.Qq mqtt_default_vhosts : -.sp -.Dl rabbitmqctl clear_global_parameter mqtt_default_vhosts -.\" ------------------------------------ -.It Cm list_global_parameters -Lists all global runtime parameters. -This is similar to -.Cm list_parameters -but the global runtime parameters are not tied to any virtual host. -.Pp -For example, this command lists all global parameters: -.sp -.Dl rabbitmqctl list_global_parameters -.El -.Ss Policy Management -Policies are used to control and modify the behaviour of queues and -exchanges on a cluster-wide basis. -Policies apply within a given vhost, and consist of a name, pattern, -definition and an optional priority. -Policies can be set, cleared and listed. -.Bl -tag -width Ds -.\" ------------------------------------ -.It Cm set_policy Oo Fl p Ar vhost Oc Oo Fl -priority Ar priority Oc Oo Fl -apply-to Ar apply-to Oc Ar name Ar pattern Ar definition -Sets a policy. -.Bl -tag -width Ds -.It Ar name -The name of the policy. -.It Ar pattern -The regular expression, which when matches on a given resources causes -the policy to apply. -.It Ar definition -The definition of the policy, as a JSON term. -In most shells you are very likely to need to quote this. -.It Ar priority -The priority of the policy as an integer. -Higher numbers indicate greater precedence. -The default is 0. -.It Ar apply-to -Which types of object this policy should apply to. -Possible values are: -.Bl -bullet -compact -.It -.Cm queues -.It -.Cm exchanges -.It -.Cm all -.El -The default is -.Cm all .. -.El -.Pp -For example, this command sets the policy -.Qq federate-me -in the default virtual host so that built-in exchanges are federated: -.sp -.Dl rabbitmqctl set_policy federate-me "^amq." '{"federation-upstream-set":"all"}' -.\" ------------------------------------ -.It Cm clear_policy Oo Fl p Ar vhost Oc Ar name -Clears a policy. -.Bl -tag -width Ds -.It Ar name -The name of the policy being cleared. -.El -.Pp -For example, this command clears the -.Qq federate-me -policy in the default virtual host: -.sp -.Dl rabbitmqctl clear_policy federate-me -.\" ------------------------------------ -.It Cm list_policies Op Fl p Ar vhost -Lists all policies for a virtual host. -.Pp -For example, this command lists all policies in the default virtual -host: -.sp -.Dl rabbitmqctl list_policies -.\" ------------------------------------ -.It Cm set_operator_policy Oo Fl p Ar vhost Oc Oo Fl -priority Ar priority Oc Oo Fl -apply-to Ar apply-to Oc Ar name Ar pattern Ar definition -Sets an operator policy that overrides a subset of arguments in user -policies. -Arguments are identical to those of -.Cm set_policy . -.Pp -Supported arguments are: -.Bl -bullet -compact -.It -expires -.It -message-ttl -.It -max-length -.It -max-length-bytes -.El -.\" ------------------------------------ -.It Cm clear_operator_policy Oo Fl p Ar vhost Oc Ar name -Clears an operator policy. -Arguments are identical to those of -.Cm clear_policy . -.\" ------------------------------------ -.It Cm list_operator_policies Op Fl p Ar vhost -Lists operator policy overrides for a virtual host. -Arguments are identical to those of -.Cm list_policies . -.El -.Ss Virtual Host Limits -It is possible to enforce certain limits on virtual hosts. -.Bl -tag -width Ds -.\" ------------------------------------ -.It Cm set_vhost_limits Oo Fl p Ar vhost Oc Ar definition -Sets virtual host limits. -.Bl -tag -width Ds -.It Ar definition -The definition of the limits, as a JSON term. -In most shells you are very likely to need to quote this. -.Pp -Recognised limits are: -.Bl -bullet -compact -.It -max-connections -.It -max-queues -.El -.Pp -Use a negative value to specify "no limit". -.El -.Pp -For example, this command limits the max number of concurrent -connections in vhost -.Qq qa_env -to 64: -.sp -.Dl rabbitmqctl set_vhost_limits -p qa_env '{"max-connections": 64}' -.Pp -This command limits the max number of queues in vhost -.Qq qa_env -to 256: -.sp -.Dl rabbitmqctl set_vhost_limits -p qa_env '{"max-queues": 256}' -.Pp -This command clears the max number of connections limit in vhost -.Qq qa_env : -.sp -.Dl rabbitmqctl set_vhost_limits -p qa_env '{"max\-connections": \-1}' -.Pp -This command disables client connections in vhost -.Qq qa_env : -.sp -.Dl rabbitmqctl set_vhost_limits -p qa_env '{"max-connections": 0}' -.\" ------------------------------------ -.It Cm clear_vhost_limits Op Fl p Ar vhost -Clears virtual host limits. -.Pp -For example, this command clears vhost limits in vhost -.Qq qa_env : -.sp -.Dl rabbitmqctl clear_vhost_limits -p qa_env -.\" ------------------------------------ -.It Cm list_vhost_limits Oo Fl p Ar vhost Oc Op Fl -global -Displays configured virtual host limits. -.Bl -tag -width Ds -.It Fl -global -Show limits for all vhosts. -Suppresses the +.It Cm list_bindings Oo Fl p Ar vhost Oc Op Ar bindinginfoitem ... +Returns binding details. +By default the bindings for the +.Qq / +virtual host are returned. +The .Fl p -parameter. -.El -.El -.Ss Topology Introspection -The topology introspection commands list topology entities (e.g. queues) with tab-delimited columns. -Some commands ( -.Cm list_queues , -.Cm list_exchanges , -.Cm list_bindings -and -.Cm list_consumers ) -accept an optional -.Ar vhost -parameter. +flag can be used to override this default. .Pp The -.Cm list_queues , -.Cm list_exchanges -and -.Cm list_bindings -commands accept an optional virtual host parameter for which to display -results. -The default value is -.Qq / . +.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 +The binding's arguments. +.El +.Pp +If no +.Ar bindinginfoitem +are specified then all above items are displayed. +.Pp +For example, this command displays the exchange name and queue name of +the bindings in the virtual host named +.Qq my-vhost +.sp +.Dl rabbitmqctl list_bindings -p my-vhost exchange_name queue_name +.\" ------------------------------------ +.It Cm list_channels Op Ar channelinfoitem ... +Returns information on all current channels, the logical containers +executing most AMQP commands. +This includes channels that are part of ordinary AMQP connections, and +channels created by various plug-ins and other extensions. +.Pp +The +.Ar channelinfoitem +parameter is used to indicate which channel information items to include +in the results. +The column order in the results will match the order of the parameters. +.Ar channelinfoitem +can take any value from the list that follows: +.Bl -tag -width Ds +.It Cm pid +Id of the Erlang process associated with the connection. +.It Cm connection +Id of the Erlang process associated with the connection to which the +channel belongs. +.It Cm name +Readable name for the channel. +.It Cm number +The number of the channel, which uniquely identifies it within a +connection. +.It Cm user +Username associated with the channel. +.It Cm vhost +Virtual host in which the channel operates. +.It Cm transactional +True if the channel is in transactional mode, false otherwise. +.It Cm confirm +True if the channel is in confirm mode, false otherwise. +.It Cm consumer_count +Number of logical AMQP consumers retrieving messages via the channel. +.It Cm messages_unacknowledged +Number of messages delivered via this channel but not yet acknowledged. +.It Cm messages_uncommitted +Number of messages received in an as yet uncommitted transaction. +.It Cm acks_uncommitted +Number of acknowledgements received in an as yet uncommitted transaction. +.It Cm messages_unconfirmed +Number of published messages not yet confirmed. +On channels not in confirm mode, this remains 0. +.It Cm prefetch_count +QoS prefetch limit for new consumers, 0 if unlimited. +.It Cm global_prefetch_count +QoS prefetch limit for the entire channel, 0 if unlimited. +.El +.Pp +If no +.Ar channelinfoitem +are specified then pid, user, consumer_count, and +messages_unacknowledged are assumed. +.Pp +For example, this command displays the connection process and count of +unacknowledged messages for each channel: +.sp +.Dl rabbitmqctl list_channels connection messages_unacknowledged +.\" ------------------------------------ +.It Cm list_ciphers +Lists cipher suites supported by encoding commands. +.Pp +For example, this command instructs the RabbitMQ broker to list all +cipher suites supported by encoding commands: +.sp +.Dl rabbitmqctl list_ciphers +.El +.\" ------------------------------------ +.It Cm list_connections Op Ar connectioninfoitem ... +Returns TCP/IP connection statistics. +.Pp +The +.Ar connectioninfoitem +parameter is used to indicate which connection information items to +include in the results. +The column order in the results will match the order of the parameters. +.Ar connectioninfoitem +can take any value from the list that follows: +.Bl -tag -width Ds +.It Cm pid +Id of the Erlang process associated with the connection. +.It Cm name +Readable name for the connection. +.It Cm port +Server port. +.It Cm host +Server hostname obtained via reverse DNS, or its IP address if reverse +DNS failed or was disabled. +.It Cm peer_port +Peer port. +.It Cm peer_host +Peer hostname obtained via reverse DNS, or its IP address if reverse DNS +failed or was not enabled. +.It Cm ssl +Boolean indicating whether the connection is secured with SSL. +.It Cm ssl_protocol +SSL protocol (e.g.\& +.Qq tlsv1 ) . +.It Cm ssl_key_exchange +SSL key exchange algorithm (e.g.\& +.Qq rsa ) . +.It Cm ssl_cipher +SSL cipher algorithm (e.g.\& +.Qq aes_256_cbc ) . +.It Cm ssl_hash +SSL hash function (e.g.\& +.Qq sha ) . +.It Cm peer_cert_subject +The subject of the peer's SSL certificate, in RFC4514 form. +.It Cm peer_cert_issuer +The issuer of the peer's SSL certificate, in RFC4514 form. +.It Cm peer_cert_validity +The period for which the peer's SSL certificate is valid. +.It Cm state +Connection state; one of: +.Bl -bullet -compact +.It +starting +.It +tuning +.It +opening +.It +running +.It +flow +.It +blocking +.It +blocked +.It +closing +.It +closed +.El +.It Cm channels +Number of channels using the connection. +.It Cm protocol +Version of the AMQP protocol in use; currently one of: +.Bl -bullet -compact +.It +{0,9,1} +.It +{0,8,0} +.El +.Pp +Note that if a client requests an AMQP 0-9 connection, we treat it as +AMQP 0-9-1. +.It Cm auth_mechanism +SASL authentication mechanism used, such as +.Qq PLAIN . +.It Cm user +Username associated with the connection. +.It Cm vhost +Virtual host name with non-ASCII characters escaped as in C. +.It Cm timeout +Connection timeout / negotiated heartbeat interval, in seconds. +.It Cm frame_max +Maximum frame size (bytes). +.It Cm channel_max +Maximum number of channels on this connection. +.It Cm client_properties +Informational properties transmitted by the client during connection +establishment. +.It Cm recv_oct +Octets received. +.It Cm recv_cnt +Packets received. +.It Cm send_oct +Octets send. +.It Cm send_cnt +Packets sent. +.It Cm send_pend +Send queue size. +.It Cm connected_at +Date and time this connection was established, as timestamp. +.El +.Pp +If no +.Ar connectioninfoitem +are specified then user, peer host, peer port, time since flow control +and memory block state are displayed. +.Pp +For example, this command displays the send queue size and server port +for each connection: +.sp +.Dl rabbitmqctl list_connections send_pend port +.\" ------------------------------------ +.It Cm list_consumers Op Fl p Ar vhost +Lists consumers, i.e. subscriptions to a queue\'s message stream. +Each line printed shows, separated by tab characters, the name of +the queue subscribed to, the id of the channel process via which the +subscription was created and is managed, the consumer tag which uniquely +identifies the subscription within a channel, a boolean indicating +whether acknowledgements are expected for messages delivered to this +consumer, an integer indicating the prefetch limit (with 0 meaning +.Qq none ) , +and any arguments for this consumer. +.\" ------------------------------------ +.It Cm list_exchanges Oo Fl p Ar vhost Oc Op Ar exchangeinfoitem ... +Returns exchange details. +Exchange details of the +.Qq / +virtual host are returned if the +.Fl p +flag is absent. +The +.Fl p +flag can be used to override this default. +.Pp +The +.Ar exchangeinfoitem +parameter is used to indicate which exchange information items to +include in the results. +The column order in the results will match the order of the parameters. +.Ar exchangeinfoitem +can take any value from the list that follows: +.Bl -tag -width Ds +.It Cm name +The name of the exchange with non-ASCII characters escaped as in C. +.It Cm type +The exchange type, such as: +.Bl -bullet -compact +.It +direct +.It +topic +.It +headers +.It +fanout +.El +.It Cm durable +Whether or not the exchange survives server restarts. +.It Cm auto_delete +Whether the exchange will be deleted automatically when no longer used. +.It Cm internal +Whether the exchange is internal, i.e. cannot be directly published to +by a client. +.It Cm arguments +Exchange arguments. +.It Cm policy +Policy name for applying to the exchange. +.El +.Pp +If no +.Ar exchangeinfoitem +are specified then exchange name and type are displayed. +.Pp +For example, this command displays the name and type for each exchange +of the virtual host named +.Qq my-vhost : +.sp +.Dl rabbitmqctl list_exchanges -p my-vhost name type +.\" ------------------------------------ +.It Cm list_hashes +Lists hash functions supported by encoding commands. +.Pp +For example, this command instructs the RabbitMQ broker to list all hash +functions supported by encoding commands: +.sp +.Dl rabbitmqctl list_hashes .\" ------------------------------------ .It Cm list_queues Oo Fl p Ar vhost Oc Oo Fl -offline | Fl -online | Fl -local Oc Op Ar queueinfoitem ... Returns queue details. @@ -1400,299 +1397,47 @@ each queue of the virtual host named .sp .Dl rabbitmqctl list_queues -p my-vhost messages consumers .\" ------------------------------------ -.It Cm list_exchanges Oo Fl p Ar vhost Oc Op Ar exchangeinfoitem ... -Returns exchange details. -Exchange details of the -.Qq / -virtual host are returned if the -.Fl p -flag is absent. -The -.Fl p -flag can be used to override this default. +.It Cm list_unresponsive_queues Oc Oo Fl -local Oc Oo Fl -queue_timeout Ar milliseconds Oc Oo Ar column ... Oc Op Fl -no-table-headers .Pp -The -.Ar exchangeinfoitem -parameter is used to indicate which exchange information items to -include in the results. -The column order in the results will match the order of the parameters. -.Ar exchangeinfoitem -can take any value from the list that follows: -.Bl -tag -width Ds -.It Cm name -The name of the exchange with non-ASCII characters escaped as in C. -.It Cm type -The exchange type, such as: -.Bl -bullet -compact -.It -direct -.It -topic -.It -headers -.It -fanout -.El -.It Cm durable -Whether or not the exchange survives server restarts. -.It Cm auto_delete -Whether the exchange will be deleted automatically when no longer used. -.It Cm internal -Whether the exchange is internal, i.e. cannot be directly published to -by a client. -.It Cm arguments -Exchange arguments. -.It Cm policy -Policy name for applying to the exchange. -.El +Tests queues to respond within timeout. Lists those which did not respond .Pp -If no -.Ar exchangeinfoitem -are specified then exchange name and type are displayed. -.Pp -For example, this command displays the name and type for each exchange -of the virtual host named -.Qq my-vhost : -.sp -.Dl rabbitmqctl list_exchanges -p my-vhost name type +For example, this command lists only those unresponsive queues whose master process +is located on the current node. +.Sp +.Dl rabbitmqctl list_unresponsive_queues --local name .\" ------------------------------------ -.It Cm list_bindings Oo Fl p Ar vhost Oc Op Ar bindinginfoitem ... -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. +.It Cm node_health_check +Performs several health checks of the target node. .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 -The binding's arguments. -.El -.Pp -If no -.Ar bindinginfoitem -are specified then all above items are displayed. -.Pp -For example, this command displays the exchange name and queue name of -the bindings in the virtual host named -.Qq my-vhost +Verifies the rabbit application is running and alarms are not set, +then checks that every queue and channel on the node can emit basic stats. .sp -.Dl rabbitmqctl list_bindings -p my-vhost exchange_name queue_name +Example: +.Dl rabbitmqctl node_health_check -n rabbit@hostname .\" ------------------------------------ -.It Cm list_connections Op Ar connectioninfoitem ... -Returns TCP/IP connection statistics. +.It Cm ping +Checks that the node OS process is up, registered with EPMD and CLI tools can authenticate with it .Pp -The -.Ar connectioninfoitem -parameter is used to indicate which connection information items to -include in the results. -The column order in the results will match the order of the parameters. -.Ar connectioninfoitem -can take any value from the list that follows: -.Bl -tag -width Ds -.It Cm pid -Id of the Erlang process associated with the connection. -.It Cm name -Readable name for the connection. -.It Cm port -Server port. -.It Cm host -Server hostname obtained via reverse DNS, or its IP address if reverse -DNS failed or was disabled. -.It Cm peer_port -Peer port. -.It Cm peer_host -Peer hostname obtained via reverse DNS, or its IP address if reverse DNS -failed or was not enabled. -.It Cm ssl -Boolean indicating whether the connection is secured with SSL. -.It Cm ssl_protocol -SSL protocol (e.g.\& -.Qq tlsv1 ) . -.It Cm ssl_key_exchange -SSL key exchange algorithm (e.g.\& -.Qq rsa ) . -.It Cm ssl_cipher -SSL cipher algorithm (e.g.\& -.Qq aes_256_cbc ) . -.It Cm ssl_hash -SSL hash function (e.g.\& -.Qq sha ) . -.It Cm peer_cert_subject -The subject of the peer's SSL certificate, in RFC4514 form. -.It Cm peer_cert_issuer -The issuer of the peer's SSL certificate, in RFC4514 form. -.It Cm peer_cert_validity -The period for which the peer's SSL certificate is valid. -.It Cm state -Connection state; one of: -.Bl -bullet -compact -.It -starting -.It -tuning -.It -opening -.It -running -.It -flow -.It -blocking -.It -blocked -.It -closing -.It -closed -.El -.It Cm channels -Number of channels using the connection. -.It Cm protocol -Version of the AMQP protocol in use; currently one of: -.Bl -bullet -compact -.It -{0,9,1} -.It -{0,8,0} -.El +Example: +.Dl rabbitmqctl ping -n rabbit@hostname +.\" ------------------------------------ +.It Cm report +Generate a server status report containing a concatenation of all server +status information for support purposes. +The output should be redirected to a file when accompanying a support +request. .Pp -Note that if a client requests an AMQP 0-9 connection, we treat it as -AMQP 0-9-1. -.It Cm auth_mechanism -SASL authentication mechanism used, such as -.Qq PLAIN . -.It Cm user -Username associated with the connection. -.It Cm vhost -Virtual host name with non-ASCII characters escaped as in C. -.It Cm timeout -Connection timeout / negotiated heartbeat interval, in seconds. -.It Cm frame_max -Maximum frame size (bytes). -.It Cm channel_max -Maximum number of channels on this connection. -.It Cm client_properties -Informational properties transmitted by the client during connection -establishment. -.It Cm recv_oct -Octets received. -.It Cm recv_cnt -Packets received. -.It Cm send_oct -Octets send. -.It Cm send_cnt -Packets sent. -.It Cm send_pend -Send queue size. -.It Cm connected_at -Date and time this connection was established, as timestamp. -.El -.Pp -If no -.Ar connectioninfoitem -are specified then user, peer host, peer port, time since flow control -and memory block state are displayed. -.Pp -For example, this command displays the send queue size and server port -for each connection: +For example, this command creates a server report which may be attached +to a support request email: .sp -.Dl rabbitmqctl list_connections send_pend port +.Dl rabbitmqctl report > server_report.txt .\" ------------------------------------ -.It Cm list_channels Op Ar channelinfoitem ... -Returns information on all current channels, the logical containers -executing most AMQP commands. -This includes channels that are part of ordinary AMQP connections, and -channels created by various plug-ins and other extensions. +.It Cm schema_info Oc Oo Fl -no-table-headers Oc Op Ar column ... +Lists schema database tables and their properties .Pp -The -.Ar channelinfoitem -parameter is used to indicate which channel information items to include -in the results. -The column order in the results will match the order of the parameters. -.Ar channelinfoitem -can take any value from the list that follows: -.Bl -tag -width Ds -.It Cm pid -Id of the Erlang process associated with the connection. -.It Cm connection -Id of the Erlang process associated with the connection to which the -channel belongs. -.It Cm name -Readable name for the channel. -.It Cm number -The number of the channel, which uniquely identifies it within a -connection. -.It Cm user -Username associated with the channel. -.It Cm vhost -Virtual host in which the channel operates. -.It Cm transactional -True if the channel is in transactional mode, false otherwise. -.It Cm confirm -True if the channel is in confirm mode, false otherwise. -.It Cm consumer_count -Number of logical AMQP consumers retrieving messages via the channel. -.It Cm messages_unacknowledged -Number of messages delivered via this channel but not yet acknowledged. -.It Cm messages_uncommitted -Number of messages received in an as yet uncommitted transaction. -.It Cm acks_uncommitted -Number of acknowledgements received in an as yet uncommitted transaction. -.It Cm messages_unconfirmed -Number of published messages not yet confirmed. -On channels not in confirm mode, this remains 0. -.It Cm prefetch_count -QoS prefetch limit for new consumers, 0 if unlimited. -.It Cm global_prefetch_count -QoS prefetch limit for the entire channel, 0 if unlimited. -.El -.Pp -If no -.Ar channelinfoitem -are specified then pid, user, consumer_count, and -messages_unacknowledged are assumed. -.Pp -For example, this command displays the connection process and count of -unacknowledged messages for each channel: +For example, this command lists the table names and their active replicas: .sp -.Dl rabbitmqctl list_channels connection messages_unacknowledged -.\" ------------------------------------ -.It Cm list_consumers Op Fl p Ar vhost -Lists consumers, i.e. subscriptions to a queue\'s message stream. -Each line printed shows, separated by tab characters, the name of -the queue subscribed to, the id of the channel process via which the -subscription was created and is managed, the consumer tag which uniquely -identifies the subscription within a channel, a boolean indicating -whether acknowledgements are expected for messages delivered to this -consumer, an integer indicating the prefetch limit (with 0 meaning -.Qq none ) , -and any arguments for this consumer. +.Dl rabbitmqctl schema_info name active_replicas .\" ------------------------------------ .It Cm status Displays broker status information such as the running applications on @@ -1706,68 +1451,500 @@ For example, this command displays information about the RabbitMQ broker: .sp .Dl rabbitmqctl status +.El +.El +.Ss Parameters +.Bl -tag -width Ds .\" ------------------------------------ -.It Cm node_health_check -Performs several health checks of the target node. +.It Cm clear_global_parameter Ar name +Clears a global runtime parameter. +This is similar to +.Cm clear_parameter +but the key-value pair isn't tied to a virtual host. +.Bl -tag -width Ds +.It Ar name +The name of the global runtime parameter being cleared. +.El .Pp -Verifies the rabbit application is running and alarms are not set, -then checks that every queue and channel on the node can emit basic stats. +For example, this command clears the global runtime parameter +.Qq mqtt_default_vhosts : .sp -Example: -.Dl rabbitmqctl node_health_check -n rabbit@hostname +.Dl rabbitmqctl clear_global_parameter mqtt_default_vhosts .\" ------------------------------------ -.It Cm environment -Displays the name and value of each variable in the application -environment for each running application. -.\" ------------------------------------ -.It Cm report -Generate a server status report containing a concatenation of all server -status information for support purposes. -The output should be redirected to a file when accompanying a support -request. +.It Cm clear_parameter Oo Fl p Ar vhost Oc Ar component_name Ar key +Clears a parameter. +.Bl -tag -width Ds +.It Ar component_name +The name of the component for which the parameter is being cleared. +.It Ar name +The name of the parameter being cleared. +.El .Pp -For example, this command creates a server report which may be attached -to a support request email: +For example, this command clears the parameter +.Qq node01 +for the +.Qq federation-upstream +component in the default virtual host: .sp -.Dl rabbitmqctl report > server_report.txt +.Dl rabbitmqctl clear_parameter federation-upstream node01 .\" ------------------------------------ -.It Cm eval Ar expr -Evaluate an arbitrary Erlang expression. +.It Cm list_global_parameters +Lists all global runtime parameters. +This is similar to +.Cm list_parameters +but the global runtime parameters are not tied to any virtual host. .Pp -For example, this command returns the name of the node to which +For example, this command lists all global parameters: +.sp +.Dl rabbitmqctl list_global_parameters +.El +.Ss Policy Management +Policies are used to control and modify the behaviour of queues and +exchanges on a cluster-wide basis. +Policies apply within a given vhost, and consist of a name, pattern, +definition and an optional priority. +Policies can be set, cleared and listed. +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm list_parameters Op Fl p Ar vhost +Lists all parameters for a virtual host. +.Pp +For example, this command lists all parameters in the default virtual +host: +.sp +.Dl rabbitmqctl list_parameters +.\" ------------------------------------ +.It Cm set_global_parameter Ar name Ar value +Sets a global runtime parameter. +This is similar to +.Cm set_parameter +but the key-value pair isn't tied to a virtual host. +.Bl -tag -width Ds +.It Ar name +The name of the global runtime parameter being set. +.It Ar value +The value for the global runtime parameter, as a JSON term. +In most shells you are very likely to need to quote this. +.El +.Pp +For example, this command sets the global runtime parameter +.Qq mqtt_default_vhosts +to the JSON term {"O=client,CN=guest":"/"}: +.sp +.Dl rabbitmqctl set_global_parameter mqtt_default_vhosts '{"O=client,CN=guest":"/"}' +.\" ------------------------------------ +.It Cm set_parameter Oo Fl p Ar vhost Oc Ar component_name Ar name Ar value +Sets a parameter. +.Bl -tag -width Ds +.It Ar component_name +The name of the component for which the parameter is being set. +.It Ar name +The name of the parameter being set. +.It Ar value +The value for the parameter, as a JSON term. +In most shells you are very likely to need to quote this. +.El +.Pp +For example, this command sets the parameter +.Qq node01 +for the +.Qq federation-upstream +component in the default virtual host to the following JSON +.Qq guest : +.sp +.Dl rabbitmqctl set_parameter federation-upstream node01 '{"uri":"amqp://user:password@server/%2F","ack-mode":"on-publish"}' +.El +.El +.Ss Policies +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm clear_operator_policy Oo Fl p Ar vhost Oc Ar name +Clears an operator policy. +Arguments are identical to those of +.Cm clear_policy . +.\" ------------------------------------ +.It Cm clear_policy Oo Fl p Ar vhost Oc Ar name +Clears a policy. +.Bl -tag -width Ds +.It Ar name +The name of the policy being cleared. +.El +.Pp +For example, this command clears the +.Qq federate-me +policy in the default virtual host: +.sp +.Dl rabbitmqctl clear_policy federate-me +.\" ------------------------------------ +.It Cm list_operator_policies Op Fl p Ar vhost +Lists operator policy overrides for a virtual host. +Arguments are identical to those of +.Cm list_policies . +.El +.Ss Virtual Host Limits +It is possible to enforce certain limits on virtual hosts. +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm list_policies Op Fl p Ar vhost +Lists all policies for a virtual host. +.Pp +For example, this command lists all policies in the default virtual +host: +.sp +.Dl rabbitmqctl list_policies +.\" ------------------------------------ +.It Cm set_operator_policy Oo Fl p Ar vhost Oc Oo Fl -priority Ar priority Oc Oo Fl -apply-to Ar apply-to Oc Ar name Ar pattern Ar definition +Sets an operator policy that overrides a subset of arguments in user +policies. +Arguments are identical to those of +.Cm set_policy . +.Pp +Supported arguments are: +.Bl -bullet -compact +.It +expires +.It +message-ttl +.It +max-length +.It +max-length-bytes +.El +.\" ------------------------------------ +.It Cm set_policy Oo Fl p Ar vhost Oc Oo Fl -priority Ar priority Oc Oo Fl -apply-to Ar apply-to Oc Ar name Ar pattern Ar definition +Sets a policy. +.Bl -tag -width Ds +.It Ar name +The name of the policy. +.It Ar pattern +The regular expression, which when matches on a given resources causes +the policy to apply. +.It Ar definition +The definition of the policy, as a JSON term. +In most shells you are very likely to need to quote this. +.It Ar priority +The priority of the policy as an integer. +Higher numbers indicate greater precedence. +The default is 0. +.It Ar apply-to +Which types of object this policy should apply to. +Possible values are: +.Bl -bullet -compact +.It +.Cm queues +.It +.Cm exchanges +.It +.Cm all +.El +The default is +.Cm all .. +.El +.Pp +For example, this command sets the policy +.Qq federate-me +in the default virtual host so that built-in exchanges are federated: +.sp +.Dl rabbitmqctl set_policy federate-me "^amq." '{"federation-upstream-set":"all"}' +.El +.Ss Virtual hosts +Note that .Nm -has connected: -.sp -.Dl rabbitmqctl eval Qq node(). -.El -.Ss Miscellaneous +manages the RabbitMQ internal user database. +Permissions for users from any alternative authorisation backend will +not be visible to +.Nm . .Bl -tag -width Ds .\" ------------------------------------ -.It Cm close_connection Ar connectionpid Ar explanation +.It Cm add_vhost Ar vhost .Bl -tag -width Ds -.It Ar connectionpid -Id of the Erlang process associated with the connection to close. -.It Ar explanation -Explanation string. +.It Ar vhost +The name of the virtual host entry to create. +.Pp +Creates a virtual host. +.Pp +For example, this command instructs the RabbitMQ broker to create a new +virtual host called +.Qq test : +.Pp +.Dl rabbitmqctl add_vhost test +.\" ------------------------------------ +.It Cm clear_vhost_limits Op Fl p Ar vhost +Clears virtual host limits. +.Pp +For example, this command clears vhost limits in vhost +.Qq qa_env : +.sp +.Dl rabbitmqctl clear_vhost_limits -p qa_env +.\" ------------------------------------ +.It Cm delete_vhost Ar vhost +.Bl -tag -width Ds +.It Ar vhost +The name of the virtual host entry to delete. .El .Pp -Instructs the broker to close the connection associated with the Erlang -process id -.Ar connectionpid -(see also the -.Cm list_connections -command), passing the -.Ar explanation -string to the connected client as part of the AMQP connection shutdown -protocol. +Deletes a virtual host. .Pp -For example, this command instructs the RabbitMQ broker to close the connection associated with the Erlang process id -.Qq , -passing the explanation -.Qq go away -to the connected client: +Deleting a virtual host deletes all its exchanges, queues, bindings, +user permissions, parameters and policies. +.Pp +For example, this command instructs the RabbitMQ broker to delete the +virtual host called +.Qq test : .sp -.Dl rabbitmqctl close_connection Qo Qc Qq go away +.Dl rabbitmqctl delete_vhost test +.\" ------------------------------------ +.It Cm list_vhost_limits Oo Fl p Ar vhost Oc Oo Fl -global Oc Op Fl -no-table-headers +Displays configured virtual host limits. +.Bl -tag -width Ds +.It Fl -global +Show limits for all vhosts. +Suppresses the +.Fl p +parameter. +.El +.El +.Ss Topology Introspection +The topology introspection commands list topology entities (e.g. queues) with tab-delimited columns. +Some commands ( +.Cm list_queues , +.Cm list_exchanges , +.Cm list_bindings +and +.Cm list_consumers ) +accept an optional +.Ar vhost +parameter. +.Pp +The +.Cm list_queues , +.Cm list_exchanges +and +.Cm list_bindings +commands accept an optional virtual host parameter for which to display +results. +The default value is +.Qq / . +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm restart_vhost Ar vhost +.Bl -tag -width Ds +.It Ar vhost +The name of the virtual host entry to restart. +.Pp +Restarts a failed vhost data stores and queues. +.Pp +For example, this command instructs the RabbitMQ broker to restart a +virtual host called +.Qq test : +.Pp +.Dl rabbitmqctl restart_vhost test +.\" ------------------------------------ +.It Cm set_vhost_limits Oo Fl p Ar vhost Oc Ar definition +Sets virtual host limits. +.Bl -tag -width Ds +.It Ar definition +The definition of the limits, as a JSON term. +In most shells you are very likely to need to quote this. +.Pp +Recognised limits are: +.Bl -bullet -compact +.It +max-connections +.It +max-queues +.El +.Pp +Use a negative value to specify "no limit". +.El +.Pp +For example, this command limits the max number of concurrent +connections in vhost +.Qq qa_env +to 64: +.sp +.Dl rabbitmqctl set_vhost_limits -p qa_env '{"max-connections": 64}' +.Pp +This command limits the max number of queues in vhost +.Qq qa_env +to 256: +.sp +.Dl rabbitmqctl set_vhost_limits -p qa_env '{"max-queues": 256}' +.Pp +This command clears the max number of connections limit in vhost +.Qq qa_env : +.sp +.Dl rabbitmqctl set_vhost_limits -p qa_env '{"max\-connections": \-1}' +.Pp +This command disables client connections in vhost +.Qq qa_env : +.sp +.Dl rabbitmqctl set_vhost_limits -p qa_env '{"max-connections": 0}' +.\" ------------------------------------ +.It Cm trace_off Op Fl p Ar vhost +.Bl -tag -width Ds +.It Ar vhost +The name of the virtual host for which to stop tracing. +.El +.Pp +Stops tracing. +.\" ------------------------------------ +.It Cm trace_on Op Fl p Ar vhost +.Bl -tag -width Ds +.It Ar vhost +The name of the virtual host for which to start tracing. +.El +.Pp +Starts tracing. +Note that the trace state is not persistent; it will revert to being off +if the server is restarted. +.El +.El +.Ss Node configuration +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm decode Ar value Ar passphrase Oo Fl -cipher Ar cipher Oc Oo Fl -hash Ar hash Oc Op Fl -iterations Ar iterations +.Bl -tag -width Ds +.It Ar value Ar passphrase +Value to decrypt (as produced by the encode command) and passphrase. +.Pp +For example: +.sp +.Dl rabbitmqctl decode '{encrypted, <<"...">>}' mypassphrase +.It Fl -cipher Ar cipher Fl -hash Ar hash Fl -iterations Ar iterations +Options to specify the decryption settings. +They can be used independently. +.Pp +For example: +.sp +.Dl rabbitmqctl decode --cipher blowfish_cfb64 --hash sha256 --iterations 10000 '{encrypted,<<"...">>} mypassphrase +.El +.\" ------------------------------------ +.It Cm encode Ar value Ar passphrase Oo Fl -cipher Ar cipher Oc Oo Fl -hash Ar hash Oc Op Fl -iterations Ar iterations +.Bl -tag -width Ds +.It Ar value Ar passphrase +Value to encrypt and passphrase. +.Pp +For example: +.sp +.Dl rabbitmqctl encode '<<"guest">>' mypassphrase +.It Fl -cipher Ar cipher Fl -hash Ar hash Fl -iterations Ar iterations +Options to specify the encryption settings. +They can be used independently. +.Pp +For example: +.sp +.Dl rabbitmqctl encode --cipher blowfish_cfb64 --hash sha256 --iterations 10000 '<<"guest">>' mypassphrase +.El +.\" ------------------------------------ +.It Cm set_cluster_name Ar name +Sets the cluster name to +.Ar name . +The cluster name is announced to clients on connection, and used by the +federation and shovel plugins to record where a message has been. +The cluster name is by default derived from the hostname of the first +node in the cluster, but can be changed. +.Pp +For example, this sets the cluster name to +.Qq london : +.sp +.Dl rabbitmqctl set_cluster_name london +.\" ------------------------------------ +.It Cm set_disk_free_limit Ar disk_limit +.Bl -tag -width Ds +.It Ar disk_limit +Lower bound limit as an integer in bytes or a string with memory unit symbols +(see vm_memory_high_watermark), e.g. 512M or 1G. +Once free disk space reaches the limit, a disk alarm will be set. +.El +.\" ------------------------------------ +.It Cm set_disk_free_limit mem_relative Ar fraction +.Bl -tag -width Ds +.It Ar fraction +Limit relative to the total amount available RAM as a non-negative +floating point number. +Values lower than 1.0 can be dangerous and should be used carefully. +.El +.\" ------------------------------------ +.It Cm set_log_level Oc Op Ar log_level +.Pp +Sets log level in the running node +.Pp +Supported +.Ar type +values are: +.Bl -tag -width Ds +.It Dv Sy debug +.It Dv Sy info +.It Dv Sy warning +.It Dv Sy error +.It Dv Sy none +.El +.Pp +Example: +.Sp +.Dl rabbitmqctl log_level debug +.\" ------------------------------------ +.It Cm set_vm_memory_high_watermark Ar fraction +.Bl -tag -width Ds +.It Ar fraction +The new memory threshold fraction at which flow control is triggered, as +a floating point number greater than or equal to 0. +.El +.\" ------------------------------------ +.It Cm set_vm_memory_high_watermark absolute Ar memory_limit +.Bl -tag -width Ds +.It Ar memory_limit +The new memory limit at which flow control is triggered, expressed in +bytes as an integer number greater than or equal to 0 or as a string +with memory unit symbol(e.g. 512M or 1G). +Available unit symbols are: +.Bl -tag -width Ds +.It Cm k , Cm kiB +kibibytes (2^10 bytes) +.It Cm M , Cm MiB +mebibytes (2^20 bytes) +.It Cm G , Cm GiB +gibibytes (2^30 bytes) +.It Cm kB +kilobytes (10^3 bytes) +.It Cm MB +megabytes (10^6 bytes) +.It Cm GB +gigabytes (10^9 bytes) +.El +.El +.Ss Feature flags +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm enable_feature_flag Ar feature_flag +Enables a feature flag on target node +Example: +.Sp +.Dl rabbitmqctl enable_feature_flag quorum_queue +.El +.\" ------------------------------------ +.It Cm list_feature_flags Oc Op Ar column ... +Lists feature flags +.Pp +Supported +.Ar column +values are: +.Bl -tag -width Ds +.It Dv Sy name +.It Dv Sy state +.It Dv Sy stability +.It Dv Sy provided_by +.It Dv Sy desc +.It Dv Sy doc_url +.El +Example: +.Sp +.Dl rabbitmqctl list_feature_flags name state +.El +.El +.Ss Operations +.Bl -tag -width Ds .\" ------------------------------------ .It Cm close_all_connections Oo Fl p Ar vhost Oc Oo Fl -global Oc Oo Fl -per-connection-delay Ar delay Oc Oo Fl -limit Ar limit Oc Ar explanation .Bl -tag -width Ds @@ -1806,120 +1983,105 @@ This command instructs broker to close all connections to the node: .Dl rabbitmqctl close_all_connections --global .sp .\" ------------------------------------ -.It Cm trace_on Op Fl p Ar vhost +.It Cm close_connection Ar connectionpid Ar explanation .Bl -tag -width Ds -.It Ar vhost -The name of the virtual host for which to start tracing. +.It Ar connectionpid +Id of the Erlang process associated with the connection to close. +.It Ar explanation +Explanation string. .El .Pp -Starts tracing. -Note that the trace state is not persistent; it will revert to being off -if the server is restarted. -.\" ------------------------------------ -.It Cm trace_off Op Fl p Ar vhost -.Bl -tag -width Ds -.It Ar vhost -The name of the virtual host for which to stop tracing. -.El +Instructs the broker to close the connection associated with the Erlang +process id +.Ar connectionpid +(see also the +.Cm list_connections +command), passing the +.Ar explanation +string to the connected client as part of the AMQP connection shutdown +protocol. .Pp -Stops tracing. -.\" ------------------------------------ -.It Cm set_vm_memory_high_watermark Ar fraction -.Bl -tag -width Ds -.It Ar fraction -The new memory threshold fraction at which flow control is triggered, as -a floating point number greater than or equal to 0. -.El -.\" ------------------------------------ -.It Cm set_vm_memory_high_watermark absolute Ar memory_limit -.Bl -tag -width Ds -.It Ar memory_limit -The new memory limit at which flow control is triggered, expressed in -bytes as an integer number greater than or equal to 0 or as a string -with memory unit symbol(e.g. 512M or 1G). -Available unit symbols are: -.Bl -tag -width Ds -.It Cm k , Cm kiB -kibibytes (2^10 bytes) -.It Cm M , Cm MiB -mebibytes (2^20 bytes) -.It Cm G , Cm GiB -gibibytes (2^30 bytes) -.It Cm kB -kilobytes (10^3 bytes) -.It Cm MB -megabytes (10^6 bytes) -.It Cm GB -gigabytes (10^9 bytes) -.El -.El -.\" ------------------------------------ -.It Cm set_disk_free_limit Ar disk_limit -.Bl -tag -width Ds -.It Ar disk_limit -Lower bound limit as an integer in bytes or a string with memory unit symbols -(see vm_memory_high_watermark), e.g. 512M or 1G. -Once free disk space reaches the limit, a disk alarm will be set. -.El -.\" ------------------------------------ -.It Cm set_disk_free_limit mem_relative Ar fraction -.Bl -tag -width Ds -.It Ar fraction -Limit relative to the total amount available RAM as a non-negative -floating point number. -Values lower than 1.0 can be dangerous and should be used carefully. -.El -.\" ------------------------------------ -.It Cm encode Ar value Ar passphrase Oo Fl -cipher Ar cipher Oc Oo Fl -hash Ar hash Oc Op Fl -iterations Ar iterations -.Bl -tag -width Ds -.It Ar value Ar passphrase -Value to encrypt and passphrase. -.Pp -For example: +For example, this command instructs the RabbitMQ broker to close the connection associated with the Erlang process id +.Qq , +passing the explanation +.Qq go away +to the connected client: .sp -.Dl rabbitmqctl encode '<<"guest">>' mypassphrase -.It Fl -cipher Ar cipher Fl -hash Ar hash Fl -iterations Ar iterations -Options to specify the encryption settings. -They can be used independently. -.Pp -For example: -.sp -.Dl rabbitmqctl encode --cipher blowfish_cfb64 --hash sha256 --iterations 10000 '<<"guest">>' mypassphrase -.El +.Dl rabbitmqctl close_connection Qo Qc Qq go away .\" ------------------------------------ -.It Cm decode Ar value Ar passphrase Oo Fl -cipher Ar cipher Oc Oo Fl -hash Ar hash Oc Op Fl -iterations Ar iterations +.It Cm eval Ar expr +Evaluate an arbitrary Erlang expression. +.Pp +For example, this command returns the name of the node to which +.Nm +has connected: +.sp +.Dl rabbitmqctl eval Qq node(). +.El +.Ss Miscellaneous .Bl -tag -width Ds -.It Ar value Ar passphrase -Value to decrypt (as produced by the encode command) and passphrase. -.Pp -For example: -.sp -.Dl rabbitmqctl decode '{encrypted, <<"...">>}' mypassphrase -.It Fl -cipher Ar cipher Fl -hash Ar hash Fl -iterations Ar iterations -Options to specify the decryption settings. -They can be used independently. -.Pp -For example: -.sp -.Dl rabbitmqctl decode --cipher blowfish_cfb64 --hash sha256 --iterations 10000 '{encrypted,<<"...">>} mypassphrase -.El .\" ------------------------------------ -.It Cm list_hashes -Lists hash functions supported by encoding commands. -.Pp -For example, this command instructs the RabbitMQ broker to list all hash -functions supported by encoding commands: -.sp -.Dl rabbitmqctl list_hashes +.It Cm exec Ar expr Oc Op Fl -offline +Evaluates a snippet of Elixir code on the CLI node .\" ------------------------------------ -.It Cm list_ciphers -Lists cipher suites supported by encoding commands. +.It Cm force_gc +Makes all Erlang processes on the target node perform/schedule a full sweep garbage collection +Example: +.Sp +.Dl rabbitmqctl force_gc +.\" ------------------------------------ +.It Cm hipe_compile Ar directory +Performs HiPE-compilation and caches resulting +.Pa .beam Ns -files in the given directory. .Pp -For example, this command instructs the RabbitMQ broker to list all -cipher suites supported by encoding commands: +Parent directories are created if necessary. +Any existing +.Pa .beam +files from the directory are automatically deleted prior to compilation. +.Pp +To use this precompiled files, you should set +.Ev RABBITMQ_SERVER_CODE_PATH +environment variable to directory specified in +.Cm hipe_compile +invocation. +.Pp +For example, to HiPE-compile modules and store them to +.Pa /tmp/rabbit-hipe/ebin +directory: .sp -.Dl rabbitmqctl list_ciphers +.Dl rabbitmqctl hipe_compile /tmp/rabbit-hipe/ebin .El +.El +.Ss Queues +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm delete_queue Oc Ar queue_name Oc Oo Fl -if-empty | Fl e Oc Op Fl -if-unused | Fl u +.Bl -tag -width Ds +.It Ar queue_name +The name of the queue to delete. +.It Ar --if-empty +Delete the queue if it is empty (has no messages ready for delivery) +.It Ar --if-unused +Delete the queue only if it has no consumers +.El +.Pp +Deletes a queue. +.\" ------------------------------------ +.It Cm purge_queue Oo Fl p Ar vhost Oc Ar queue +.Bl -tag -width Ds +.It Ar queue +The name of the queue to purge. +.El +.Pp +Purges a queue (removes all messages in it). +.\" ------------------------------------ +.It Cm quorum_status Oc Ar queue_name +.Bl -tag -width Ds +.It Ar queue_name +The name of the queue. +.El +.Pp +Displays quorum status of a quorum queue. .\" ------------------------------------------------------------------ .Sh PLUGIN COMMANDS .\" ------------------------------------------------------------------