Skip to content

Plugins ​

EMQX plugins allow users to extend core functionality or integrate custom logic into the broker using Erlang. This system is ideal for implementing features such as custom authentication, authorization, logging, metrics, or protocol translation.

This section introduces what plugins are and how they are developed, customized, and managed.

Starting from EMQX 6.3.0, the plugin framework is controlled by the plugins feature gate. The FULL preset enables it by default. If you use a custom EMQX_FEATURES list, include plugins to use plugin functionality. When plugins is disabled, EMQX does not start the plugin framework, EMQX Dashboard hides the plugin management UI, and the /api/v5/plugins/* and /api/v5/plugin_api/* routes are not registered. For more information, see Feature Gates.

What is a Plugin? ​

A plugin in EMQX is an Erlang/OTP application that runs inside EMQX nodes. Plugins interact with the EMQX core through hookpoints, which are predefined events such as client connection, message publish, authentication, and more.

To use a plugin in EMQX, first build it as a release package. Then choose how each node manages it:

  • Cluster-managed plugin: Install the .tar.gz package through the Dashboard, REST API, or CLI. EMQX distributes the package and manages its lifecycle across the cluster.
  • Node-pinned plugin: Starting from EMQX 6.2.4, extract the package on a specific node and list its name and version in node.pinned_plugins. The node runs the plugin independently of the cluster plugin configuration.

Upon startup, a plugin typically registers some of its functions as EMQX callbacks to modify or extend the behavior of EMQX. Plugins operate in isolation from EMQX core and from other plugins, ensuring they don’t interfere with each other. Cluster-managed plugins follow a defined lifecycle for installation, startup, shutdown, and removal. Node-pinned plugins are pre-deployed on specific nodes and can be started or stopped locally. To remove one, delete its entry from node.pinned_plugins, remove the plugin from the node's deployment artifact, and then restart the node.

Key Concepts ​

  • Hookpoints: Extension points in EMQX’s workflow where plugins can inject custom logic.
  • Callbacks: Functions in the plugin module that are registered to hookpoints.
  • Configuration schema: An optional Avro-based schema used to validate plugin configurations and render UI forms dynamically in the EMQX Dashboard.

Plugin Workflow Overview ​

  1. Develop the plugin using the official plugin template.
  2. Customize its logic to suit your use case (e.g., implement authentication).
  3. Build and package the plugin into a .tar.gz file using make rel.
  4. Install and start the plugin through the Dashboard, CLI, or API, or deploy and configure it as a node-pinned plugin.
  5. Configure and maintain the plugin according to the selected management mode.

Learn More ​

  • Develop EMQX Plugins: Learn how to build a plugin from scratch using the official template.
  • Customize Plugin Logic: Explore examples of how to implement hook callbacks for authentication, authorization, and more.
  • Manage Plugins: Understand how to install, configure, start/stop, and uninstall plugins across EMQX nodes and clusters.
  • Plugin Catalog: Browse ready-to-use plugins for data integration, governance, and access control.