• Features
• Get Started
• Support
• Community
• Docs
• Blog

Plugins

Overview

This guide covers

• Plugin support in RabbitMQ
• How to enable a plugin using CLI tools
• Plugin directories
• How to preconfigure plugins on a node at deployment time
• Troubleshooting of a number of common issues
• Plugin support tiers

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

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.

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):

# 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"

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.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.

Effects on rabbitmq-plugins

When plugin directories are overriden 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

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

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

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