Skip to main content
Version: Next

Plugins

Overview​

This guide covers

and more.

Plugin development is covered in a separate guide.

The Basics​

RabbitMQ supports plugins. Plugins extend core broker functionality in a variety of ways: with support for more protocols, system state monitoring, additional AMQP 0-9-1 exchange types, node federation, and more. A number of features are implemented as plugins that ship in the core distribution.

This guide covers the plugin mechanism and plugins that ship in the latest release of the RabbitMQ distribution. 3rd party plugins can be installed separately. A set of curated plugins is also available.

Plugins are activated when a node is started or at runtime when a CLI tool is used. For a plugin to be activated at boot, it must be enabled. To enable a plugin, use the rabbitmq-plugins:

rabbitmq-plugins enable <plugin-name>

For example, to enable the Kubernetes peer discovery plugin:

rabbitmq-plugins enable rabbitmq_peer_discovery_k8s

And to disable a plugin, use:

rabbitmq-plugins disable <plugin-name>

For example, to disable the rabbitmq-top plugin:

rabbitmq-plugins disable rabbitmq_top

A list of plugins available locally (in the node's plugins directory) as well as their status (enabled or disabled) can be obtained using rabbitmq-plugins list:

rabbitmq-plugins list

To list available plugins without the legend header (marker explanations at the top):

rabbitmq-plugins list -s

To list available plugins in JSON:

rabbitmq-plugins list --formatter=json

Different Ways to Enable Plugins​

The rabbitmq-plugins command enables or disables plugins by contacting the running node to tell it to start or stop plugins as needed. It is possible to contact an arbitrary node -n option to specify a different node.

Having a node running before the plugins are enabled is not always practical or operator-friendly. For those cases rabbitmq-plugins provides an alternative way. If the --offline flag is specified, the tool will not contact any nodes and instead will modify the file containing the list of enabled plugins (appropriately named enabled_plugins) directly. This option is often optimal for node provisioning automation.

The enabled_plugins file is usually located in the node data directory or under /etc, together with configuration files. The file contains a list of plugin names ending with a dot. For example, when rabbitmq_management and rabbitmq_shovel plugins are enabled, the file contents will look like this:

[rabbitmq_management,rabbitmq_management_agent,rabbitmq_shovel].

Note that dependencies of plugins are not listed. Plugins with correct dependency metadata will specify their dependencies there and they will be enabled first at the time of plugin activation. Unlike rabbitmq-plugins disable calls against a running node, changes to the file require a node restart.

The file can be generated by deployment tools. This is another automation-friendly approach. When a plugin must be disabled, it should be removed from the list and the node must be restarted.

For more information on rabbitmq-plugins, consult the manual page.

Plugin Directories​

RabbitMQ loads plugins from the local filesystem. Plugins are distributed as archives (.ez files) with compiled code modules and metadata. Since some plugins ship with RabbitMQ, every node has at least one default plugin directory. The path varies between package types and can be overridden using the RABBITMQ_PLUGINS_DIR environment variable. Please see File and Directory Locations guide to learn about the default value on various platforms.

tip

the plugin directory can be a list of paths separated by a colon (on Linux, MacOS, BSD) or a semicolon (Windows with PowerShell)

The built-in plugin directory is by definition version-independent: its contents will change from release to release. So will its exact path (by default) which contains version number, e.g. /usr/lib/rabbitmq/lib/rabbitmq_server-3.11.6/plugins. Because of this automated installation of 3rd party plugins into this directory is harder and more error-prone, and therefore not recommended.

To solve this problem, the plugin directory can be a list of paths separated by a colon (on Linux, MacOS, BSD) or a semicolon (Windows with PowerShell):

# Example rabbitmq-env.conf file that features a colon-separated list of plugin directories
PLUGINS_DIR="/usr/lib/rabbitmq/plugins:/usr/lib/rabbitmq/lib/rabbitmq_server-3.11.6/plugins"

Plugin directory paths that don't have a version-specific component and are not updated by RabbitMQ package installers during upgrades are optimal for 3rd party plugin installation. Provisioning automation tools can rely on those directories to be stable and only managed by them.

3rd party plugin directories will differ from platform to platform and installation method to installation method. For example, /usr/lib/rabbitmq/plugins is a 3rd party plugin directory path used by RabbitMQ Debian packages.

Plugin directory can be located by executing the rabbitmq-plugins directories command on the host with a running RabbitMQ node:

rabbitmq-plugins directories -s
# => Plugin archives directory: /path/to/rabbitmq/plugins
# => Plugin expansion directory: /path/to/node/node-plugins-expand
# => Enabled plugins file: /path/to/enabled_plugins

The first directory in the example above is the 3rd party plugin directory. The second one contains plugins that ship with RabbitMQ and will change as installed RabbitMQ version changes between upgrades.

rabbitmq-plugins​

When plugin directories are overridden using an environment variable, the same variable must also be set identically for the local OS user that invokes CLI tools.

If this is not done, rabbitmq-plugins in offline mode will not locate the correct directory.

The Enabled Plugins File​

The list of currently enabled plugins on a node is stored in a file. The file is commonly known as the enabled plugins file. Depending on the package type it is usually located under the etc directory or under the node's data directory. Its path can be overridden using the RABBITMQ_ENABLED_PLUGINS_FILE environment variable. As a user you don't usually have to think about that file as it is managed by the node and rabbitmq-plugins (when used in --offline mode).

Deployment automation tools must make sure that the file is readable and writeable by the local RabbitMQ node. In environments that need to preconfigure plugins the file can be machine-generated at deployment time. The plugin names on the list are exactly the same as listed by rabbitmq-plugins list.

The file contents is an Erlang term file that contains a single list:

[rabbitmq_management,rabbitmq_management_agent,rabbitmq_mqtt,rabbitmq_stomp].

Note that the trailing dot is significant and cannot be left out.

Plugin Expansion (Extraction)​

Not every plugin can be loaded from an archive .ez file. For this reason RabbitMQ will extract plugin archives on boot into a separate directory that is then added to its code path. This directory is known as the expanded plugins directory. It is usually managed entirely by RabbitMQ but if node directories are changed to non-standard ones, that directory will likely need to be overridden, too. It can be done using the RABBITMQ_PLUGINS_EXPAND_DIR environment variable. The directory must be readable and writable by the effective operating system user of the RabbitMQ node.

Troubleshooting​

tip

A significant majority of 3rd-party plugin activation issues come down to insufficient filesystem permissions

If a 3rd party plugin was installed but cannot be found, the most likely reasons are

  • Incorrect plugin directory
  • rabbitmq-plugins and the server use different plugin directories
  • rabbitmq-plugins and the server use different enable plugin file
  • The plugin doesn't declare a dependency on RabbitMQ core
  • Plugin version is incompatible with RabbitMQ core

3rd Party Plugin Not Found​

When a plugin is enabled but the server cannot locate it, it will report an error. Since any plugin name can be given to rabbitmq-plugins, double check the name:

# note the typo
rabbitmq-plugins enable rabbitmq_managemenr
# => Error:
# => {:plugins_not_found, [:rabbitmq_managemenr]}

Another common reason is that plugin directory the plugin archive (the .ez file) was downloaded to doesn't match that of the server.

Plugin directory can be located by executing the rabbitmq-plugins directories command on the host with a running RabbitMQ node:

rabbitmq-plugins directories -s
# => Plugin archives directory: /path/to/rabbitmq/plugins
# => Plugin expansion directory: /path/to/node/node-plugins-expand
# => Enabled plugins file: /path/to/enabled_plugins

The first directory in the example above is the 3rd party plugin directory. The second one contains plugins that ship with RabbitMQ and will change as installed RabbitMQ version changes between upgrades.

which and similar tools can be used to locate rabbitmq-plugins and determine if it comes from the expected installation:

which rabbitmq-plugins
# => /path/to/rabbitmq/installation/sbin/rabbitmq-plugins

Plugin Cannot be Enabled​

In some environments, in particular development ones, rabbitmq-plugins comes from a different installation than the running server node. This can be the case when a node is installed using a binary build package but CLI tools come from the local package manager such as apt or Homebrew.

In that case CLI tools will have a different enabled plugins file from the server and the operation will fail with an error:

rabbitmq-plugins enable rabbitmq_top
Enabling plugins on node rabbit@warp10:
# =>  rabbitmq_top
# =>  The following plugins have been configured:
# =>    rabbitmq_management
# =>    rabbitmq_management_agent
# =>    rabbitmq_shovel
# =>    rabbitmq_shovel_management
# =>    rabbitmq_top
# =>    rabbitmq_web_dispatch
# =>  Applying plugin configuration to rabbit@warp10...
# =>  Error:
# =>  {:enabled_plugins_mismatch, '/path/to/installation1/etc/rabbitmq/enabled_plugins', '/path/to/installation2/etc/rabbitmq/enabled_plugins'}

The first path in the error above corresponds to the enabled plugins file used by rabbitmq-plugins, the second one is that used by the target RabbitMQ node.

rabbitmqctl environment can be used to inspect effective enabled plugins file path used by the server:

rabbitmq-plugins directories -s
# => Plugin archives directory: /path/to/rabbitmq/plugins
# => Plugin expansion directory: /path/to/node/node-plugins-expand
# => Enabled plugins file: /path/to/enabled_plugins

Other common reasons that prevent plugins from being enabled can include plugin archive and/or plugin expansion directories permissions not having sufficient privileges for the effective user of the server node. In other words, the node cannot use those directories to complete plugin activation and loading.

CLI Commands From a Plugin are Not Discovered​

When performing command discovery, CLI tools will consult the Enabled Plugins File to determine what plugins to scan for commands. If a plugin is not included into that file, e.g. because it was enabled implicitly as a dependency, it won't be listed in the enabled plugins file and thus its CLI commands will not be discovered.

Plugin Tiers​

Plugins that ship with the RabbitMQ distributions are often referred to as tier 1 plugins. Provided that a standard distribution package is used they do not need to be installed but do need to be enabled before they can be used.

In addition to the plugins bundled with the server, team RabbitMQ offers binary downloads of curated plugins which have been contributed by authors in the community. See the community plugins page for more details.

Even more plugins can be found on GitHub, GitLab, Bitbucket and similar services.

Tier 1 (Core) Plugins in Open Source RabbitMQ​

The table below lists tier 1 (core) plugins that ship with RabbitMQ.

Plugin nameDescription
rabbitmq_auth_backend_ldap

Authentication and authorisation plugin using an external LDAP server.

rabbitmq_auth_backend_oauth2

Authentication and authorisation plugin using OAuth 2.0 protocol.

rabbitmq_auth_backend_http

Authentication and authorisation plugin that uses an external HTTP API.

rabbitmq_auth_mechanism_ssl

Authentication mechanism plugin using SASL EXTERNAL to authenticate using TLS (x509) client certificates.

rabbitmq_consistent_hash_exchange

Consistent hashing exchange.

rabbitmq_federation

Scalable messaging across WANs and administrative domains.

rabbitmq_federation_management

Shows federation status in the management API and UI. Only of use when using rabbitmq_federation in conjunction with rabbitmq_management. In a heterogeneous cluster this should be installed on the same nodes as rabbitmq_management.

rabbitmq_jms_topic_exchange

A special exchange type to be used with the RabbitMQ JMS client.

rabbitmq_management

A management / monitoring API over HTTP, along with a browser-based UI.

rabbitmq_management_agent

When installing the management plugin on some of the nodes in a cluster, rabbitmq_management_agent must be enabled on all on all cluster nodes nodes, otherwise stats for some nodes will not be collected.

rabbitmq_mqtt

MQTT 5 and 3.1.1 support.

rabbitmq_prometheus

Prometheus monitoring support.

rabbitmq_shovel

A plug-in for RabbitMQ that shovels messages from a queue on one broker to an exchange on another broker.

rabbitmq_shovel_management

Shows Shovel status in the management API and UI. Only of use when using rabbitmq_shovel in conjunction with rabbitmq_management. In a heterogeneous cluster this should be installed on the same nodes as RabbitMQ management plugin.

rabbitmq_stomp

Provides STOMP protocol support in RabbitMQ.

rabbitmq_tracing

Adds message tracing to the management plugin. Logs messages from the firehose in a couple of formats.

rabbitmq_trust_store

Provides a client x509 certificate trust store.

rabbitmq_web_stomp

STOMP-over-WebSockets: a bridge exposing rabbitmq_stomp to web browsers using WebSockets.

rabbitmq_web_mqtt

MQTT-over-WebSockets: a bridge exposing rabbitmq_mqtt to Web browsers using WebSockets.

rabbitmq_web_stomp_examples

Adds some basic examples to rabbitmq_web_stomp: a simple "echo" service and a basic canvas-based collaboration tool.

rabbitmq_web_mqtt_examples

Adds some basic examples to rabbitmq_web_mqtt: a simple "echo" service and a basic canvas-based collaboration tool.

Additional Plugins in VMware Tanzu RabbitMQ®​

The table below lists of plugins only available in Tanuz RabbitMQ®.

Plugin nameDescription
rabbitmq_schema_definition_sync

Part of Warm Standby Replication.

rabbitmq_standby_replication

Part of Warm Standby Replication.

Discontinued​

All plugins below have been discontinued. They no longer ship with the RabbitMQ distribution and are no longer actively maintained by the RabbitMQ core team.

  • rabbitmq_auth_backend_amqp
  • rabbitmq_management_visualiser