Hot Upgrade

Hot upgrade lets you apply a patch-version update to a running EMQX Enterprise node without stopping it. Connections stay alive throughout the upgrade; the node switches to the new release tree on its next restart.

Hot upgrade is supported for patch-version hops only (the third digit of the version number). For example, upgrading from 5.10.4 to 5.10.5 is supported, but upgrading from 5.10.x to 5.11.0 is not.

Hot upgrade is driven by the emqx_relup plugin. The plugin is installed from the Dashboard. All upgrade operations are performed through the emqx ctl relup CLI.

Important Notice

Back up data/, etc/, and log/ before running a hot upgrade. There is no in-place rollback once a hop is applied.

Prerequisites

• EMQX Enterprise is running on each node.
• You have shell access and can run emqx ctl commands on each node.
• The emqx_relup plugin version matches your current EMQX Enterprise version.
• The target version is listed as a supported hop by the plugin (verify in step 2).

Step 1: Install the emqx_relup Plugin

Install the plugin from the Dashboard following the Install Packages via Dashboard instructions. Plugin packages are published at https://packages.emqx.io/emqx-plugins/e<EMQX-VSN>/.

The plugin should appear with status running after installation.

Step 2: Confirm the Upgrade Path Is Supported

List the version hops the installed plugin knows about:

emqx ctl relup list-supported-paths

Confirm that your {from, target} version pair appears in the output before continuing.

Step 3: Prepare the Tarball and SHA256 Sidecar

Copy two files to each node. They can be placed anywhere readable by the EMQX process:

• emqx-enterprise-<TargetVsn>-<os>-<arch>.tar.gz: The EMQX Enterprise target release tarball.
• emqx-enterprise-<TargetVsn>-<os>-<arch>.tar.gz.sha256: The SHA256 digest of the tarball. Both the bare digest format and the sha256sum output format (<digest> <filename>) are accepted.

scp emqx-enterprise-<TargetVsn>-<os>-<arch>.tar.gz      node1:/opt/upgrade/
scp emqx-enterprise-<TargetVsn>-<os>-<arch>.tar.gz.sha256 node1:/opt/upgrade/

The .sha256 sidecar must sit next to the tarball and share the same base name with a .sha256 extension.

Step 4: Run the Upgrade

On each node, trigger the upgrade by pointing relup upgrade at the tarball:

emqx ctl relup upgrade /opt/upgrade/emqx-enterprise-<TargetVsn>-<os>-<arch>.tar.gz

The upgrade handler performs the following steps:

1. Verifies the SHA256 digest and refuses to proceed if there is a mismatch.
2. Extracts the tarball and reads the target version from releases/emqx_vars.
3. Deploys only the runtime subdirectories (bin/, erts-*/, lib/, releases/) to <RootDir>/relup/<TargetVsn>/. Config, data, logs, and plugins remain at the original install root.
4. Applies the matching code-change instructions from the plugin's .relup catalog.
5. Runs post-upgrade callbacks.
6. Writes <RootDir>/relup/current with the target version string.

Rolling out across a cluster is the operator's responsibility. Upgrade nodes one at a time and verify each before proceeding.

Step 5: Verify the Node

After the upgrade command returns, confirm the node is healthy:

# Check the node is running
emqx ctl status

# Confirm the version marker was written
cat <RootDir>/relup/current

# Check upgrade status and history
emqx ctl relup status
emqx ctl relup logs

relup/current should contain the target version string, and emqx ctl status should report the node running.

Step 6: Restart Into the New Release

The code-change upgrade takes effect in the running VM immediately. To fully switch to the new ERTS runtime and binaries, restart the node:

emqx restart

On restart, the bin/emqx wrapper detects <RootDir>/relup/current and starts from <RootDir>/relup/<TargetVsn>/ instead. The original <RootDir> remains the authority for data/, etc/, log/, and plugins/.

Step 7: Clean Up

Once the entire cluster is running the target version, remove the staging files:

rm /opt/upgrade/emqx-enterprise-<TargetVsn>-<os>-<arch>.tar.gz
rm /opt/upgrade/emqx-enterprise-<TargetVsn>-<os>-<arch>.tar.gz.sha256

The plugin does not track the source path, so no cleanup is needed inside the plugin itself.

Rollback

There is no in-place rollback for an applied hop. Code changes run against the live VM, and post-upgrade callbacks may have mutated data on disk; reversing those is not supported.

Two limited recovery options are available:

• Before the next restart: If the upgraded code is misbehaving but disk state is still compatible with the old release, delete the version marker and restart into the old tree:

  rm <RootDir>/relup/current
  # optionally: rm -rf <RootDir>/relup/<TargetVsn>/
  emqx restart

  This recovers only the boot path. Live state changes made by the upgrade are already in effect.

• Full restore: Restore data/ from the pre-upgrade backup and reinstall the old EMQX release.

Plan your upgrade window with these limitations in mind.

CLI Reference

Command	Description
emqx ctl relup upgrade <TarballPath>	Apply the upgrade hop from the given tarball.
emqx ctl relup list-supported-paths	List supported {from, target} version hops in the plugin catalog.
emqx ctl relup status	Show the current upgrade state: idle, in-progress, or hot-upgraded to <vsn>; pending on restart to boot from the new version.
emqx ctl relup logs	Print this node's upgrade history from the persistent log table.
emqx ctl relup logs-clear	Wipe this node's upgrade log table.