This guide covers
and more.
Plugin development is covered in a separate guide.
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
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.
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.
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 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.
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.
If a 3rd party plugin was installed but cannot be found, the most likely reasons are
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
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.
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.
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.
The table below lists tier 1 (core) plugins that ship with RabbitMQ.
Plugin name | Description |
---|---|
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 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 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. |
All plugins below have been discontinued. They don't (or won't) ship with the RabbitMQ distribution and are no longer maintained.
If you have questions about the contents of this guide or any other topic related to RabbitMQ, don't hesitate to ask them using GitHub Discussions or our community Discord server.
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!