path: root/deps/rabbit/docs/rabbitmq-plugins.8

.\" vim:ft=nroff:
.\" This Source Code Form is subject to the terms of the Mozilla Public 
.\" License, v. 2.0. If a copy of the MPL was not distributed with this
.\" file, You can obtain one at https://mozilla.org/MPL/2.0/.
.\"
.\" Copyright (c) 2007-2020 VMware, Inc. or its affiliates.  All rights reserved.
.\"
.Dd September 28, 2019
.Dt RABBITMQ-PLUGINS 8
.Os "RabbitMQ Server"
.Sh NAME
.Nm rabbitmq-plugins
.Nd command line tool for managing RabbitMQ plugins
.\" ------------------------------------------------------------------
.Sh SYNOPSIS
.\" ------------------------------------------------------------------
.Nm
.Op Fl q
.Op Fl s
.Op Fl l
.Op Fl n Ar node
.Op Fl t Ar timeout
.Ar command
.Op Ar command_options
.\" ------------------------------------------------------------------
.Sh DESCRIPTION
.\" ------------------------------------------------------------------
.Nm
is a command line tool for managing RabbitMQ plugins.
See the
.Lk https://www.rabbitmq.com/plugins.html "RabbitMQ Plugins guide"
for an overview of RabbitMQ plugins and how they are used.

.Nm
allows the operator to enable, disable and inspect plugins.
It must be run by a user with write permissions to the RabbitMQ
configuration directory.
.Pp
Plugins can depend on other plugins.
.Nm
resolves the dependencies and enables or disables all dependencies
so that the user doesn't have to manage them explicitly.
Plugins listed on the
.Nm
command line are marked as explicitly enabled; dependent plugins are
marked as implicitly enabled.
Implicitly enabled plugins are automatically disabled again when they
are no longer required.
.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 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,
.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.
To learn more, see the
.Lk https://www.rabbitmq.com/plugins.html "RabbitMQ Plugins guide"
.
.\" ------------------------------------------------------------------
.Sh OPTIONS
.\" ------------------------------------------------------------------
.Bl -tag -width Ds
.It Fl n Ar node
Default node is
.Qq Ar rabbit@target-hostname ,
where
.Ar target-hostname
is the local host.
On a host named
.Qq myserver.example.com ,
the node name will usually be
.Qq rabbit@myserver
(unless
.Ev RABBITMQ_NODENAME
has been overridden).
The output of
.Qq hostname -s
is usually the correct suffix to use after the
.Qq @
sign.
See
.Xr rabbitmq-server 8
for details of configuring a RabbitMQ node.
.It Fl q , -quiet
Quiet output mode is selected.
Informational messages are reduced when quiet mode is in effect.
.It Fl s , -silent
Silent output mode is selected.
Informational messages are reduced and table headers are suppressed when silent mode is in effect.
.It Fl t Ar timeout , Fl -timeout Ar timeout
Operation timeout in seconds.
Not all commands support timeouts.
Default is
.Cm infinity .
.It Fl l , Fl -longnames
Must be specified when the cluster is configured to use long (FQDN) node names.
To learn more, see the
.Lk https://www.rabbitmq.com/clustering.html "RabbitMQ Clustering guide"
.It Fl -erlang-cookie Ar cookie
Shared secret to use to authenticate to the target node.
Prefer using a local file or the
.Ev RABBITMQ_ERLANG_COOKIE
environment variable instead of specifying this option on the command line.
To learn more, see the
.Lk https://www.rabbitmq.com/cli.html "RabbitMQ CLI Tools guide"
.El
.\" ------------------------------------------------------------------
.Sh COMMANDS
.\" ------------------------------------------------------------------
.Bl -tag -width Ds
.\" ------------------------------------
.It Cm list Oo Fl Eemv Oc Op Ar pattern
.Bl -tag -width Ds
.It Fl E
Show only explicitly enabled plugins.
.It Fl e
Show only explicitly or implicitly enabled plugins.
.It Fl m
Show only plugin names (minimal).
.It Fl v
Show all plugin details (verbose).
.It Ar pattern
Pattern to filter the plugin names by.
.El
.Pp
Lists all plugins, their versions, dependencies and descriptions.
Each plugin is prefixed with two status indicator characters inside [ ].
The first indicator can be:
.Bl -tag -width <space> -compact
.It Sy <space>
to indicate that the plugin is not enabled
.It Sy E
to indicate that it is explicitly enabled
.It Sy e
to indicate that it is implicitly enabled
.It Sy \!
to indicate that it is enabled but missing and thus not operational
.El
.Pp
The second indicator can be:
.Bl -tag -width <space> -compact
.It Sy <space>
to show that the plugin is not running
.It Sy *
to show that it is
.El
.Pp
If the optional pattern is given, only plugins whose name matches
.Ar pattern
are shown.
.Pp
For example, this command lists all plugins, on one line each
.sp
.Dl rabbitmq-plugins list
.Pp
This command lists all plugins:
.sp
.Dl rabbitmq-plugins list -v
.Pp
This command lists all plugins whose name contains "management".
.sp
.Dl rabbitmq-plugins list -v management
.Pp
This command lists all implicitly or explicitly enabled RabbitMQ plugins.
.sp
.Dl rabbitmq-plugins list -e rabbit
.\" ------------------------------------
.It Cm enable Oo Fl -offline Oc Oo Fl -online Oc Ar plugin ...
.Bl -tag -width Ds
.It Fl -offline
Modify node's enabled plugin state directly without contacting the node.
.It Fl -online
Treat a failure to connect to the running broker as fatal.
.It Ar plugin
One or more plugins to enable.
.El
.Pp
Enables the specified plugins and all their dependencies.
.Pp
For example, this command enables the
.Qq shovel
and
.Qq management
plugins and all their dependencies:
.sp
.Dl rabbitmq\-plugins enable rabbitmq_shovel rabbitmq_management
.\" ------------------------------------
.It Cm disable Oo Fl -offline Oc Oo Fl -online Oc Ar plugin ...
.Bl -tag -width Ds
.It Fl -offline
Modify node's enabled plugin state directly without contacting the node.
.It Fl -online
Treat a failure to connect to the running broker as fatal.
.It Ar plugin
One or more plugins to disable.
.El
.Pp
Disables the specified plugins and all their dependencies.
.Pp
For example, this command disables
.Qq rabbitmq_management
and all plugins that depend on it:
.sp
.Dl rabbitmq-plugins disable rabbitmq_management
.\" ------------------------------------
.It Cm set Oo Fl -offline Oc Oo Fl -online Oc Op Ar plugin ...
.Bl -tag -width Ds
.It Fl -offline
Modify node's enabled plugin state directly without contacting the node.
.It Fl -online
Treat a failure to connect to the running broker as fatal.
.It Ar plugin
Zero or more plugins to disable.
.El
.Pp
Enables the specified plugins and all their dependencies.
Unlike
.Cm enable ,
this command ignores and overwrites any existing enabled plugins.
.Cm set
with no plugin arguments is a legal command meaning "disable all plugins".
.Pp
For example, this command enables the
.Qq management
plugin and its dependencies and disables everything else:
.sp
.Dl rabbitmq-plugins set rabbitmq_management
.El
.\" ------------------------------------------------------------------
.Sh SEE ALSO
.\" ------------------------------------------------------------------
.Xr rabbitmqctl 8 ,
.Xr rabbitmq-diagnostics 8 ,
.Xr rabbitmq-server 8 ,
.Xr rabbitmq-queues 8 ,
.Xr rabbitmq-upgrade 8 ,
.Xr rabbitmq-service 8 ,
.Xr rabbitmq-env.conf 5 ,
.Xr rabbitmq-echopid 8
.\" ------------------------------------------------------------------
.Sh AUTHOR
.\" ------------------------------------------------------------------
.An The RabbitMQ Team Aq Mt info@rabbitmq.com