Menu

Plugins

Overview

This guide covers

and more.

Plugin development is covered in a separate guide.

Overview

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 with RabbitMQ 3.7.9. 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
And to disable a plugin, use:
rabbitmq-plugins disable plugin-name

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

Different Ways to Enable Plugins

The rabbitmq-plugins comand 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.

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.7.9/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):

# 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.7.9/plugins"
On Windows, a semicolon is used as path separator:
# Example rabbitmq-env-conf.bat file that features a colon-separated list of plugin directories
PLUGINS_DIR="C:\Example\RabbitMQ\plugins;C:\Example\RabbitMQ\rabbitmq_server-3.7.9\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 following command on the host with a running RabbitMQ node:

rabbitmqctl eval 'application:get_env(rabbit, plugins_dir).'
# => {ok,"/usr/lib/rabbitmq/plugins:/usr/lib/rabbitmq/lib/rabbitmq_server-3.7.9/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.

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_shovel,rabbitmq_shovel_management].
Note that the trailing comma is significant.

Plugin Expansion (Extraction)

Not every plugin can be loaded from an archive .ez file. For this reason RabbitMQ will extracts 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.

Plugin Expansion (Extraction)

Not every plugin can be loaded from an archive .ez file. For this reason RabbitMQ will extracts 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

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 checking the name:

rabbitmq-plugins enable rabbitmq_managemenr                                                                                                                                                                                          70 ↵
# => Error:
# => {:plugins_not_found, [:rabbitmq_managemenr]}

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

Plugin directory can be located by executing the following command on the host with a running RabbitMQ node:

rabbitmqctl eval 'application:get_env(rabbit, plugins_dir).'
# => {ok,"/usr/lib/rabbitmq/plugins:/usr/lib/rabbitmq/lib/rabbitmq_server-3.7.9/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 [email protected]:
# =>  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 [email protected]
# =>  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:

rabbitmqctl environment | grep enabled_plugins                                                                                                                                                                                                  70 ↵
# =>       {enabled_plugins_file,
# =>         "/path/to/rabbitmq/etc/rabbitmq/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.

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

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

rabbitmq_amqp1_0
AMQP 1.0 protocol support. This plugin is several years old and is moderately mature. It may have certain limitations with its current architecture but most major AMQP 1.0 features should be in place.
rabbitmq_auth_backend_ldap
Authentication / authorisation plugin using an external LDAP server.
rabbitmq_auth_backend_http
Authentication / 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 hash exchange type.
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 heterogenous cluster this should be installed on the same nodes as rabbitmq_management.
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, you must install rabbitmq_management_agent on all of the nodes in the cluster. You can install the full management plugin on as many of the nodes as you want.
rabbitmq_mqtt
An adapter implementing the MQTT 3.1 protocol.
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. See the plugin README for this plugin. Only of use when using rabbitmq_shovel in conjunction with rabbitmq_management. In a heterogenous cluster this should be installed on the same nodes as rabbitmq_management.
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.

Discontinued

All plugins below have been discontinued. They don't (or won't) ship with the RabbitMQ distribution and are no longer maintained.

rabbitmq_management_visualiser
Broker topology visualiser plugin which is itself a plugin to the management plugin. Adds a Visualiser tab to the management web interface, which then flexibly and interactively displays channels, queues and exchanges, and the links between them.

Getting Help and Providing Feedback

If you have questions about the contents of this guide or any other topic related to RabbitMQ, don't hesitate to ask them on the RabbitMQ mailing list.

Help Us Improve the Docs <3

If you'd like to contribute an improvement to the site, its source is available on GitHub. Simply fork the repository and submit a pull request. Thank you!