--- description: Configure active-passive replicas to provide high availability for routed Cloudflare Mesh networks. title: High availability image: https://developers.cloudflare.com/mesh/features/high-availability/og.png?v=78b4108b2a8cfc72 --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/mesh/llms.txt > Use this file to discover all available pages before exploring further. # High availability Last updated Sep 16, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/mesh/features/high-availability/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) For production deployments, you can run multiple replicas of a Mesh node in active-passive mode. All replicas share the same node identity and advertise the same [routes](https://developers.cloudflare.com/mesh/features/routes/). If the active replica goes down, Cloudflare automatically promotes a standby replica. MASQUE required This feature requires that the [device profile](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/device-profiles/) of the Mesh node is configured to use [MASQUE](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/settings/#device-tunnel-protocol), the default protocol for the Cloudflare One Client. It does not work if the device profile uses WireGuard instead. ## When to use high availability High availability provides resilience for CIDR route prefixes advertised by a Mesh node. When the active replica disconnects, Cloudflare promotes a standby so that traffic to the advertised subnets continues to flow. This means HA is useful for nodes that have routes configured — nodes acting as subnet gateways for private networks behind them. If a node is only used for direct Mesh IP connectivity (no routes), HA has limited benefit because the node's Mesh IP is tied to the individual replica. High availability does not spread traffic across replicas, because only one replica is active at a time. To distribute traffic across several servers, health-check each server, or fail over between sites (for example, from a Cloudflare WAN site to a Mesh site), use a [private load balancer](https://developers.cloudflare.com/cloudflare-one/networks/load-balancing/). Within a virtual network, a CIDR can be assigned to only one tunnel or Mesh node, so endpoints behind different nodes need different IP addresses or different [virtual networks](https://developers.cloudflare.com/cloudflare-one/networks/virtual-networks/). ## How it works When you create a Mesh node with high availability enabled, Cloudflare generates a single token for that node. You install the Cloudflare One Client on multiple Linux hosts using this token. Each host registers as a replica of the same node. - All replicas advertise the same CIDR routes. - One replica is active at a time. The others are passive standby. - If the active replica disconnects, Cloudflare automatically promotes a passive replica. - Failover is handled by Cloudflare's network. ``` flowchart LR subgraph replicas["Mesh node: web-server"] R1["Replica 1
(active)"] R2["Replica 2
(standby)"] R3["Replica 3
(standby)"] end CF((Cloudflare)) <--> R1 CF -. failover .-> R2 CF -. failover .-> R3 client["Client device"] <--> CF ``` ## Create a node with high availability When you create a Mesh node through the dashboard, high availability is enabled by default. To create a new node: 1. In the Cloudflare dashboard, go to **Networking** > **Mesh**. [Go to **Mesh** ↗](https://dash.cloudflare.com/?to=/:account/mesh) 2. Select **Add participant** > **Add node**. 3. Follow the setup wizard. The node is created with HA enabled automatically. 4. Select an installation method and follow the displayed instructions. To create a node with high availability via the API, set `ha: true` in the request body: ```sh curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/warp_connector" \ -H "Authorization: Bearer {api_token}" \ -H "Content-Type: application/json" \ -d '{ "name": "web-server", "ha": true }' ``` The response includes a `token` field. Use this token to register replicas. ## Add replicas To add a replica to an existing high-availability node, install the Cloudflare One Client on a new Linux host and register it using the same node token. 1. In the Cloudflare dashboard, go to **Networking** > **Mesh**. [Go to **Mesh** ↗](https://dash.cloudflare.com/?to=/:account/mesh) 2. Select your Mesh node. 3. Select **Add a replica**. 4. A dialog shows the install commands and the node's token. 5. On a new Linux host, run the install commands shown in the dialog.
Installation commands IP forwarding is not required to reach the node by its Mesh IP. If the node will advertise CIDR routes, enable persistent forwarding before connecting it: ```sh printf 'net.ipv4.ip_forward = 1\nnet.ipv6.conf.all.forwarding = 1\nnet.ipv6.conf.all.accept_ra = 2\n' | sudo tee /etc/sysctl.d/99-zzz-cloudflare-warp-connector.conf && sudo sysctl --system ``` ```sh curl -fsSL https://pkg.cloudflareclient.com/pubkey.gpg | sudo gpg --yes --dearmor -o /usr/share/keyrings/cloudflare-warp-archive-keyring.gpg && echo "deb [signed-by=/usr/share/keyrings/cloudflare-warp-archive-keyring.gpg] https://pkg.cloudflareclient.com/ $(. /etc/os-release && echo $VERSION_CODENAME) main" | sudo tee /etc/apt/sources.list.d/cloudflare-client.list && sudo apt-get update -qq && sudo apt-get install -y -qq cloudflare-warp ``` ```sh sudo warp-cli --accept-tos connector new && sudo warp-cli --accept-tos connect ``` On RHEL 9 and later, enable the Extra Packages for Enterprise Linux (EPEL) repository before installing cloudflare-warp. EPEL provides dependencies required by the Cloudflare One Client UI. Turn on CodeReady Builder, then install the EPEL release package for your RHEL version: ```sh sudo subscription-manager repos --enable codeready-builder-for-rhel-$(rpm -E %rhel)-$(arch)-rpms && sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-$(rpm -E %rhel).noarch.rpm ``` On Rocky Linux, AlmaLinux, and other RHEL-compatible distributions, run sudo dnf config-manager --set-enabled crb && sudo dnf install -y epel-release instead. For details, refer to Run Mesh on Linux. Then install the package: ```sh curl -fsSL https://pkg.cloudflareclient.com/cloudflare-warp-ascii.repo | sudo tee /etc/yum.repos.d/cloudflare-warp.repo && sudo dnf install -y cloudflare-warp ``` ```sh sudo warp-cli --accept-tos connector new && sudo warp-cli --accept-tos connect ```
1. Retrieve the node's token: ```sh curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/warp_connector/{node_id}/token" \ -H "Authorization: Bearer {api_token}" ``` The response contains the token string. 2. Install the client and register on a new Linux host: IP forwarding is not required to reach the node by its Mesh IP. If the node will advertise [CIDR routes](https://developers.cloudflare.com/mesh/features/routes/), enable persistent forwarding before connecting it: ```sh printf 'net.ipv4.ip_forward = 1\nnet.ipv6.conf.all.forwarding = 1\nnet.ipv6.conf.all.accept_ra = 2\n' | sudo tee /etc/sysctl.d/99-zzz-cloudflare-warp-connector.conf && sudo sysctl --system ``` ```sh curl -fsSL https://pkg.cloudflareclient.com/pubkey.gpg | sudo gpg --yes --dearmor -o /usr/share/keyrings/cloudflare-warp-archive-keyring.gpg && echo "deb [signed-by=/usr/share/keyrings/cloudflare-warp-archive-keyring.gpg] https://pkg.cloudflareclient.com/ $(. /etc/os-release && echo $VERSION_CODENAME) main" | sudo tee /etc/apt/sources.list.d/cloudflare-client.list && sudo apt-get update -qq && sudo apt-get install -y -qq cloudflare-warp ``` ```sh sudo warp-cli --accept-tos connector new && sudo warp-cli --accept-tos connect ``` On RHEL 9 and later, enable the Extra Packages for Enterprise Linux (EPEL) repository before installing `cloudflare-warp`. EPEL provides dependencies required by the Cloudflare One Client UI. Turn on CodeReady Builder, then install the EPEL release package for your RHEL version: ```sh sudo subscription-manager repos --enable codeready-builder-for-rhel-$(rpm -E %rhel)-$(arch)-rpms && sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-$(rpm -E %rhel).noarch.rpm ``` On Rocky Linux, AlmaLinux, and other RHEL-compatible distributions, run `sudo dnf config-manager --set-enabled crb && sudo dnf install -y epel-release` instead. For details, refer to [Run Mesh on Linux](https://developers.cloudflare.com/mesh/guides/run-mesh-on-linux/#rhel). Then install the package: ```sh curl -fsSL https://pkg.cloudflareclient.com/cloudflare-warp-ascii.repo | sudo tee /etc/yum.repos.d/cloudflare-warp.repo && sudo dnf install -y cloudflare-warp ``` ```sh sudo warp-cli --accept-tos connector new && sudo warp-cli --accept-tos connect ``` The new replica will be in standby mode until the active replica disconnects. ## View replicas 1. In the Cloudflare dashboard, go to **Networking** > **Mesh**. [Go to **Mesh** ↗](https://dash.cloudflare.com/?to=/:account/mesh) 2. Select an HA-enabled node. HA nodes display an **HA** badge in the overview table. 3. The node detail page shows a tab for each replica. Each tab displays: - **Active** or **Passive** badge - Mesh IP (IPv4 and IPv6) - Edge data center - Origin IP - Platform, version, and device name - Connected since timestamp To view all replicas and their HA status, query the connections API endpoint: ```sh curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/warp_connector/{node_id}/connections" \ -H "Authorization: Bearer {api_token}" ``` The response includes each replica with its `ha_status` (`active` or `passive`), connection details, and the Cloudflare data center it is connected to: ```json { "success": true, "result": [ { "id": "bf69f118-238e-11f1-b113-ee02f3be4a5b", "conns": [ { "colo_name": "lhr16", "origin_ip": "34.105.147.200", "opened_at": "2026-03-19T12:25:47.400Z" } ], "run_at": "2026-03-19T12:25:47.400Z", "ha_status": "active" }, { "id": "e07272a6-21fc-11f1-8997-e28f01ba3991", "conns": [ { "colo_name": "lhr14", "origin_ip": "35.246.81.139", "opened_at": "2026-03-19T02:38:37.203Z" } ], "run_at": "2026-03-19T02:38:37.203Z", "ha_status": "passive" } ] } ``` ## Manual failover In addition to automatic failover when the active replica disconnects, you can manually promote a passive replica to active. 1. In the Cloudflare dashboard, go to **Networking** > **Mesh**. [Go to **Mesh** ↗](https://dash.cloudflare.com/?to=/:account/mesh) 2. Select an HA-enabled node. 3. Select the tab for the passive replica you want to promote. 4. Select **Promote to active**. 5. In the confirmation dialog, select **Promote to active** to confirm. Traffic reroutes to the promoted replica immediately. The previous active replica switches to passive standby. To manually trigger failover, send a `PUT` request with the `client_id` of the replica you want to promote: ```sh curl -X PUT "https://api.cloudflare.com/client/v4/accounts/{account_id}/warp_connector/{node_id}/failover" \ -H "Authorization: Bearer {api_token}" \ -H "Content-Type: application/json" \ -d '{ "client_id": "e07272a6-21fc-11f1-8997-e28f01ba3991" }' ``` Get the `client_id` from the [connections endpoint](#view-replicas). Use the `id` field of the replica you want to promote. ## Considerations ### Setup requirements - High availability is set at node creation time and cannot be changed afterward. - You must install the client on at least two hosts for failover to work. A single replica means no redundancy. - High availability requires that the Mesh node's [device profile](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/device-profiles/) is configured to use [MASQUE](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/settings/#device-tunnel-protocol), the default protocol for the Cloudflare One Client. It does not work if the device profile uses WireGuard instead. ### Network configuration - All replicas must be on the same subnet and have the same network routing configuration (Split Tunnels, static routes). - HA provides resilience for CIDR route prefixes. Nodes without routes do not benefit from HA failover. ### Failover behavior - Failover time depends on how quickly Cloudflare detects the active replica has disconnected (typically seconds). - Inbound traffic (from Mesh clients to the subnet) fails over automatically on Cloudflare's network. Cloudflare routes traffic to the newly promoted active replica. - Outbound traffic (from devices on the subnet through the Mesh node) does not fail over automatically. Your environment must detect that a different replica has been promoted to active and update routing tables to send traffic through the now-active host. There is no client-side failover for on-ramp traffic at this time. Was this helpful? YesNo ## On this page [![](https://developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/mesh/features/high-availability/#page","headline":"High availability","description":"Configure active-passive replicas to provide high availability for routed Cloudflare Mesh networks.","url":"https://developers.cloudflare.com/mesh/features/high-availability/","inLanguage":"en","image":"https://developers.cloudflare.com/mesh/features/high-availability/og.png?v=78b4108b2a8cfc72","dateModified":"2026-09-16","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"},"keywords":["Private networks"]} ```