ℹ️

This page covers upgrading an existing Xray instance to RabbitMQ quorum queues. It does not apply to fresh installations — see the fresh installation documentation for new deployments.

Prerequisites

Before you upgrade to quorum mode:

1. An existing Xray non quorum deployment in any of the following modes:

   • Single-node Xray with bundled RabbitMQ
   • Multi-node Xray with bundled RabbitMQ in each node
   • Single-node Xray and Single-node RabbitMQ deployed independently on separate nodes (split mode)
   • Multi-node Xray and Multi-node RabbitMQ deployed independently on separate nodes (split mode)

2. Use Xray version 3.131.x or later — earlier versions don't support upgrading the bundled RabbitMQ to quorum mode. It is recommended to use the latest available version.

3. RabbitMQ version 3.11.x or higher — your existing deployment must already be on RabbitMQ 3.11.x or higher before enabling Quorum Queue or upgrading to RabbitMQ 4. If not, upgrade to the latest on-prem Xray version first, then proceed with the Quorum Queue migration.

   To check your RabbitMQ version, go to the management UI:

   Text

   http://<any rabbitmq node ip>:15672

   Default credentials are guest / JFXR_RABBITMQ_COOKIE, unless you have overridden them.

4. Ensure indexing queues are empty before starting — no active scans or Watches should be running during the migration.

5. (For linux archive based installs) If you are using a custom Xray user, add the following to /etc/security/limits.conf to set the open file descriptor limit (this is required for RabbitMQ to function properly)

   Text

     <custom user>    soft    nofile    100000
     <custom user>    hard    nofile    100000

⚠️

Quorum Queue Node Recommendations (Bundled RabbitMQ)

• Single-node: Supported.
• 3 or more nodes: Supported, but quorum will only grow across the first 3 RabbitMQ nodes. For better stability, splitting RabbitMQ onto dedicated VMs is recommended. See the Split mode architecture for details.
• 2-node deployments: Supported, but not recommended — a 2-node cluster is not fault-tolerant for quorum queues. See the 2-node VM to Quorum migration guide before proceeding.

📘

Awareness of the two-step migration — Migrating to RabbitMQ 4 + Quorum Queue is a two-run process: the first run optionally enables Quorum Queue on RabbitMQ 3, and the second run optionally upgrades to RabbitMQ 4. Both steps are irreversible once executed and rollback is not supported — plan your maintenance window accordingly.

The Big Picture

Upgrade Process

Follow the section that matches how your existing Xray instance was installed according to the installer type.

1. Helm

For Helm-based deployments, follow the Quorum Queue Enablement for Xray and Platform Helm Charts guide. It covers both chart types:

1. Xray standalone charts
2. Platform charts

2. Linux Archive/ RPM, DEB / Docker Compose

installv2.sh/configV2.sh (recommended installer script for version 3.131.x and later)

Use this script if you run installations manually, or if you previously used install.sh/config.sh and want to move to the supported path. If you're already on installV2.sh/configV2.sh, continue using it for future upgrades.

Follow the guide for your deployment type:

1. Migrate to Quorum using installV2.sh for linux archive
2. Migrate to Quorum using installV2.sh for RPM / DEB
3. Migrate to Quorum using installV2.sh for Docker Compose

❗️

Note: If your existing Xray instance is automated with the original install.sh script, follow the non-breaking upgrade instructions in Upgrade to Quorum Queue via install.sh ( legacy )

The legacy (script install.sh/config.sh) is retained only to avoid breaking existing automated deployments. For all new manual installs, use installV2.sh/configV2.sh.

Related Topics

• Xray Upgrade
• Upgrade to Quorum Queue via install.sh (legacy)
• Quorum Queue Enablement for Xray and Platform Helm Charts
• RabbitMQ HA in Xray Using Quorum Queues
• RabbitMQ Split for Xray