rabbitmqctl(8) WIP

3 files changed, 185 insertions, 51 deletions

diff --git a/docs/rabbitmq-diagnostics.8 b/docs/rabbitmq-diagnostics.8
index 193d6b0fc2..aae6b4ee60 100644
--- a/docs/rabbitmq-diagnostics.8
+++ b/docs/rabbitmq-diagnostics.8
@@ -42,28 +42,14 @@ See the
 to learn more about RabbitMQ diagnostics, monitoring and health checks.
 
 .Nm
-allows the operator to TODO.
+allows the operator to inspect node and cluster state. A number of
+health checks are available to be used interactively and by monitoring tools.
 
 .Pp
-The
-.Cm enable ,
-.Cm disable ,
-and
-.Cm set
-commands will update the plugins file and then attempt to connect to the
-broker and ensure it is running all enabled plugins.
-By default if it is not possible to connect to the running broker (for
-example if it is stopped) the operation will fail.
-If
-.Nm
-is used on the same host as the target node,
-.Fl -offline
-can be specified to make
-.Nm
-resolve and update plugin state directly (without contacting the node).
-Such changes will only have an effect on next node start.
+By default if it is not possible to connect to and authenticate with the target node
+(for example if it is stopped), the operation will fail.
 To learn more, see the
-.Lk https://www.rabbitmq.com/plugins.html "RabbitMQ Plugins guide"
+.Lk https://www.rabbitmq.com/monitoring.html "RabbitMQ Monitoring guide"
 .
 .\" ------------------------------------------------------------------
 .Sh OPTIONS
@@ -115,4 +101,155 @@ To learn more, see the
 .El
 .\" ------------------------------------------------------------------
 .Sh COMMANDS
+.\" ------------------------------------
+.Ss Topology Introspection
+.Pp
+The topology introspection commands list topology entities (e.g. queues) with tab-delimited columns.
+.
+These commands and their arguments are delegated to rabbitmqctl(8).
+.Pp
+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 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 status
+See
+.Cm status
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm node_health_check
+Performs several health checks of the target node.
+.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.
+.Pp
+Example:
+.Sp
+.Dl rabbitmqctl node_health_check -n rabbit@hostname
+.\" ------------------------------------
+.It Cm environment
+See
+.Cm environment
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm report
+See
+.Cm report
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm list_global_parameters
+See
+.Cm list_global_parameters
+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
+See
+.Cm list_permissions
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm list_policies Op Fl p Ar vhost
+See
+.Cm list_policies
+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_users
+See
+.Cm list_users
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm list_vhosts Op Ar vhostinfoitem ...
+See
+.Cm list_vhosts
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
diff --git a/docs/rabbitmq-plugins.8 b/docs/rabbitmq-plugins.8
index 3962a7d555..4d0d86150e 100644
--- a/docs/rabbitmq-plugins.8
+++ b/docs/rabbitmq-plugins.8
@@ -63,8 +63,8 @@ and
 .Cm set
 commands will update the plugins file and then attempt to connect to the
 broker and ensure it is running all enabled plugins.
-By default if it is not possible to connect to the running broker (for
-example if it is stopped) the operation will fail.
+By default if it is not possible to connect to and authenticate with the target node
+(for example if it is stopped), the operation will fail.
 If
 .Nm
 is used on the same host as the target node,
diff --git a/docs/rabbitmqctl.8 b/docs/rabbitmqctl.8
index 5f63b88e11..64648627d3 100644
--- a/docs/rabbitmqctl.8
+++ b/docs/rabbitmqctl.8
@@ -812,12 +812,12 @@ For example, this command instructs the RabbitMQ broker to grant the
 user named
 .Qq janeway
 access to the virtual host called
-.Qq /myvhost ,
+.Qq my-vhost ,
 with configure permissions on all resources whose names starts with
 .Qq janeway- ,
 and write and read permissions on all resources:
 .sp
-.Dl rabbitmqctl set_permissions -p /myvhost janeway Qo ^janeway-.* Qc Qo .* Qc Qq .*
+.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
@@ -835,9 +835,9 @@ For example, this command instructs the RabbitMQ broker to deny the user
 named
 .Qq janeway
 access to the virtual host called
-.Qq /myvhost :
+.Qq my-vhost :
 .sp
-.Dl rabbitmqctl clear_permissions -p /myvhost janeway
+.Dl rabbitmqctl clear_permissions -p my-vhost janeway
 .\" ------------------------------------
 .It Cm list_permissions Op Fl p Ar vhost
 .Bl -tag -width Ds
@@ -852,12 +852,12 @@ 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 /myvhost ,
+.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 /myvhost
+.Dl rabbitmqctl list_permissions -p my-vhost
 .\" ------------------------------------
 .It Cm list_user_permissions Ar username
 .Bl -tag -width Ds
@@ -899,18 +899,18 @@ user named
 publish and consume messages going through the
 .Qq amp.topic
 exchange of the
-.Qq /myvhost
+.Qq my-vhost
 virtual host with a routing key starting with
 .Qq janeway- :
 .sp
-.Dl rabbitmqctl set_topic_permissions -p /myvhost janeway amq.topic Qo ^janeway-.* Qc Qo ^janeway-.* Qc
+.Dl rabbitmqctl set_topic_permissions -p my-vhost janeway amq.topic Qo ^janeway-.* Qc Qo ^janeway-.* Qc
 .Pp
 Topic permissions support variable expansion for the following variables:
 username, vhost, and client_id. Note that client_id is expanded only when using MQTT.
 The previous example could be made more generic by using
 .Qq ^{username}-.* :
 .sp
-.Dl rabbitmqctl set_topic_permissions -p /myvhost janeway amq.topic Qo ^{username}-.* Qc Qo ^{username}-.* Qc
+.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
@@ -933,9 +933,9 @@ named
 for the topic exchange
 .Qq amq.topic
 in the virtual host called
-.Qq /myvhost :
+.Qq my-vhost :
 .sp
-.Dl rabbitmqctl clear_topic_permissions -p /myvhost janeway amq.topic
+.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
@@ -949,9 +949,9 @@ 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 /myvhost:
+.Qq my-vhost:
 .sp
-.Dl rabbitmqctl list_topic_permissions -p /myvhost
+.Dl rabbitmqctl list_topic_permissions -p my-vhost
 .\" ------------------------------------
 .It Cm list_user_topic_permissions Ar username
 .Bl -tag -width Ds
@@ -1230,10 +1230,9 @@ Suppresses the
 parameter.
 .El
 .El
-.Ss Server Status
-The server status queries interrogate the server and return a list of
-results with tab-delimited columns.
-Some queries (
+.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
@@ -1242,8 +1241,6 @@ and
 accept an optional
 .Ar vhost
 parameter.
-This parameter, if present, must be specified immediately after the
-query.
 .Pp
 The
 .Cm list_queues ,
@@ -1399,9 +1396,9 @@ are specified then queue name and depth are displayed.
 .Pp
 For example, this command displays the depth and number of consumers for
 each queue of the virtual host named
-.Qq /myvhost
+.Qq my-vhost
 .sp
-.Dl rabbitmqctl list_queues -p /myvhost messages consumers
+.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.
@@ -1455,9 +1452,9 @@ 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 /myvhost :
+.Qq my-vhost :
 .sp
-.Dl rabbitmqctl list_exchanges -p /myvhost name type
+.Dl rabbitmqctl list_exchanges -p my-vhost name type
 .\" ------------------------------------
 .It Cm list_bindings Oo Fl p Ar vhost Oc Op Ar bindinginfoitem ...
 Returns binding details.
@@ -1503,9 +1500,9 @@ 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 /myvhost
+.Qq my-vhost
 .sp
-.Dl rabbitmqctl list_bindings -p /myvhost exchange_name queue_name
+.Dl rabbitmqctl list_bindings -p my-vhost exchange_name queue_name
 .\" ------------------------------------
 .It Cm list_connections Op Ar connectioninfoitem ...
 Returns TCP/IP connection statistics.
@@ -1711,13 +1708,13 @@ broker:
 .Dl rabbitmqctl status
 .\" ------------------------------------
 .It Cm node_health_check
-Health check of the RabbitMQ node.
-Verifies the rabbit application is running, list_queues and
-list_channels return, and alarms are not set.
+Performs several health checks of the target node.
 .Pp
-For example, this command performs a health check on the RabbitMQ node:
+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 node_health_check -n rabbit@stringer
+Example:
+.Dl rabbitmqctl node_health_check -n rabbit@hostname
 .\" ------------------------------------
 .It Cm environment
 Displays the name and value of each variable in the application