--- title: Cloudflare Tunnel description: Securely connect your origin servers, APIs, and services to Cloudflare with post-quantum encrypted tunnels — no public IPs required. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/index.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Cloudflare Tunnel Securely connect your origin servers, APIs, and services to Cloudflare with post-quantum encrypted tunnels — no public IPs required. Available on all plans Cloudflare Tunnel connects your infrastructure to Cloudflare through an outbound-only, [post-quantum encrypted](https://developers.cloudflare.com/ssl/post-quantum-cryptography/) connection. Instead of exposing a public IP, you install a lightweight daemon called `cloudflared` on your server. It creates a persistent tunnel to Cloudflare's global network, so all traffic to your origins flows through Cloudflare — where CDN caching, WAF, Bot Management, and DDoS protection are applied automatically. No open inbound ports. No public IPs. No attack surface. ## How it works 1. Install `cloudflared` on your server or network. 2. `cloudflared` establishes outbound, post-quantum encrypted connections to Cloudflare — no inbound ports or firewall changes required. 3. Map public hostnames to local services (for example, `app.example.com` to `http://localhost:8080`). 4. Traffic flows through Cloudflare's network to your origin, with full CDN and security applied. Each tunnel maintains four long-lived connections to two Cloudflare data centers for built-in redundancy. You can run multiple `cloudflared` [replicas](https://developers.cloudflare.com/tunnel/configuration/#replicas-and-high-availability) for additional high availability. ![How an HTTP request reaches an origin connected with Cloudflare Tunnel](https://developers.cloudflare.com/_astro/handshake.eh3a-Ml1_26dKUX.webp) ## Use cases * **Secure origin connectivity** — Eliminate public origin IPs. All traffic flows through Cloudflare with CDN, WAF, and DDoS protection applied. * **Public ingress routing** — Publish internal applications to the internet by mapping public hostnames to local services. Supports HTTP, HTTPS, TCP, SSH, RDP, and [more](https://developers.cloudflare.com/tunnel/routing/#supported-protocols). * **Workers VPC** — Enable [Cloudflare Workers](https://developers.cloudflare.com/workers-vpc/) to securely access private databases, APIs, and services through your tunnel. * **Load Balancing** — Use tunnels as origin endpoints in [Cloudflare Load Balancer](https://developers.cloudflare.com/load-balancing/) pools for high availability and intelligent traffic steering. Looking for Zero Trust and private networking? For VPN replacement, private network access, and network traffic filtering, refer to the [Cloudflare One Tunnel documentation](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/). ## Get started [Create your first tunnel](https://developers.cloudflare.com/tunnel/setup/) Set up a tunnel in under 5 minutes using the dashboard or API. [Routing](https://developers.cloudflare.com/tunnel/routing/) DNS records, protocols, and load balancing for published applications. [Integrations](https://developers.cloudflare.com/tunnel/integrations/) Cloudflare One, Workers VPC, Load Balancing, Access, and more. [Configuration](https://developers.cloudflare.com/tunnel/configuration/) Replicas, firewall rules, tokens, and runtime parameters. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}}]} ``` --- --- title: Setup description: Create your first Cloudflare Tunnel and publish an application in under 5 minutes. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/setup.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Setup Create a Cloudflare Tunnel and publish your first application in under 5 minutes. ## Prerequisites * A [Cloudflare account ↗](https://dash.cloudflare.com/sign-up) * A [domain on Cloudflare](https://developers.cloudflare.com/fundamentals/manage-domains/add-site/) (required to publish applications) * A server or VM with internet access where you will install `cloudflared` Tip If your server is behind a restrictive firewall, verify it can reach Cloudflare on port `7844` before proceeding. Refer to [Connection errors](https://developers.cloudflare.com/tunnel/troubleshooting/#connection-errors). ## Create a tunnel To create a new Cloudflare Tunnel: * [ Dashboard ](#tab-panel-6704) * [ API ](#tab-panel-6705) 1. In the [Cloudflare dashboard ↗](https://dash.cloudflare.com/), go to **Networking** \> **Tunnels**. [ Go to **Tunnels** ](https://dash.cloudflare.com/?to=/:account/tunnels) 2. Select **Create Tunnel**. 3. Enter a name for your tunnel (for example, `production-web` or `staging-api`). 4. Select **Create Tunnel**. 5. Under **Setup Environment**, select the operating system and architecture of your server. 6. Copy the install commands shown under **Install and Run** and run them in a terminal on your server. 7. Once the tunnel connects, select **Continue**. Your tunnel should appear on the **Tunnels** page with a `Healthy` [status](https://developers.cloudflare.com/tunnel/monitoring/#tunnel-health). 1. [Create an API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) with the following permissions: | Type | Item | Permission | | ------- | ----------------- | ---------- | | Account | Cloudflare Tunnel | Edit | | Zone | DNS | Edit | 2. Create a tunnel: Required API token permissions At least one of the following [token permissions](https://developers.cloudflare.com/fundamentals/api/reference/permissions/)is required: * `Cloudflare One Connectors Write` * `Cloudflare One Connector: cloudflared Write` * `Cloudflare Tunnel Write` Create a Cloudflare Tunnel ``` curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/cfd_tunnel" \ --request POST \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "name": "api-tunnel", "config_src": "cloudflare" }' ``` 3. Copy the `id` and `token` values from the response. You will need them to configure and run the tunnel. ## Publish an application To make an application accessible from the Internet, add a published application route to your tunnel. The tunnel route maps a public hostname to a local service. * [ Dashboard ](#tab-panel-6706) * [ API ](#tab-panel-6707) 1. In the [Cloudflare dashboard ↗](https://dash.cloudflare.com/), go to **Networking** \> **Tunnels** and select your tunnel. [ Go to **Tunnels** ](https://dash.cloudflare.com/?to=/:account/tunnels) 2. Under **Routes**, select **Add route**. 3. Select **Published application**. 4. Under **Hostname**, enter a subdomain and select a domain from the drop-down menu. 5. For **Service URL**, enter the local address and port of your application. For example, if your web server runs on the same machine as `cloudflared`: * HTTP on port `80`: `http://localhost:80` * HTTPS on port `443`: `https://localhost:443` If your web server runs on a different machine: `http://192.0.2.1:80` 6. Select **Add route**. 1. Configure your tunnel's ingress rules: Required API token permissions At least one of the following [token permissions](https://developers.cloudflare.com/fundamentals/api/reference/permissions/)is required: * `Cloudflare One Connectors Write` * `Cloudflare One Connector: cloudflared Write` * `Cloudflare Tunnel Write` Put configuration ``` curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/cfd_tunnel/$TUNNEL_ID/configurations" \ --request PUT \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "config": { "ingress": [ { "hostname": "app.example.com", "service": "http://localhost:80", "originRequest": {} }, { "service": "http_status:404" } ] } }' ``` Your ingress rules must include a catch-all rule at the end. In this example, `cloudflared` will respond with a 404 status code when the request does not match any hostname. 2. Create a DNS record for your application: Required API token permissions At least one of the following [token permissions](https://developers.cloudflare.com/fundamentals/api/reference/permissions/)is required: * `DNS Write` Create DNS Record ``` curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records" \ --request POST \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "type": "CNAME", "proxied": true, "name": "app.example.com", "content": ".cfargotunnel.com" }' ``` 3. Install `cloudflared` on your server and run the tunnel using the `token` obtained in [Create a tunnel](https://developers.cloudflare.com/tunnel/setup/#create-a-tunnel): * [ Linux ](#tab-panel-6700) * [ Windows ](#tab-panel-6701) * [ macOS ](#tab-panel-6702) * [ Docker ](#tab-panel-6703) 1. [Download and install ↗](https://pkg.cloudflare.com/index.html) `cloudflared`. 2. Run the following command: Terminal window ``` sudo cloudflared service install ``` 1. [Download and install](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/#windows) `cloudflared`. 2. Open Command Prompt as administrator. 3. Run the following command: ``` cloudflared.exe service install ``` 1. [Download and install](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/#macos) `cloudflared`. 2. Open a terminal window and run the following command: Terminal window ``` sudo cloudflared service install ``` 1. Open a terminal window. 2. Run the following command: Terminal window ``` docker run cloudflare/cloudflared:latest tunnel --no-autoupdate run --token ``` Your application is now live at the hostname you configured. Cloudflare automatically proxies traffic through its network, applying CDN caching, WAF, and DDoS protection. Note Non-HTTP services (SSH, TCP, RDP) require `cloudflared` on the client side. Refer to the [protocols reference](https://developers.cloudflare.com/tunnel/routing/#supported-protocols) for details. ## Quick tunnels (development) For local development, you can instantly expose localhost without a Cloudflare account: Terminal window ``` cloudflared tunnel --url http://localhost:8080 ``` This generates a random `trycloudflare.com` subdomain that proxies traffic to your local server. Quick tunnels are for testing only — they have a 200 concurrent request limit and do not support Server-Sent Events (SSE). For production use, [create a tunnel](#create-a-tunnel) instead. ## Next steps * [Routing](https://developers.cloudflare.com/tunnel/routing/) — Configure DNS records, load balancers, and protocol support. * [Configuration](https://developers.cloudflare.com/tunnel/configuration/) — Deploy replicas, manage tokens, and tune performance. * [Deployment guides](https://developers.cloudflare.com/tunnel/deployment-guides/) — Deploy on Kubernetes, AWS, GCP, Terraform, and more. * [Troubleshooting](https://developers.cloudflare.com/tunnel/troubleshooting/) — Resolve common errors and connectivity issues. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/setup/","name":"Setup"}}]} ``` --- --- title: Routing description: Cloudflare Tunnel routes traffic from Cloudflare's network to services running behind cloudflared. When you publish an application, you map a public hostname to a local service — for example, app.example.com to http://localhost:8080 — and Cloudflare applies CDN caching, WAF, and DDoS protection before forwarding the request to your origin. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/routing.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Routing Cloudflare Tunnel routes traffic from Cloudflare's network to services running behind `cloudflared`. When you [publish an application](https://developers.cloudflare.com/tunnel/setup/#publish-an-application), you map a public hostname to a local service — for example, `app.example.com` to `http://localhost:8080` — and Cloudflare applies CDN caching, WAF, and DDoS protection before forwarding the request to your origin. ![Multiple outbound connections from cloudflared are spread across Cloudflare data centers for reliability and failover.](https://developers.cloudflare.com/_astro/cf1-ref-arch-7.Dk3BnKM8_UmiKN.svg) ## Published applications A published application is a hostname-to-service mapping defined in your tunnel configuration. Each mapping tells `cloudflared` which local service should receive traffic for a given public hostname. You can publish multiple applications on a single tunnel. For each application, specify: * **Public hostname** — The domain or subdomain that users visit (for example, `app.example.com`). * **Service** — The local address or socket where the application is running (for example, `http://localhost:8080`). When you add a route through the dashboard, Cloudflare automatically creates a DNS record pointing the hostname to your tunnel subdomain (`.cfargotunnel.com`). ## Supported protocols The table below lists the service types you can route to a public hostname. Non-HTTP services require [installing cloudflared on the client](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/non-http/cloudflared-authentication/) for end users to connect. | Service type | Description | Example service value | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- | | HTTP | Proxies incoming HTTPS requests to your local web service over HTTP. | http://localhost:8000 | | HTTPS | Proxies incoming HTTPS requests directly to your local web service. You can [disable TLS verification](https://developers.cloudflare.com/tunnel/configuration/#notlsverify) for self-signed certificates. | https://localhost:8000 | | UNIX | Same as HTTP, but uses a Unix socket. | unix:/home/production/echo.sock | | UNIX + TLS | Same as HTTPS, but uses a Unix socket. | unix+tls:/home/production/echo.sock | | TCP | Streams TCP over a WebSocket connection. End users run cloudflared access tcp to [connect](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/non-http/cloudflared-authentication/arbitrary-tcp/). For long-lived connections, use [Client-to-Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/cloudflared/) instead. | tcp://localhost:2222 | | SSH | Streams SSH over a WebSocket connection. End users run cloudflared access ssh to [connect](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/use-cases/ssh/ssh-cloudflared-authentication/). For long-lived connections, use [Client-to-Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/use-cases/ssh/ssh-infrastructure-access/) instead. | ssh://localhost:22 | | RDP | Streams RDP over a WebSocket connection. For more information, refer to [Connect to RDP with client-side cloudflared](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/use-cases/rdp/rdp-cloudflared-authentication/). | rdp://localhost:3389 | | SMB | Streams SMB over a WebSocket connection. For more information, refer to [Connect to SMB with client-side cloudflared](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/use-cases/smb/#connect-to-smb-server-with-cloudflared-access). | smb://localhost:445 | | HTTP\_STATUS | Responds to all requests with a fixed HTTP status code. | http\_status:404 | | BASTION | Allows cloudflared to act as a jump host, providing access to any local address. | bastion | | HELLO\_WORLD | Test server for validating your Cloudflare Tunnel connection (for [locally managed tunnels](https://developers.cloudflare.com/tunnel/other-tunnel-types/local-management/configuration-file/#file-structure-for-published-applications) only). | hello\_world | ## DNS records When you create a tunnel, Cloudflare generates a subdomain at `.cfargotunnel.com`. You point a CNAME record at this subdomain to route traffic from your hostname to the tunnel. The `cfargotunnel.com` subdomain only proxies traffic for DNS records in the same Cloudflare account. If someone discovers your tunnel UUID, they cannot create a DNS record in another account to proxy traffic through it. ### Create a DNS record To create a DNS record for a Cloudflare Tunnel: * [ Dashboard ](#tab-panel-6698) * [ CLI ](#tab-panel-6699) 1. Log in to the [Cloudflare dashboard ↗](https://dash.cloudflare.com/) and go to **DNS Records** for your domain. [ Go to **Records** ](https://dash.cloudflare.com/?to=/:account/:zone/dns/records) 2. Select **Add record**. 3. Enter the following values: * **Type**: _CNAME_ * **Name**: Subdomain of your application * **Target**: `.cfargotunnel.com` 4. Select **Save**. ![Example of fields completed to create a new CNAME record.](https://developers.cloudflare.com/_astro/dns-record.B25etJTI_Z1p13KV.webp) For locally-managed tunnels, run the following command to create a CNAME record pointing to your tunnel subdomain: Terminal window ``` cloudflared tunnel route dns www.app.com ``` This creates a CNAME record but does not proxy traffic unless the tunnel is running. Note To create DNS records using `cloudflared`, the [cert.pem](https://developers.cloudflare.com/tunnel/other-tunnel-types/local-management/local-tunnel-terms/#certpem) file must be installed on your system. The DNS record and the tunnel are independent. You can create DNS records that point to a tunnel that is not running. If a tunnel stops, the DNS record is not deleted — visitors will see a `1016` error. You can also create multiple DNS records pointing to the same tunnel subdomain. If you route traffic from multiple hostnames to multiple services, create a CNAME entry for each hostname. All entries share the same target. ## Load balancing Use a [public load balancer](https://developers.cloudflare.com/load-balancing/load-balancers/) to distribute traffic across servers running your published applications. This provides health-check-based failover and intelligent traffic steering across regions. graph LR accTitle: Load balancing traffic to applications behind Cloudflare Tunnel A[Internet] --> C{Cloudflare
Load Balancer} C -- Tunnel 1 --> cf1 C -- Tunnel 2 --> cf2 subgraph F[Data center 2] cf2[cloudflared] S3[App server] S4[App server] cf2-->S3 cf2-->S4 end subgraph E[Data center 1] cf1[cloudflared] S1[App server] S2[App server] cf1-->S1 cf1-->S2 end ### Replicas versus load balancers Running multiple `cloudflared` [replicas](https://developers.cloudflare.com/tunnel/configuration/#replicas-and-high-availability) on the same tunnel UUID provides basic redundancy — if one host fails, other replicas continue serving traffic. However, the load balancer treats all replicas of the same tunnel UUID as a single endpoint. For granular traffic steering and [session affinity](https://developers.cloudflare.com/load-balancing/understand-basics/session-affinity/), connect each host using a different tunnel UUID so the load balancer can address them independently. ### Add a tunnel to a load balancer pool Prerequisites A Cloudflare Tunnel with at least one [published application route](https://developers.cloudflare.com/tunnel/setup/#publish-an-application). To create a load balancer for Cloudflare Tunnel published applications: 1. In the Cloudflare dashboard, go to the **Load Balancing** page. [ Go to **Load Balancing** ](https://dash.cloudflare.com/?to=/:account/load-balancing) 2. Select **Create load balancer**, then select **Public load balancer**. 3. Under **Select website**, select the domain of your published application route. 4. On the **Hostname** page, enter a hostname for the load balancer (for example, `lb.example.com`). 5. On the **Pools** page, select **Create a pool** and enter a descriptive name. 6. Add a tunnel endpoint with the following values: * **Endpoint Name**: Name of the server running the application * **Endpoint Address**: `.cfargotunnel.com` (find the Tunnel ID in the \[Cloudflare dashboard\](https://dash.cloudflare.com/) under \*\*Networking\*\* > \*\*Tunnels\*\*) * **Header value**: Hostname of your published application route (for example, `app.example.com`) * **Weight**: `1` (if only one endpoint) Note A single origin pool cannot reference the same tunnel UUID twice. 7. Choose a **Fallback pool**. Refer to [traffic steering policies](https://developers.cloudflare.com/load-balancing/understand-basics/traffic-steering/steering-policies/) for routing options. 8. (Recommended) On the **Monitors** page, attach a monitor to the endpoint. For an HTTP or HTTPS application, create an HTTPS monitor: * **Type**: _HTTPS_ * **Path**: `/` * **Port**: `443` * **Expected Code(s)**: `200` * **Header Name**: `Host` * **Value**: `app.example.com` 9. Save and deploy the load balancer. To test, access your application using the load balancer hostname (`lb.example.com`). Monitor TCP tunnel origins TCP monitors are not supported for tunnel endpoints. Instead, create a health check endpoint on the `cloudflared` host and use an HTTPS monitor. For example, you can use `cloudflared` to return a fixed HTTP status response: 1. [Add a published application route](https://developers.cloudflare.com/tunnel/setup/#publish-an-application) for the health check: * **Hostname**: `health-check.example.com` * **Service Type**: _HTTP\_STATUS_ * **HTTP Status Code**: `200` 2. [Create a monitor](https://developers.cloudflare.com/load-balancing/monitors/create-monitor/) with these settings: * **Type**: _HTTPS_ * **Path**: `/` * **Port**: `443` * **Expected Code(s)**: `200` * **Header Name**: `Host` * **Value**: `health-check.example.com` This monitor verifies that `cloudflared` is reachable. It does not check whether the upstream service is accepting requests. Local connection preference If you notice traffic imbalances across endpoints in different locations, you may need to adjust your load balancer configuration. Cloudflare uses [Anycast routing ↗](https://www.cloudflare.com/learning/cdn/glossary/anycast-network/) to direct end user requests to the nearest data center. `cloudflared` prefers to serve requests using connections in the same data center, which can affect how traffic is distributed across endpoints. If you run [cloudflared replicas](https://developers.cloudflare.com/tunnel/configuration/#replicas-and-high-availability) on the same tunnel UUID, consider switching to separate tunnels for more granular control over [traffic steering](https://developers.cloudflare.com/load-balancing/understand-basics/traffic-steering/). ## Cloudflare settings Published applications inherit the Cloudflare settings for their hostname, including [cache rules](https://developers.cloudflare.com/cache/how-to/cache-rules/), [WAF rules](https://developers.cloudflare.com/waf/), and other [Rules](https://developers.cloudflare.com/rules/) configurations. You can change these settings for each hostname in the [Cloudflare dashboard ↗](https://dash.cloudflare.com/). If you use a load balancer, settings are applied to the load balancer hostname instead. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/routing/","name":"Routing"}}]} ``` --- --- title: Configuration description: This page covers the most common configuration options for cloudflared tunnels, including high availability, firewall rules, and runtime parameters. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/configuration.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Configuration This page covers the most common configuration options for `cloudflared` tunnels, including high availability, firewall rules, and runtime parameters. ## Replicas and high availability When you run a tunnel, `cloudflared` establishes four outbound-only, [post-quantum encrypted](https://developers.cloudflare.com/ssl/post-quantum-cryptography/) connections to at least two distinct Cloudflare data centers. If any connection, server, or data center goes offline, your resources remain available. A replica is an additional `cloudflared` instance that points to the same tunnel. Each replica creates four new connections, providing additional ingress points to your origin. You can run up to 25 replicas (100 connections) per tunnel. Traffic routes to the geographically closest replica. graph LR C((Cloudflare)) subgraph E[Your network] cf1["cloudflared
(Replica for tunnel-01)"] cf2["cloudflared
(Replica for tunnel-01)"] S1[Application] cf1-->S1 cf2-->S1 end C -- "Connections x 4
"--> cf1 C --> cf1 C --> cf1 C --> cf1 C -- Connections x 4--> cf2 C --> cf2 C --> cf2 C --> cf2 ### Deploy a replica * [ Dashboard ](#tab-panel-6680) * [ CLI ](#tab-panel-6681) To deploy a replica for a remotely-managed tunnel: 1. In the [Cloudflare dashboard ↗](https://dash.cloudflare.com/), go to **Networking** \> **Tunnels**. [ Go to **Tunnels** ](https://dash.cloudflare.com/?to=/:account/tunnels) 2. Select your tunnel. 3. Select **Add a replica**. 4. Select the operating system of the host where you want to deploy a replica. 5. Copy the installation command and run it on the host. To deploy a replica for a [locally-managed tunnel](https://developers.cloudflare.com/tunnel/advanced/local-management/), run `cloudflared tunnel run ` on an additional host using the same [tunnel credentials](https://developers.cloudflare.com/tunnel/advanced/local-management/tunnel-permissions/). Note For intelligent traffic steering, failover logic, or health alerts, use [Cloudflare Load Balancing](https://developers.cloudflare.com/tunnel/routing/#load-balancing) instead of replicas. ## Firewall rules `cloudflared` connects outbound to Cloudflare on port `7844`. Your firewall must allow egress to the following destinations. Block all ingress traffic for a positive security model — only the services in your tunnel configuration will be exposed. ### Required ports #### `region1.v2.argotunnel.com` | IPv4 | IPv6 | Port | Protocols | | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | -------------------- | | 198.41.192.167 198.41.192.67 198.41.192.57 198.41.192.107 198.41.192.27 198.41.192.7 198.41.192.227 198.41.192.47 198.41.192.37 198.41.192.77 | 2606:4700:a0::1 2606:4700:a0::2 2606:4700:a0::3 2606:4700:a0::4 2606:4700:a0::5 2606:4700:a0::6 2606:4700:a0::7 2606:4700:a0::8 2606:4700:a0::9 2606:4700:a0::10 | 7844 | TCP/UDP (http2/quic) | #### `region2.v2.argotunnel.com` | IPv4 | IPv6 | Port | Protocols | | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | -------------------- | | 198.41.200.13 198.41.200.193 198.41.200.33 198.41.200.233 198.41.200.53 198.41.200.63 198.41.200.113 198.41.200.73 198.41.200.43 198.41.200.23 | 2606:4700:a8::1 2606:4700:a8::2 2606:4700:a8::3 2606:4700:a8::4 2606:4700:a8::5 2606:4700:a8::6 2606:4700:a8::7 2606:4700:a8::8 2606:4700:a8::9 2606:4700:a8::10 | 7844 | TCP/UDP (http2/quic) | US region IPs When using the [\--region us](#region) flag, ensure your firewall allows outbound connections to these US-region destinations on port `7844` (TCP/UDP). #### `us-region1.v2.argotunnel.com` | IPv4 | IPv6 | Port | Protocol | | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | -------------------- | | 198.41.218.1 198.41.218.2 198.41.218.3 198.41.218.4 198.41.218.5 198.41.218.6 198.41.218.7 198.41.218.8 198.41.218.9 198.41.218.10 | 2606:4700:a1::1 2606:4700:a1::2 2606:4700:a1::3 2606:4700:a1::4 2606:4700:a1::5 2606:4700:a1::6 2606:4700:a1::7 2606:4700:a1::8 2606:4700:a1::9 2606:4700:a1::10 | 7844 | TCP/UDP (http2/quic) | #### `us-region2.v2.argotunnel.com` | IPv4 | IPv6 | Port | Protocol | | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | -------------------- | | 198.41.219.1 198.41.219.2 198.41.219.3 198.41.219.4 198.41.219.5 198.41.219.6 198.41.219.7 198.41.219.8 198.41.219.9 198.41.219.10 | 2606:4700:a9::1 2606:4700:a9::2 2606:4700:a9::3 2606:4700:a9::4 2606:4700:a9::5 2606:4700:a9::6 2606:4700:a9::7 2606:4700:a9::8 2606:4700:a9::9 2606:4700:a9::10 | 7844 | TCP/UDP (http2/quic) | FedRAMP High IPs When deploying `cloudflared` in a [FedRAMP High ↗](https://www.cloudflare.com/cloudflare-for-government/) environment, `cloudflared` automatically routes to FedRAMP data centers based on the [tunnel token](https://developers.cloudflare.com/tunnel/advanced/tunnel-tokens/). Ensure your firewall allows outbound connections to these FedRAMP-specific destinations on port `7844` (TCP/UDP). #### `fed-region1.v2.argotunnel.com` | IPv4 | IPv6 | Port | Protocols | | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | -------------------- | | 162.159.234.1 162.159.234.2 162.159.234.3 162.159.234.4 162.159.234.5 162.159.234.6 162.159.234.7 162.159.234.8 162.159.234.9 162.159.234.10 | 2a06:98c1:4d::1 2a06:98c1:4d::2 2a06:98c1:4d::3 2a06:98c1:4d::4 2a06:98c1:4d::5 2a06:98c1:4d::6 2a06:98c1:4d::7 2a06:98c1:4d::8 2a06:98c1:4d::9 2a06:98c1:4d::10 | 7844 | TCP/UDP (http2/quic) | #### `fed-region2.v2.argotunnel.com` | IPv4 | IPv6 | Port | Protocols | | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | -------------------- | | 172.64.234.1 172.64.234.2 172.64.234.3 172.64.234.4 172.64.234.5 172.64.234.6 172.64.234.7 172.64.234.8 172.64.234.9 172.64.234.10 | 2606:4700:f6::1 2606:4700:f6::2 2606:4700:f6::3 2606:4700:f6::4 2606:4700:f6::5 2606:4700:f6::6 2606:4700:f6::7 2606:4700:f6::8 2606:4700:f6::9 2606:4700:f6::10 | 7844 | TCP/UDP (http2/quic) | SNI-enforcing firewalls If your firewall enforces Server Name Indication (SNI), also allow these hostnames on port `7844`: | Hostname | Port | Protocols | | --------------------------------------- | ---- | -------------------- | | \_v2-origintunneld.\_tcp.argotunnel.com | 7844 | TCP (http2) | | cftunnel.com | 7844 | TCP/UDP (http2/quic) | | h2.cftunnel.com | 7844 | TCP (http2) | | quic.cftunnel.com | 7844 | UDP (quic) | Optional port 443 destinations Opening port `443` enables optional features like software auto-updates and Access JWT validation. `cloudflared` runs correctly without these connections. | Destination | Purpose | | ------------------------------------- | ----------------------------------------- | | api.cloudflare.com | Software update checks | | update.argotunnel.com | Software update checks | | github.com | Download latest release | | .cloudflareaccess.com | Access JWT validation (if Access enabled) | | pqtunnels.cloudflareresearch.com | Post-quantum error reporting | | cfd-features.argotunnel.com (DNS TXT) | UDP datagram version negotiation | To verify your firewall allows tunnel traffic, refer to [Connection errors](https://developers.cloudflare.com/tunnel/troubleshooting/#connection-errors). ## Run parameters These flags apply to the `cloudflared tunnel run` command. They control how the tunnel runs on your operating system. The most commonly used parameters: | Parameter | Default | Description | | ----------------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------- | | [\--loglevel](https://developers.cloudflare.com/tunnel/advanced/run-parameters/#loglevel) | info | Log verbosity: debug, info, warn, error, fatal | | [\--logfile](https://developers.cloudflare.com/tunnel/advanced/run-parameters/#logfile) | stdout | Path to write log output | | [\--metrics](https://developers.cloudflare.com/tunnel/advanced/run-parameters/#metrics) | 127.0.0.1:20241–20245 | Prometheus metrics endpoint address (first available port in range) | | [\--protocol](https://developers.cloudflare.com/tunnel/advanced/run-parameters/#protocol) | auto | Connection protocol: auto, quic, http2 | | [\--region](https://developers.cloudflare.com/tunnel/advanced/run-parameters/#region) | global | Route through US-only data centers with us | | [\--token](https://developers.cloudflare.com/tunnel/advanced/run-parameters/#token) | — | Tunnel token (remotely-managed tunnels) | The following example shows how to manually run a tunnel with configuration flags: Terminal window ``` cloudflared tunnel --loglevel info --logfile /var/log/cloudflared/cloudflared.log run --token ``` For the complete list of run parameters and instructions on how to add them to a tunnel service, refer to [Run parameters](https://developers.cloudflare.com/tunnel/advanced/run-parameters/). ## Origin parameters Origin configuration parameters control how `cloudflared` proxies traffic to your origin server. The most commonly used parameters: | Parameter | Default | Description | | --------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------- | | [originServerName](https://developers.cloudflare.com/tunnel/advanced/origin-parameters/#originservername) | "" | Hostname expected from origin certificate | | [noTLSVerify](https://developers.cloudflare.com/tunnel/advanced/origin-parameters/#notlsverify) | false | Disable TLS certificate verification | | [httpHostHeader](https://developers.cloudflare.com/tunnel/advanced/origin-parameters/#httphostheader) | "" | Override HTTP Host header | | [connectTimeout](https://developers.cloudflare.com/tunnel/advanced/origin-parameters/#connecttimeout) | 30s | TCP connection timeout to origin | For the complete list of origin parameters and setup instructions, refer to [Origin parameters](https://developers.cloudflare.com/tunnel/advanced/origin-parameters/). ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/configuration/","name":"Configuration"}}]} ``` --- --- title: Monitoring description: Cloudflare Tunnel exposes logs, metrics, and diagnostic tools to help you monitor tunnel health and resolve issues. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/monitoring.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Monitoring Cloudflare Tunnel exposes logs, metrics, and diagnostic tools to help you monitor tunnel health and resolve issues. ## Tunnel health You can check your tunnel connection status in the [Cloudflare dashboard ↗](https://dash.cloudflare.com/) by going to **Networking** \> **Tunnels**, or by running `cloudflared tunnel list`. [ Go to **Tunnels** ](https://dash.cloudflare.com/?to=/:account/tunnels) | Status | Meaning | Recommended Action | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Healthy** | The tunnel is active and serving traffic through four connections to the Cloudflare global network. | No action is required. Your tunnel is running correctly. | | **Inactive** | The tunnel has been created (via the API or dashboard) but the cloudflared connector has never been run to establish a connection. | Run the tunnel as a service (recommended) or use the cloudflared tunnel run command on your origin server to connect the tunnel to Cloudflare. Refer to [substep 6 of step 1 in the Create a Tunnel dashboard guide](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/#1-create-a-tunnel) or step 4 in the [Create a Tunnel API guide](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel-api/#4-install-and-run-the-tunnel). | | **Down** | The tunnel was previously connected but is currently disconnected because the cloudflared process has stopped. | 1\. Ensure the cloudflared [service](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/local-management/as-a-service/) or process is actively running on your server. 2\. Check for server-side issues, such as the machine being powered off, an application crash, or recent network changes. | | **Degraded** | The cloudflared connector is running and the tunnel is serving traffic, but at least one individual connection has failed. Further degradation in [tunnel availability](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/configure-tunnels/tunnel-availability/) could risk the tunnel going down and failing to serve traffic. | 1\. Review your cloudflared [logs](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/monitor-tunnels/logs/) for connection failures or error messages. 2\. Investigate local network and firewall rules to ensure they are not blocking connections to the [Cloudflare Tunnel IPs and ports](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/configure-tunnels/tunnel-with-firewall/). | Tunnel status scope The tunnel status only reflects the connection between `cloudflared` and the Cloudflare network. It does not indicate whether `cloudflared` can reach your internal services. A tunnel can appear **Healthy** while users are unable to connect to an application. ### Notifications Administrators can receive alerts when tunnels change health or deployment status. Notifications can be delivered by email, webhook, or third-party services. To configure tunnel notifications, refer to [Create a notification](https://developers.cloudflare.com/notifications/get-started/#create-a-notification). Tunnel Creation or Deletion Event **Who is it for?** Customers who want to receive a notification when Cloudflare Tunnels are created or deleted in their account. **Other options / filters** None. **Included with** All Cloudflare Zero Trust plans. **What should you do if you receive one?** No action is needed. Tunnel Health Alert **Who is it for?** Customers who want to be warned about changes in health status for their Cloudflare Tunnels. **Other options / filters** None. **Included with** All Cloudflare Zero Trust plans. **What should you do if you receive one?** Monitor tunnel health over time and consider deploying [cloudflared replicas or load balancers](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/configure-tunnels/tunnel-availability/). **Additional information** Refer to [Tunnel status](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/troubleshoot-tunnels/common-errors/#tunnel-status) to review the list of possible tunnel statuses (`Healthy`, `Inactive`, `Down` and `Degraded`). ## Logs Tunnel logs record all activity between `cloudflared` and the Cloudflare global network, and all activity between `cloudflared` and your origin server. ### Server-side logs If you have access to the origin server, you can use the [\--loglevel flag](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/configure-tunnels/run-parameters/#loglevel) to enable logging when you start the tunnel. By default, `cloudflared` prints logs to stdout and does not store logs on the server. You can optionally use the [\--logfile flag](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/configure-tunnels/run-parameters/#logfile) to write your logs to a file. To enable logs, [run the tunnel](https://developers.cloudflare.com/tunnel/configuration/#update-run-parameters) using the `--loglevel info` and `--logfile ` flags. For example, Terminal window ``` cloudflared tunnel --loglevel info --logfile cloudflared.log run ``` ### Remote log streaming You can stream real-time logs from a running tunnel without SSH access to the server. * [ CLI ](#tab-panel-6696) * [ Dashboard ](#tab-panel-6697) The `cloudflared` daemon can stream logs from any tunnel in your account to the local command line. `cloudflared` must be installed on both your local machine and the origin server. 1. On your local machine, authenticate `cloudflared` to your Cloudflare account: Terminal window ``` cloudflared tunnel login ``` 2. Run `cloudflared tail` for a specific tunnel: Terminal window ``` cloudflared tail ``` For a more structured view of the JSON message, you can pipe the output to tools like [jq ↗](https://stedolan.github.io/jq/): Terminal window ``` cloudflared tail --output=json | jq . ``` 1. If you are running multiple [replicas](https://developers.cloudflare.com/tunnel/configuration/#replicas-and-high-availability), you can specify which replica to stream logs from: Terminal window ``` cloudflared tail --connector-id ``` To find the replica ID, go to **Networks** \> **Connectors** and select your tunnel. All active replicas appear in the **Connectors** list on the tunnel overview page. The replica ID is the **Connector ID**. Log filtering options You can filter logs by event type (`--event`), event level (`--level`), or sampling rate (`-sampling`) to reduce the volume of logs streamed from the origin. This helps mitigate the performance impact on the origin, especially when the origin is normally under high load. For example: Terminal window ``` cloudflared tail --level debug ``` | Flag | Description | Allowed values | Default value | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------- | | \--event | Filter by the type of event / request. | cloudflared, http, tcp, udp | All events | | \--level | Return logs at this level and above. Works independently of the [\--loglevel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/configure-tunnels/run-parameters/#loglevel) setting on the server. | debug, info, warn, error, fatal | debug | | \--sampling | Sample a fraction of the total logs. | Number from 0.0 to 1.0 | 1.0 | Dashboard log streams are only available for remotely-managed tunnels. To stream tunnel logs from the dashboard: 1. In [Cloudflare One ↗](https://one.dash.cloudflare.com/), go to **Networks** \> **Connectors** \> **Cloudflare Tunnels**. 2. Select **View logs** next to the tunnel you want to monitor. 3. Select **Begin log stream**. #### View logs for a replica If you are running multiple `cloudflared` instances for the same tunnel (also known as [replicas](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/configure-tunnels/tunnel-availability/)), you can stream logs for a specific replica: 1. In [Cloudflare One ↗](https://one.dash.cloudflare.com/), go to **Networks** \> **Connectors** \> **Cloudflare Tunnels** and select your tunnel. 2. In the **Connectors** list, select the **Connector ID** for the replica you want to view. 3. Select **Begin log stream**. ## Metrics Tunnel metrics show a Cloudflare Tunnel's throughput and resource usage over time. When you run a tunnel, `cloudflared` will spin up a Prometheus metrics endpoint — an HTTP server that exposes metrics in [Prometheus ↗](https://prometheus.io/docs/introduction/overview/) format. You can use the Prometheus toolkit on a remote machine to scrape metrics data from the `cloudflared` server. ### Default metrics server address In non-containerized environments, `cloudflared` starts the metrics server on `127.0.0.1:/metrics`, where `` is the first available port in the range `20241` to `20245`. If all ports are unavailable, `cloudflared` binds to a random port. In containerized environments (Docker, Kubernetes), the default address is `0.0.0.0:/metrics`. To determine the default port, check your [tunnel logs](#server-side-logs) around the time when the tunnel started. For example: ``` 2024-12-19T21:17:58Z INF Starting metrics server on 127.0.0.1:20241/metrics ``` ### Configure a custom address To serve metrics on a custom IP address and port, perform these steps on the `cloudflared` host: 1. [Run the tunnel](https://developers.cloudflare.com/tunnel/configuration/#update-run-parameters) using the`--metrics` flag. For example, Terminal window ``` cloudflared tunnel --metrics 127.0.0.1:60123 run my-tunnel ``` Note If you plan to fetch metrics from another machine on the local network, replace `127.0.0.1` with the internal IP of the `cloudflared` server (for example, `198.168.x.x`). To serve metrics on all available network interfaces, use `0.0.0.0`. 2. Verify that the metrics server is running by going to `http://localhost:60123/metrics`. This will only work if you configured a localhost IP (`127.0.0.1` or `0.0.0.0`). You can now export the metrics to Prometheus and Grafana to visualize and query the data. Refer to the [Grafana tutorial](https://developers.cloudflare.com/tunnel/tutorials/grafana/) for instructions on getting started with these tools. cloudflared metrics | Name | Description | Type | Labels | | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ------- | ---------------------------------- | | build\_info | Build and version information. | GAUGE | goversion, revision, type, version | | cloudflared\_config\_local\_config\_pushes | Number of local configuration pushes to Cloudflare. | COUNTER | | | cloudflared\_config\_local\_config\_pushes\_errors | Number of errors that occurred during local configuration pushes. | COUNTER | | | cloudflared\_orchestration\_config\_version | Configuration version. | GAUGE | | | cloudflared\_tcp\_active\_sessions | Concurrent number of TCP sessions that are being proxied to any origin. | GAUGE | | | cloudflared\_tcp\_total\_sessions | Total number of TCP sessions that have been proxied to any origin. | COUNTER | | | cloudflared\_tunnel\_active\_streams | Total number of active streams. | GAUGE | | | cloudflared\_tunnel\_concurrent\_requests\_per\_tunnel | Concurrent number of requests proxied through each tunnel. | GAUGE | | | cloudflared\_tunnel\_ha\_connections | Number of active HA connections. | GAUGE | | | cloudflared\_tunnel\_request\_errors | Number of errors proxying to origin. | COUNTER | | | cloudflared\_tunnel\_server\_locations | Where each tunnel is connected to. 1 means current location, 0 means previous locations. | GAUGE | connection\_id, edge\_location | | cloudflared\_tunnel\_timer\_retries | Unacknowledged heart beats count. | GAUGE | | | cloudflared\_tunnel\_total\_requests | Number of requests proxied through all tunnels. | COUNTER | | | cloudflared\_tunnel\_tunnel\_authenticate\_success | Number of successful tunnel authentication events. | COUNTER | | | cloudflared\_tunnel\_tunnel\_register\_success | Number of successful tunnel registrations. | COUNTER | rpcName | | cloudflared\_udp\_active\_sessions | Concurrent number of UDP sessions that are being proxied to any origin. | GAUGE | | | cloudflared\_udp\_total\_sessions | Total number of UDP sessions that have been proxied to any origin. | COUNTER | | | coredns\_panics\_total | Number of panics. | COUNTER | | | quic\_client\_closed\_connections | Number of connections that have been closed. | COUNTER | | | quic\_client\_latest\_rtt | Latest round-trip time (RTT) measured on a connection. | GAUGE | conn\_index | | quic\_client\_lost\_packets | Number of packets that have been lost from a connection. | COUNTER | conn\_index, reason | | quic\_client\_min\_rtt | Lowest RTT measured on a connection in ms. | GAUGE | conn\_index | | quic\_client\_packet\_too\_big\_dropped | Number of packets received from origin that are too big to send to Cloudflare and are dropped as a result. | COUNTER | | | quic\_client\_smoothed\_rtt | Smoothed RTT calculated for a connection in ms. | GAUGE | conn\_index | | quic\_client\_total\_connections | Number of connections initiated. For all QUIC metrics, client means the side initiating the connection. | COUNTER | | Prometheus metrics | Name | Description | Type | Labels | | ----------------------------------------------- | -------------------------------------------- | ------- | ------ | | promhttp\_metric\_handler\_requests\_in\_flight | Current number of scrapes being served. | GAUGE | | | promhttp\_metric\_handler\_requests\_total | Total number of scrapes by HTTP status code. | COUNTER | code | Go runtime metrics | Name | Description | Type | Labels | | ------------------------------------- | ------------------------------------------------------------------ | ------- | ------- | | go\_gc\_duration\_seconds | A summary of the pause duration of garbage collection cycles. | SUMMARY | | | go\_goroutines | Number of goroutines that currently exist. | GAUGE | | | go\_info | Information about the Go environment. | GAUGE | version | | go\_memstats\_alloc\_bytes | Number of bytes allocated and still in use. | GAUGE | | | go\_memstats\_alloc\_bytes\_total | Total number of bytes allocated, even if freed. | COUNTER | | | go\_memstats\_buck\_hash\_sys\_bytes | Number of bytes used by the profiling bucket hash table. | GAUGE | | | go\_memstats\_frees\_total | Total number of frees. | COUNTER | | | go\_memstats\_gc\_sys\_bytes | Number of bytes used for garbage collection system metadata. | GAUGE | | | go\_memstats\_heap\_alloc\_bytes | Number of heap bytes allocated and still in use. | GAUGE | | | go\_memstats\_heap\_idle\_bytes | Number of heap bytes waiting to be used. | GAUGE | | | go\_memstats\_heap\_inuse\_bytes | Number of heap bytes that are in use. | GAUGE | | | go\_memstats\_heap\_objects | Number of allocated objects. | GAUGE | | | go\_memstats\_heap\_released\_bytes | Number of heap bytes released to OS. | GAUGE | | | go\_memstats\_heap\_sys\_bytes | Number of heap bytes obtained from system. | GAUGE | | | go\_memstats\_last\_gc\_time\_seconds | Number of seconds since 1970 of last garbage collection. | GAUGE | | | go\_memstats\_lookups\_total | Total number of pointer lookups. | COUNTER | | | go\_memstats\_mallocs\_total | Total number of mallocs. | COUNTER | | | go\_memstats\_mcache\_inuse\_bytes | Number of bytes in use by mcache structures. | GAUGE | | | go\_memstats\_mcache\_sys\_bytes | Number of bytes used for mcache structures obtained from system. | GAUGE | | | go\_memstats\_mspan\_inuse\_bytes | Number of bytes in use by mspan structures. | GAUGE | | | go\_memstats\_mspan\_sys\_bytes | Number of bytes used for mspan structures obtained from system. | GAUGE | | | go\_memstats\_next\_gc\_bytes | Number of heap bytes when next garbage collection will take place. | GAUGE | | | go\_memstats\_other\_sys\_bytes | Number of bytes used for other system allocations. | GAUGE | | | go\_memstats\_stack\_inuse\_bytes | Number of bytes in use by the stack allocator. | GAUGE | | ## Diagnostic logs Cloudflare Tunnel generates diagnostic reports that collect data from a single `cloudflared` instance running on the local machine. This requires `cloudflared` version 2024.12.2 or later. ### Generate diagnostics 1. (Linux only) To include network diagnostics in the logs, allow the `cloudflared` user to create RAW and PACKET sockets without root permissions: Terminal window ``` sudo setcap cap_net_raw+ep /usr/bin/traceroute && sudo setcap cap_net_raw+ep /usr/bin/traceroute ``` If you do not set `cap_net_raw`, then traceroute data will be unavailable. 2. Get diagnostic logs: Terminal window ``` cloudflared tunnel diag ``` If multiple instances of `cloudflared` are running on the same host, specify the [metrics server IP and port](#configure-a-custom-address) for the instance you want to diagnose. For example: Terminal window ``` cloudflared tunnel diag --metrics 127.0.0.1:20241 ``` This command will output the status of each diagnostic task and place a `cloudflared-diag-YYYY-MM-DDThh-mm-ss.zip` file in your working directory. Docker diagnostics `cloudflared` reads diagnostic data from the [tunnel metrics server](#metrics). To get diagnostic logs, the metrics server must be exposed from the Docker container and reachable from the host machine. 1. Determine the [metrics server port](#default-metrics-server-address) for the `cloudflared` instance running in Docker. 2. Ensure the container is deployed with port forwarding enabled. The diagnostic feature will request information from the Docker instance using local port `20241`, therefore you should forward port `20241` to the container port obtained in Step 1: Terminal window ``` docker run -d -p 20241: docker.io/cloudflare/cloudflared tunnel ... ``` 3. Verify that you can reach the metrics server address from the Docker host environment: Terminal window ``` curl localhost:20241/diag/tunnel ``` This command should return a JSON: ``` { "tunnelID": "ef96b330-a7f5-4bce-a00e-827ce5be077f", "connectorID": "d236670a-9f74-422f-adf1-030f5c5f0523", "connections": [ { "isConnected": true, "protocol": 1, "edgeAddress": "198.41.192.167"}, {"isConnected": true, "protocol": 1, "edgeAddress": "198.41.200.113", "index": 1}, {"isConnected": true, "protocol": 1, "edgeAddress": "198.41.192.47", "index": 2}, {"isConnected": true, "protocol": 1, "edgeAddress": "198.41.200.73", "index": 3} ], "icmp_sources": ["192.168.1.243", "fe80::c59:bd4a:e815:ed6"] } ``` 4. Run the diagnostic using the Docker container ID: Terminal window ``` cloudflared tunnel diag --diag-container-id= ``` Alternatively, you can specify the container's name instead of its ID: Terminal window ``` cloudflared tunnel diag --diag-container-id= ``` Running the diagnostic command with the container ID allows `cloudflared` to collect information from the Docker environment such as logs and container details. This command will output the status of each diagnostic task and place a `cloudflared-diag-YYYY-MM-DDThh-mm-ss.zip` file in your working directory. Kubernetes diagnostics The diagnostic feature will request data from the [tunnel metrics server](#metrics) using ports `20241` to `20245`. You will need to use port forwarding to allow the local `cloudflared` instance to connect to the metrics server on one of these ports. 1. Determine the tunnel's [metrics server port](#default-metrics-server-address). 2. Enable port forwarding: Terminal window ``` kubectl port-forward : ``` * ``: Name of the pod where the tunnel is running * `` is any local port in the range `20241` to `20245`. * `` is the Kubernetes pod port for the `cloudflared` instance you want to diagnose (obtained in Step 1). For example, if you set the metrics server address to `0.0.0.0:12345`: Terminal window ``` kubectl port-forward cloudflared-6d4897585b-r8kfz 20244:12345 ``` Connections made to local port `20244` are forwarded to port `12345` of the pod that is running the tunnel. 3. Run the diagnostic: Terminal window ``` cloudflared tunnel diag --diag-pod-id= ``` If the pod has multiple applications/services running and `cloudflared` is not the first in the pod, you must specify either the container ID or name: Terminal window ``` cloudflared tunnel diag --diag-pod-id= --diag-container-id= ``` This command will output the status of each diagnostic task and place a `cloudflared-diag-YYYY-MM-DDThh-mm-ss.zip` file in your working directory. ### Diagnostic file contents The `cloudflared-diag-YYYY-MM-DDThh-mm-ss.zip` archive contains the files listed below. The data in a file either applies to the `cloudflared` instance being diagnosed (`diagnosee`) or the instance that triggered the diagnosis (`diagnoser`). For example, if your tunnel is running in a Docker container, the diagnosee is the Docker instance and the diagnoser is the host instance. | File name | Description | Instance | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------- | | cli-configuration.json | [Tunnel run parameters](https://developers.cloudflare.com/tunnel/advanced/run-parameters/) used when starting the tunnel | diagnosee | | cloudflared\_logs.txt | [Tunnel log file](#logs)[1](#user-content-fn-1) | diagnosee | | configuration.json | Tunnel configuration parameters | diagnosee | | goroutine.pprof | goroutine profile made available by pprof | diagnosee | | heap.pprof | heap profile made available by pprof | diagnosee | | metrics.txt | Snapshot of [Tunnel metrics](#metrics) at the time of diagnosis | diagnosee | | network.txt | JSON traceroutes to Cloudflare's global network using IPv4 and IPv6 | diagnoser | | raw-network.txt | Raw traceroutes to Cloudflare's global network using IPv4 and IPv6 | diagnoser | | systeminformation.json | Operating system information and resource usage | diagnosee | | task-result.json | Result of each diagnostic task | diagnoser | | tunnelstate.json | Tunnel connections at the time of diagnosis | diagnosee | ## Footnotes 1. If the log file is blank, you may need to [set \--loglevel to debug](#server-side-logs) when you start the tunnel. The `--loglevel` parameter is only required if you ran the tunnel from the CLI using a `cloudflared tunnel run` command. It is not necessary if the tunnel runs as a Linux/macOS service or runs in Docker/Kubernetes. [↩](#user-content-fnref-1) ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/monitoring/","name":"Monitoring"}}]} ``` --- --- title: Integrations description: Use Cloudflare Tunnel with Cloudflare One, Workers VPC, Load Balancing, Access, Spectrum, and other Cloudflare services. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/integrations.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Integrations Cloudflare Tunnel integrates with other Cloudflare products to extend connectivity, security, and availability for your applications. ## Cloudflare One (private networking) Beyond publishing public applications, Cloudflare Tunnel is the connectivity layer for [Cloudflare One](https://developers.cloudflare.com/cloudflare-one/) — Cloudflare's SASE platform. The same post-quantum encrypted tunnels that serve your public applications can also serve private traffic when combined with the [Cloudflare One Client](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/): * **Private applications** — Expose internal web apps, SSH servers, RDP hosts, and other services to authenticated users without making them publicly reachable. * **Private networks** — Route entire IP ranges (RFC 1918, custom CIDRs) through a tunnel, replacing site-to-site VPNs. Users on Cloudflare One Client-enrolled devices reach private IPs as if they were on your private network. * **Network traffic filtering** — Apply DNS, HTTP, and network-level policies through [Cloudflare Gateway](https://developers.cloudflare.com/cloudflare-one/traffic-policies/) to all traffic flowing through the tunnel. If you are using Cloudflare Tunnel for Zero Trust network access, VPN replacement, or private network connectivity, refer to the [Cloudflare One Tunnel documentation](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/) for setup and configuration. **Related:** [Connect private networks](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/cloudflared/) | [SSH guide](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/use-cases/ssh/) | [RDP guide](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/use-cases/rdp/) | [Replace your VPN](https://developers.cloudflare.com/learning-paths/replace-vpn/get-started/) ## Workers VPC [Workers VPC](https://developers.cloudflare.com/workers-vpc/) enables Cloudflare Workers to access private resources such as databases, internal APIs, and other services. Cloudflare Tunnel serves as the connectivity layer, establishing a post-quantum encrypted outbound connection from your private network to Cloudflare. You can manage your tunnels directly from [Wrangler](https://developers.cloudflare.com/workers/wrangler/commands/tunnel/), the Cloudflare Developer Platform CLI. **Get started:** [Create a tunnel](https://developers.cloudflare.com/tunnel/setup/) and then follow the [Workers VPC guide](https://developers.cloudflare.com/workers-vpc/get-started/) to configure VPC Services. **Related:** [Connect to a private API](https://developers.cloudflare.com/workers-vpc/examples/private-api/) | [Connect to an S3 bucket](https://developers.cloudflare.com/workers-vpc/examples/private-s3-bucket/) ## Load Balancing [Cloudflare Load Balancing](https://developers.cloudflare.com/load-balancing/) distributes traffic across multiple origins using health checks, steering algorithms, and failover logic. Combined with Tunnel, you can load balance traffic to origins without publicly routable IP addresses. Each tunnel is assigned a subdomain (`.cfargotunnel.com`). Add this as an endpoint in a Load Balancer pool with the application hostname as the host header. **Get started:** Refer to [Load Balancing setup](https://developers.cloudflare.com/tunnel/routing/#load-balancing) for step-by-step instructions. **Related:** [Tunnel replicas](https://developers.cloudflare.com/tunnel/configuration/#replicas-and-high-availability) | [Load Balancing reference architecture](https://developers.cloudflare.com/reference-architecture/architectures/load-balancing/) ## Cloudflare Access [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/access-controls/) provides an identity-aware proxy that authenticates every request to your applications. Combined with Tunnel, Access lets you publish internal web applications to the Internet while ensuring only authorized users can reach them. You can configure [Access policies](https://developers.cloudflare.com/cloudflare-one/access-controls/policies/) based on user identity, source IP ranges, service tokens for machine-to-machine authentication, and more. **Get started:** [Publish a self-hosted application](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/self-hosted-public-app/). **Related:** [Identity providers](https://developers.cloudflare.com/cloudflare-one/integrations/identity-providers/) | [Validate Access JWTs](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/validating-json/) ## Spectrum [Cloudflare Spectrum](https://developers.cloudflare.com/spectrum/) extends DDoS protection and traffic acceleration to non-HTTP protocols. You can route Spectrum application traffic to origins connected via Tunnel using a DNS CNAME record or Load Balancer. Spectrum integration with Tunnel is only supported for HTTP and HTTPS applications. For the full list of limitations, refer to the [Spectrum limitations documentation](https://developers.cloudflare.com/spectrum/reference/limitations/). ## Additional integrations [Keyless SSL](https://developers.cloudflare.com/ssl/keyless-ssl/configuration/cloudflare-tunnel/) Connect your key server to Cloudflare without exposing it to the internet. [Post-quantum tunnels](https://developers.cloudflare.com/ssl/post-quantum-cryptography/pqc-and-zero-trust/) TLS 1.3 tunnels with post-quantum key agreement between your data centers and Cloudflare. [Data Localization](https://developers.cloudflare.com/data-localization/compatibility/) Restrict tunnel connectivity to specific regions for data residency requirements. [Cloudflare for SaaS](https://developers.cloudflare.com/reference-architecture/design-guides/extending-cloudflares-benefits-to-saas-providers-end-customers/#cloudflare-tunnel-as-fallback-origin-setup-with-regional-services) Use Tunnel with Cloudflare for SaaS to enhance your SaaS application origin security. [Hyperdrive](https://developers.cloudflare.com/hyperdrive/configuration/connect-to-private-database/) Connect Hyperdrive to a private database through Cloudflare Tunnel. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/integrations/","name":"Integrations"}}]} ``` --- --- title: Troubleshooting description: Use this page to diagnose and resolve common issues with Cloudflare Tunnel. Many issues are resolved by upgrading to the latest version of cloudflared — refer to Update cloudflared before investigating further. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/troubleshooting.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Troubleshooting Use this page to diagnose and resolve common issues with Cloudflare Tunnel. Many issues are resolved by upgrading to the latest version of `cloudflared` — refer to [Update cloudflared](https://developers.cloudflare.com/tunnel/downloads/update-cloudflared/) before investigating further. For tunnel health monitoring, logs, and metrics, refer to [Monitoring](https://developers.cloudflare.com/tunnel/monitoring/). ## Connection errors When `cloudflared` cannot reach the Cloudflare network, it [logs](https://developers.cloudflare.com/tunnel/monitoring/#logs) specific error messages that indicate whether the issue is DNS resolution, QUIC (UDP), or TCP connectivity. ### DNS resolution failures #### `edge discovery: error looking up Cloudflare edge IPs` ``` ERR edge discovery: error looking up Cloudflare edge IPs: the DNS query failed error="lookup _v2-origintunneld._tcp.argotunnel.com on 172.19.64.1:53: no such host" ``` This error means the DNS resolver configured on your machine cannot resolve the SRV records that `cloudflared` uses to discover the [Cloudflare Tunnel destination IPs](https://developers.cloudflare.com/tunnel/configuration/#firewall-rules). Common causes include corporate DNS resolvers that strip or block SRV records, and DNS resolvers that return compressed SRV records. **To diagnose:** On the `cloudflared` host machine, run: Terminal window ``` dig SRV _v2-origintunneld._tcp.argotunnel.com ``` If you receive `SERVFAIL`, `NXDOMAIN`, or an empty answer, test against Cloudflare's public resolver: Terminal window ``` dig SRV _v2-origintunneld._tcp.argotunnel.com @1.1.1.1 ``` **To resolve:** * If `1.1.1.1` returns results but your local resolver does not, configure the host to use [Cloudflare DNS (1.1.1.1)](https://developers.cloudflare.com/1.1.1.1/setup/) or another public resolver. * If neither resolver returns results, your firewall is likely blocking outbound DNS queries (UDP port `53`). Work with your network administrator to allow DNS traffic. #### `DNS query failed ... i/o timeout` ``` ERR edge discovery: error looking up Cloudflare edge IPs: the DNS query failed error="lookup _v2-origintunneld._tcp.argotunnel.com on 127.0.0.11:53: read udp 127.0.0.1:53467->127.0.0.11:53: i/o timeout" ``` This variant means DNS queries from `cloudflared` are being blocked or dropped entirely — the resolver never responds. This is common in container environments (Docker, Kubernetes) where the internal DNS resolver (`127.0.0.11`) is unreachable or misconfigured. **To resolve:** * In Docker, verify your container's DNS configuration (`/etc/resolv.conf`). You can override the resolver with `--dns 1.1.1.1` when running the container. * In Kubernetes, verify the `kube-dns` or `CoreDNS` service is running and reachable from the pod. * On the `cloudflared` host, verify that the resolver listed in `/etc/resolv.conf` is reachable and responding to queries. ### QUIC handshake timeout #### `Failed to dial a quic connection` ``` ERR Failed to dial a quic connection error="failed to dial to edge with quic: timeout: handshake did not complete in time" connIndex=0 ip=198.41.192.227 INF Retrying connection in up to 2s connIndex=0 ip=198.41.192.227 ``` This error means `cloudflared` resolved the [Cloudflare Tunnel destination IPs](https://developers.cloudflare.com/tunnel/configuration/#firewall-rules) but could not complete a QUIC handshake over UDP port `7844`. Your network or firewall is blocking outbound UDP traffic to Cloudflare. `cloudflared` retries with exponential backoff (2, 4, 8, 16, 32, up to 64 seconds). After exhausting retries, it falls back to HTTP/2 over TCP: ``` INF Switching to fallback protocol http2 connIndex=0 ``` If the fallback also fails, you will see a [TCP connection timeout](#tcp-connection-timeout) error. **To diagnose:** On the `cloudflared` host machine, test connectivity on port `7844`: Terminal window ``` nc -uvz -w 3 198.41.192.227 7844 ``` Replace `198.41.192.227` with the IP shown in your [error message](#failed-to-dial-a-quic-connection). If the port is closed or blocked by a firewall, the command will return `Connection refused` or time out. **To resolve:** * Allow outbound UDP traffic to port `7844` on your firewall or security group. Refer to the [full list of IPs and ports](https://developers.cloudflare.com/tunnel/configuration/#firewall-rules). * If you cannot open UDP, `cloudflared` will fall back to HTTP/2 over TCP automatically. You can also force HTTP/2 by setting the `--protocol http2` [run parameter](https://developers.cloudflare.com/tunnel/configuration/#run-parameters), but QUIC is recommended for better performance. ### TCP connection timeout #### `DialContext error: dial tcp ... i/o timeout` ``` ERR Unable to establish connection with Cloudflare edge error="DialContext error: dial tcp 198.41.200.43:7844: i/o timeout" connIndex=0 ERR Serve tunnel error error="DialContext error: dial tcp 198.41.200.43:7844: i/o timeout" connIndex=0 ``` This error means `cloudflared` cannot reach Cloudflare over TCP port `7844`. If you also see the [QUIC handshake timeout](#failed-to-dial-a-quic-connection) above it, both UDP and TCP are blocked — the tunnel cannot connect at all. **To diagnose:** As a quick test, run: Terminal window ``` curl -v https://region1.v2.argotunnel.com:7844 ``` If the connection hangs, traffic is being dropped between your host and Cloudflare. To test if `cloudflared` can connect on port `7844`, run: Terminal window ``` nc -vz -w 3 198.41.200.43 7844 ``` Replace `198.41.200.43` with the IP shown in your [error message](#dialcontext-error-dial-tcp--io-timeout). If the port is closed or blocked by a firewall, the command will return `Connection refused` or time out. **To resolve:** * Allow outbound TCP traffic to port `7844` to the [Cloudflare Tunnel IP ranges](https://developers.cloudflare.com/tunnel/configuration/#firewall-rules). * If your environment blocks port `7844` entirely (both UDP and TCP), the tunnel cannot function. Work with your network administrator to allow outbound traffic on this port. ## I see `cloudflared service is already installed`. If you see this error when installing a remotely-managed tunnel, ensure that no other `cloudflared` instances are running as a service on this machine. Only a single instance of `cloudflared` may run as a service on any given machine. Instead, add additional routes to your existing tunnel. Alternatively, you can run `sudo cloudflared service uninstall` to uninstall `cloudflared`. ## I see `An A, AAAA, or CNAME record with that host already exists`. If you are unable to save your tunnel's public hostname, choose a different hostname or delete the existing DNS record. [Check the DNS records](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/) for your domain from the [Cloudflare dashboard ↗](https://dash.cloudflare.com). ## Tunnel credentials file does not exist or is not a file. If you encounter the following error when running a tunnel, double check your `config.yml` file and ensure that the `credentials-file` points to the correct location. You may need to change `/root/` to your home directory. Terminal window ``` cloudflared tunnel run ``` ``` 2021-06-04T06:21:16Z INF Starting tunnel tunnelID=928655cc-7f95-43f2-8539-2aba6cf3592d Tunnel credentials file '/root/.cloudflared/928655cc-7f95-43f2-8539-2aba6cf3592d.json' doesn't exist or is not a file ``` ## My tunnel fails to authenticate. To start using Cloudflare Tunnel, a super administrator in the Cloudflare account must first log in through `cloudflared login`. The client will launch a browser window and prompt the user to select a hostname in their Cloudflare account. Once selected, Cloudflare generates a certificate that consists of three components: * The public key of the origin certificate for that hostname * The private key of the origin certificate for that domain * A token that is unique to Cloudflare Tunnel Those three components are bundled into a single PEM file that is downloaded one time during that login flow. The host certificate is valid for the root domain and any subdomain one-level deep. Cloudflare uses that certificate file to authenticate `cloudflared` to create DNS records for your domain in Cloudflare. The third component, the token, consists of the zone ID (for the selected domain) and an API token scoped to the user who first authenticated with the login command. When user permissions change (if that user is removed from the account or becomes an admin of another account, for example), Cloudflare rolls the user's API key. However, the certificate file downloaded through `cloudflared` retains the older API key and can cause authentication failures. The user will need to login once more through `cloudflared` to regenerate the certificate. Alternatively, the administrator can create a dedicated service user to authenticate. ## I see an error: x509: certificate signed by unknown authority. This means the origin is using a certificate that `cloudflared` does not trust. For example, you may get this error if you are using SSL/TLS inspection in a proxy between your server and Cloudflare. To resolve: * Add the certificate to the system certificate pool. * Use the `--origin-ca-pool` flag and specify the path to the certificate. * Use the `--no-tls-verify` flag to stop `cloudflared` checking the certificate for a trust chain. ## I see an error 1033 when attempting to run a tunnel. A `1033` error indicates your tunnel is not connected to Cloudflare's network because Cloudflare's network cannot find a healthy `cloudflared` instance to receive the traffic. First, review whether your tunnel is listed as `Active` on the [Cloudflare One ↗](https://one.dash.cloudflare.com/) dashboard by going to **Networks** \> **Connectors** \> **Cloudflare Tunnels** or run `cloudflared tunnel list`. If the tunnel is not `Active`, review the following and take the action necessary for your tunnel status: | Status | Meaning | Recommended Action | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Healthy** | The tunnel is active and serving traffic through four connections to the Cloudflare global network. | No action is required. Your tunnel is running correctly. | | **Inactive** | The tunnel has been created (via the API or dashboard) but the cloudflared connector has never been run to establish a connection. | Run the tunnel as a service (recommended) or use the cloudflared tunnel run command on your origin server to connect the tunnel to Cloudflare. Refer to [substep 6 of step 1 in the Create a Tunnel dashboard guide](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/#1-create-a-tunnel) or step 4 in the [Create a Tunnel API guide](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel-api/#4-install-and-run-the-tunnel). | | **Down** | The tunnel was previously connected but is currently disconnected because the cloudflared process has stopped. | 1\. Ensure the cloudflared [service](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/local-management/as-a-service/) or process is actively running on your server. 2\. Check for server-side issues, such as the machine being powered off, an application crash, or recent network changes. | | **Degraded** | The cloudflared connector is running and the tunnel is serving traffic, but at least one individual connection has failed. Further degradation in [tunnel availability](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/configure-tunnels/tunnel-availability/) could risk the tunnel going down and failing to serve traffic. | 1\. Review your cloudflared [logs](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/monitor-tunnels/logs/) for connection failures or error messages. 2\. Investigate local network and firewall rules to ensure they are not blocking connections to the [Cloudflare Tunnel IPs and ports](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/configure-tunnels/tunnel-with-firewall/). | For more information, refer to the [comprehensive list of Cloudflare 1xxx errors](https://developers.cloudflare.com/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors/). ## I see a 502 Bad Gateway error when connecting to an HTTP or HTTPS application through tunnel. A `502 Bad Gateway` error with `Unable to reach the origin service. The service may be down or it may not be responding to traffic from cloudflared` on a tunnel route means the tunnel itself is connected to the Cloudflare network, but `cloudflared` cannot reach the origin service defined in your ingress rule. Unlike [error 1033](#i-see-an-error-1033-when-attempting-to-run-a-tunnel), which indicates the tunnel is not connected to Cloudflare, a 502 error indicates the problem is between `cloudflared` and your local service. To identify the specific cause, review your [Tunnel logs](https://developers.cloudflare.com/tunnel/monitoring/#logs) for `error`\-level messages. Common causes include: #### Origin service is not running If the origin service has stopped or never started, `cloudflared` logs will show an error similar to: ``` error="dial tcp [::1]:8080: connect: connection refused" ``` To resolve, verify the service is running and listening on the expected port: Terminal window ``` curl -v http://localhost:8080 ``` If the service is not running, start or restart it. You can confirm the service is listening by running `ss -tlnp | grep ` (Linux) or `lsof -iTCP -sTCP:LISTEN -nP | grep ` (macOS). #### Origin service URL uses the wrong protocol If the origin expects HTTPS but the tunnel route specifies `http://`, or vice versa, `cloudflared` logs will show an error similar to: ``` error="net/http: HTTP/1.x transport connection broken: malformed HTTP response \"\x15\x03\x01\x00\x02\x02\"" ``` To resolve, update the service URL in your tunnel route to match the [protocol](https://developers.cloudflare.com/tunnel/routing/#supported-protocols) your origin expects. For example, change `http://localhost:8080` to `https://localhost:8080`. If you are using a locally-managed tunnel, update your ingress rule in the [configuration file](https://developers.cloudflare.com/tunnel/other-tunnel-types/local-management/configuration-file/). #### Origin service URL points to the wrong port If the port in your tunnel route does not match the port your service is listening on, `cloudflared` will log a `connection refused` error for that port. Double-check the service URL in your ingress rule and compare it against the port your application is bound to. #### Origin uses a certificate that `cloudflared` does not trust If the origin presents a TLS certificate that `cloudflared` cannot verify, the logs will show an error similar to: ``` error="x509: certificate is valid for example.com, not localhost" ``` This commonly occurs when the origin uses a self-signed certificate or when an SSL/TLS inspection proxy sits between `cloudflared` and the origin. To resolve, use one of the following approaches: * Set [originServerName](https://developers.cloudflare.com/tunnel/configuration/#originservername) to the hostname on the origin certificate in your tunnel route. If you are using a locally-managed tunnel, here is an example of a [configuration file](https://developers.cloudflare.com/tunnel/other-tunnel-types/local-management/configuration-file/): ``` ingress: - hostname: app.example.com service: https://localhost:443 originRequest: originServerName: app.example.com ``` * Provide the CA certificate using [caPool](https://developers.cloudflare.com/tunnel/configuration/#capool): ``` ingress: - hostname: app.example.com service: https://localhost:443 originRequest: caPool: /path/to/ca-cert.pem ``` * As a last resort, disable TLS verification with [noTLSVerify](https://developers.cloudflare.com/tunnel/configuration/#notlsverify). This is not recommended for production environments. ``` ingress: - hostname: app.example.com service: https://localhost:443 originRequest: noTLSVerify: true ``` ## I see `ERR_TOO_MANY_REDIRECTS` when attempting to connect to an Access self-hosted app. This error occurs when `cloudflared` does not recognize the SSL/TLS certificate presented by your origin. To resolve the issue, set the [origin server name](https://developers.cloudflare.com/tunnel/configuration/#originservername) parameter to the hostname on your origin certificate. Here is an example of a locally-managed tunnel configuration: ``` ingress: - hostname: test.example.com service: https://localhost:443 originRequest: originServerName: test.example.com ``` ## `cloudflared access` shows an error `websocket: bad handshake`. This means that your `cloudflared access` client is unable to reach your `cloudflared tunnel` origin. To diagnose this, look at the `cloudflared tunnel` logs. A common root cause is that the `cloudflared tunnel` is unable to proxy to your origin (for example, because the ingress is misconfigured, the origin is down, or the origin HTTPS certificate cannot be validated by `cloudflared tunnel`). If `cloudflared tunnel` has no logs, it means Cloudflare's network is not able to route the websocket traffic to it. There are several possible root causes behind this error: * Your `cloudflared tunnel` is either not running or not connected to Cloudflare's network. * WebSockets are not [enabled](https://developers.cloudflare.com/network/websockets/#enable-websockets). * Your Cloudflare account has Universal SSL enabled but your SSL/TLS encryption mode is set to **Off (not secure)**. To resolve, go to **SSL/TLS** \> **Overview** in the Cloudflare dashboard and set your SSL/TLS encryption mode to **Flexible**, **Full**, or **Full (strict)**. * Your requests are blocked by [Super Bot Fight Mode](https://developers.cloudflare.com/bots/get-started/super-bot-fight-mode/). To resolve, make sure you set **Definitely automated** to _Allow_ in the bot fight mode settings. * Your SSH or RDP Access application has the [Binding Cookie](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/#binding-cookie) enabled. To disable the cookie, go to **Access controls** \> **Applications** and edit the application settings. * One or more [Workers routes](https://developers.cloudflare.com/workers/configuration/routing/routes/) are overlapping with the tunnel hostname, and the Workers do not properly handle the traffic. To resolve, either exclude your tunnel from the Worker route by not defining a route that includes the tunnel's hostname, or update your Worker to only handle specific paths and forward all other requests to the origin (for example, by using `return fetch(req)`). ## Tunnel connections fail with SSL error. If `cloudflared` returns error `error="remote error: tls: handshake failure"`, check to make sure the hostname in question is covered by a SSL certificate. If using a multi-level subdomain, an [advanced certificate](https://developers.cloudflare.com/ssl/edge-certificates/advanced-certificate-manager/) may be required as the Universal SSL will not cover more than one level of subdomain. This may surface in the browser as `ERR_SSL_VERSION_OR_CIPHER_MISMATCH`. ## Tunnel connections fail with `Too many open files` error. If your [Cloudflare Tunnel logs](https://developers.cloudflare.com/tunnel/monitoring/#logs) return a `socket: too many open files` error, it means that `cloudflared` has exhausted the open files limit on your machine. The maximum number of open files, or file descriptors, is an operating system setting that determines how many files a process is allowed to open. To increase the open file limit, you will need to [configure ulimit settings](https://developers.cloudflare.com/tunnel/configuration/#ulimits) on the machine running `cloudflared`. ## I see `failed to sufficiently increase receive buffer size` in my cloudflared logs. This buffer size increase is reported by the [quic-go library ↗](https://github.com/quic-go/quic-go) leveraged by [cloudflared ↗](https://github.com/cloudflare/cloudflared). You can learn more about the log message in the [quic-go repository ↗](https://github.com/quic-go/quic-go/wiki/UDP-Buffer-Sizes). This log message is generally not impactful and can be safely ignored when troubleshooting. However, if you have deployed `cloudflared` within a unique, high-bandwidth environment then buffer size can be manually overridden for testing purposes. To set the maximum receive buffer size on Linux: 1. Create a new file under `/etc/sysctl.d/`: Terminal window ``` sudo vi 98-core-rmem-max.conf ``` 2. In the file, define the desired buffer size: ``` net.core.rmem_max=2500000 ``` 3. Reboot the host machine running `cloudflared`. 4. To validate that these changes have taken effect, use the `grep` command: Terminal window ``` sudo sysctl -a | grep net.core.rmem_max ``` ``` net.core.rmem_max = 2500000 ``` ## Cloudflare Tunnel is buffering my streaming response instead of streaming it live. Proxied traffic through Cloudflare Tunnel is buffered by default unless the origin server includes the `Content-Type: text/event-stream` response header. This header tells `cloudflared` to stream data as it arrives instead of buffering the entire response. ## How do I contact support? For the fastest possible troubleshooting, ensure your support ticket includes comprehensive details. The more context you provide, the faster your issue can be identified and resolved. To ensure efficient resolution when [contacting support](https://developers.cloudflare.com/support/contacting-cloudflare-support/), include as much relevant detail as possible in your ticket: * Context: Briefly describe the scenario or use case (for example, where the user was, what they were trying to do). * Reproduction steps: Describe the steps you took to reproduce the issue during troubleshhooting. * Timestamps: Be specific and include the exact time and time zone when the issue occurred. * Troubleshooting attempts: Outline any troubleshooting steps or changes already attempted to resolve the issue. * Tunnel ID and tunnel name. * `cloudflared` version (run `cloudflared --version`). * How the tunnel was set up (locally-managed or remotely-managed via the dashboard). * Tunnel logs: Include the [logs from your local machine](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/monitor-tunnels/logs/#view-logs-on-your-local-machine). * Tunnel diagnostic logs: Include [tunnel diagnostic logs](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/troubleshoot-tunnels/diag-logs/). Write a detailed ticket to resolve your issue faster Avoid vague descriptions and include scenario, timestamps, and steps taken to troubleshoot the issue. Refer to the following example: Acme Corp attempted to establish a tunnel connection on October 30, 2025, at approximately 3:45 PM UTC. DNS resolution and TCP connectivity tests passed, but the `cloudflared` daemon logs showed `failed to sufficiently increase receive buffer size` errors. The tunnel diagnostic logs collected at 3:50 PM UTC are attached, along with the output from the DNS and network connectivity pre-checks. ### Collect debug logs To capture verbose output for troubleshooting: * **Locally-managed tunnels**: Run `cloudflared` with the `--loglevel debug` flag: Terminal window ``` cloudflared tunnel --loglevel debug run ``` To persist logs to a file, add the `--logfile` flag: Terminal window ``` cloudflared tunnel --loglevel debug --logfile /var/log/cloudflared/cloudflared.log run ``` * **Remotely-managed tunnels** (created via the dashboard): Configure logging in the tunnel's [run parameters](https://developers.cloudflare.com/tunnel/advanced/run-parameters/#loglevel). You can also stream logs in real time using the [remote log streaming](https://developers.cloudflare.com/tunnel/monitoring/#remote-log-streaming) feature. Attach the debug logs when contacting support — refer to the checklist above for the full list of information to include. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/troubleshooting/","name":"Troubleshooting"}}]} ``` --- --- title: Tutorials image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/tutorials/index.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Tutorials | Name | Last Updated | Difficulty | | ----------------------------------------------------------------------------------------------------- | ---------------- | ------------ | | [Monitor Cloudflare Tunnel with Grafana](https://developers.cloudflare.com/tunnel/tutorials/grafana/) | over 2 years ago | Intermediate | ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/tutorials/","name":"Tutorials"}}]} ``` --- --- title: Monitor Cloudflare Tunnel with Grafana description: This tutorial covers how to create the metrics endpoint and set up the Prometheus server. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/tutorials/grafana.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Monitor Cloudflare Tunnel with Grafana **Last reviewed:** over 2 years ago [Grafana ↗](https://grafana.com/) is a dashboard tool that visualizes data stored in other databases. You can use Grafana to convert your [tunnel metrics](https://developers.cloudflare.com/tunnel/monitoring/#metrics) into actionable insights. It is not possible to push metrics directly from `cloudflared` to Grafana. Instead, `cloudflared` runs a [Prometheus ↗](https://prometheus.io) metrics endpoint, which a Prometheus server periodically scrapes. Grafana then uses Prometheus as a data source to present metrics to the administrator. flowchart LR subgraph 192.168.1.1 A[cloudflared]-->B[Metrics endpoint] end B--->C subgraph 192.168.1.2 C[Prometheus server]-->D[Grafana dashboard] end This tutorial covers how to create the metrics endpoint, set up the Prometheus server, and view the data in Grafana. ## Before you begin * You will need a Cloudflare Tunnel. To create a tunnel, refer to our [getting started guide](https://developers.cloudflare.com/tunnel/setup/). ## Create the metrics endpoint If your tunnel was created via the CLI, run the following command on the `cloudflared` server (`192.168.1.1`): Terminal window ``` cloudflared tunnel --metrics 192.168.1.1:60123 run my-tunnel ``` If your tunnel was created via the dashboard, the [\--metrics](https://developers.cloudflare.com/tunnel/advanced/run-parameters/#metrics) flag must be added to your `cloudflared` system service configuration. Refer to [Add tunnel run parameters](https://developers.cloudflare.com/tunnel/advanced/run-parameters/#add-run-parameters-to-tunnel-service) for instructions on how to do this. ## Set up Prometheus On the Prometheus and Grafana server (`192.168.1.2`): 1. [Download ↗](https://prometheus.io/download/) Prometheus. 2. Extract Prometheus: Terminal window ``` tar xvfz prometheus-*.tar.gz cd prometheus-* ``` 3. Open `prometheus.yml` in a text editor and add the `cloudflared` job to the end of the file: ``` # my global config global: scrape_interval: 15s # Set the scrape interval to every 15 seconds. Default is every 1 minute. evaluation_interval: 15s # Evaluate rules every 15 seconds. The default is every 1 minute. # scrape_timeout is set to the global default (10s). # Alertmanager configuration alerting: alertmanagers: - static_configs: - targets: # - alertmanager:9093 # Load rules once and periodically evaluate them according to the global 'evaluation_interval'. rule_files: # - "first_rules.yml" # - "second_rules.yml" # A scrape configuration containing exactly one endpoint to scrape: # Here it's Prometheus itself. scrape_configs: # The job name is added as a label `job=` to any timeseries scraped from this config. - job_name: "prometheus" # metrics_path defaults to '/metrics' # scheme defaults to 'http'. static_configs: - targets: ["localhost:9090"] ## Address of Prometheus dashboard - job_name: "cloudflared" static_configs: - targets: ["198.168.1.1:60123"] ## cloudflared server IP and the --metrics port configured for the tunnel ``` 4. Start Prometheus: Terminal window ``` ./prometheus --config.file="prometheus.yml" ``` You can optionally configure Prometheus to run as a service so that it does not need to be manually started if the machine reboots. 5. Open a browser and go to `http://localhost:9090/`. You should be able to access the Prometheus dashboard. 6. To verify that Prometheus is fetching tunnel metrics, enter `cloudflared_tunnel_total_requests` into the expression console and select **Execute**. ![Prometheus dashboard showing tunnel metrics data](https://developers.cloudflare.com/_astro/Prometheus-dashboard.CUKRS856_28Ma3Y.webp) Refer to [Available metrics](https://developers.cloudflare.com/tunnel/monitoring/#metrics) to check what other metrics are available. ## Connect Grafana to Prometheus 1. [Download ↗](https://grafana.com/grafana/download) and install Grafana. 2. Start Grafana as a system service: Terminal window ``` sudo systemctl daemon-reload sudo systemctl start grafana-server ``` 3. Verify that Grafana is running: Terminal window ``` sudo systemctl status grafana-server ``` 4. Open a browser and go to `http://localhost:3000/`. The default HTTP port that Grafana listens to is `3000` unless you have configured a different port. 5. On the sign-in page, enter your Grafana credentials. To test without an account, you can enter `admin` for both the username and password and skip the password change step. 6. In Grafana, go to **Connections** \> **Data sources**. 7. Select **Add a new data source** and select **Prometheus**. 8. In the **Prometheus server URL** field, enter the IP address and port of your Prometheus dashboard (`http://localhost:9090`). 9. Select **Save & test**. ## Build Grafana dashboard 1. In Grafana, go to **Dashboards** \> **New** \> **New dashboard**. 2. Select **Add visualization**. 3. Select **Prometheus**. 4. In the metrics field, enter `cloudflared_tunnel_total_requests` and select **Run queries**. You will see a graph showing the number of requests as a function of time. ![Grafana dashboard showing a tunnel metrics graph](https://developers.cloudflare.com/_astro/Grafana-dashboard.Bz0eyO9h_ZBdbLa.webp) You can add operations to the queries to modify what is displayed. For example, you could show all tunnel requests over a recent period of time, such as a day, rather than all tunnel requests since metrics began reporting. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/tutorials/","name":"Tutorials"}},{"@type":"ListItem","position":4,"item":{"@id":"/tunnel/tutorials/grafana/","name":"Monitor Cloudflare Tunnel with Grafana"}}]} ``` --- --- title: Downloads description: Cloudflare Tunnel requires the installation of a lightweight daemon, cloudflared, to connect your infrastructure to Cloudflare. If you are creating a tunnel through the dashboard, you can simply copy-paste the installation command shown in the dashboard. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/downloads/index.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Downloads Cloudflare Tunnel requires the installation of a lightweight daemon, `cloudflared`, to connect your infrastructure to Cloudflare. If you are [creating a tunnel through the dashboard](https://developers.cloudflare.com/tunnel/setup/), you can simply copy-paste the installation command shown in the dashboard. To download and install `cloudflared` manually, use one of the following links. ## GitHub repository `cloudflared` is an [open source project ↗](https://github.com/cloudflare/cloudflared) maintained by Cloudflare. * [All releases ↗](https://github.com/cloudflare/cloudflared/releases) * [Release notes ↗](https://github.com/cloudflare/cloudflared/blob/master/RELEASE%5FNOTES) ## Latest release ### Linux You can download and install `cloudflared` via the [Cloudflare Package Repository ↗](https://pkg.cloudflare.com/). Alternatively, download the latest release directly: | Type | amd64 / x86-64 | x86 (32-bit) | ARM | ARM64 | | ------ | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | Binary | [Download ↗](https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64) | [Download ↗](https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-386) | [Download ↗](https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm) | [Download ↗](https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm64) | | .deb | [Download ↗](https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb) | [Download ↗](https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-386.deb) | [Download ↗](https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm.deb) | [Download ↗](https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm64.deb) | | .rpm | [Download ↗](https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-x86%5F64.rpm) | [Download ↗](https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-386.rpm) | [Download ↗](https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm.rpm) | [Download ↗](https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-aarch64.rpm) | ### macOS Download and install `cloudflared` via Homebrew: Terminal window ``` brew install cloudflared ``` Alternatively, download the [latest Darwin arm64 release ↗](https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-darwin-arm64.tgz) or [latest Darwin amd64 release ↗](https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-darwin-amd64.tgz) directly. ### Windows Download and install `cloudflared` via [winget ↗](https://learn.microsoft.com/en-us/windows/package-manager/winget/): Terminal window ``` winget install --id Cloudflare.cloudflared ``` Alternatively, download the latest release directly: | Type | 32-bit | 64-bit | | ---------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | | Executable | [Download ↗](https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-386.exe) | [Download ↗](https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-amd64.exe) | Note Instances of `cloudflared` do not automatically update on Windows. You will need to perform manual updates. ### Docker A Docker image of `cloudflared` is [available on DockerHub ↗](https://hub.docker.com/r/cloudflare/cloudflared). ## Deprecated releases Cloudflare supports versions of `cloudflared` that are within one year of the most recent release. Breaking changes unrelated to feature availability may be introduced that will impact versions released more than one year ago. For example, as of January 2023 Cloudflare will support `cloudflared` version 2023.1.1 to cloudflared 2022.1.1. To update `cloudflared`, refer to [these instructions](https://developers.cloudflare.com/tunnel/downloads/update-cloudflared/). ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/downloads/","name":"Downloads"}}]} ``` --- --- title: System requirements description: cloudflared is lightweight enough to run on a Raspberry Pi or a data center server. Tunnel throughput is primarily limited by the number of ports configured in system software, not hardware. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/downloads/system-requirements.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # System requirements `cloudflared` is lightweight enough to run on a Raspberry Pi or a data center server. Tunnel throughput is primarily limited by the number of ports configured in system software, not hardware. ## Baseline recommendations Run a `cloudflared` [replica](https://developers.cloudflare.com/tunnel/configuration/#replicas-and-high-availability) on two dedicated hosts per location with a minimum of 4 GB RAM and 4 CPU cores. Allocate 50,000 ports per host. ## Port configuration * [ Linux ](#tab-panel-6688) * [ Windows ](#tab-panel-6689) To increase the number of ports available to `cloudflared` on Linux: If your machine has a `/etc/sysctl.d/` directory: Terminal window ``` echo 'net.ipv4.ip_local_port_range = 11000 60999' | sudo tee -a /etc/sysctl.d/99-cloudflared.conf sudo sysctl -p /etc/sysctl.d/99-cloudflared.conf ``` Otherwise: Terminal window ``` echo 'net.ipv4.ip_local_port_range = 11000 60999' | sudo tee -a /etc/sysctl.conf sudo sysctl -p /etc/sysctl.conf ``` To increase the number of ports available to `cloudflared` on Windows, set the [dynamic port range ↗](https://learn.microsoft.com/en-us/troubleshoot/windows-client/networking/tcp-ip-port-exhaustion-troubleshooting) for TCP and UDP: ``` netsh int ipv4 set dynamicport tcp start=11000 num=50000 netsh int ipv4 set dynamicport udp start=11000 num=50000 netsh int ipv6 set dynamicport tcp start=11000 num=50000 netsh int ipv6 set dynamicport udp start=11000 num=50000 ``` ## ulimits (Linux and macOS) On Linux and macOS, `ulimit` settings determine the system resources available to a logged-in user. We recommend configuring the following ulimits on the `cloudflared` server: | ulimit | Description | Value | | ------ | ------------------------------------------------ | -------- | | \-n | Maximum number of open files or file descriptors | ≥ 70,000 | To view your current ulimits, open a terminal and run: Terminal window ``` ulimit -a ``` To set the open files `ulimit`: Terminal window ``` ulimit -n 70000 ``` The command above sets the open files limit only for the current terminal session and will not persist after a reboot or new login. To apply this limit permanently, configure it using the persistent method appropriate for your operating system. ## Capacity calculator To estimate tunnel capacity requirements for your deployment: 1. Use the [metrics endpoint](https://developers.cloudflare.com/tunnel/monitoring/#cloudflared-metrics) to measure `cloudflared_tcp_total_sessions` and `cloudflared_udp_total_sessions`. 2. Compute the average **TCP requests per second** by dividing `cloudflared_tcp_total_sessions` by total time. 3. Compute the average **Non-DNS UDP requests per second** by dividing `cloudflared_udp_total_sessions` by total time. 4. Input **TCP requests per second** and **Non-DNS UDP requests per second** into the calculator below. (You can leave **Private DNS requests per second** as `0` unless you are using the tunnel for [private network access](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/configure-tunnels/tunnel-availability/system-requirements/).) System configuration Available ports per host Number of cloudflared replicas DNS UDP session timeout (in seconds) Average non-DNS UDP session timeout (seconds) Metrics TCP requests per second Non-DNS UDP requests per second Private DNS requests per second Result Percent capacity per replica Percent capacity across all replicas Maximum DNS requests per minute across all replicas This calculator is for informational purposes only and all results are estimates. To increase tunnel capacity, add identical hosts running `cloudflared` replicas. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/downloads/","name":"Downloads"}},{"@type":"ListItem","position":4,"item":{"@id":"/tunnel/downloads/system-requirements/","name":"System requirements"}}]} ``` --- --- title: Update cloudflared description: Updates will cause cloudflared to restart which will impact traffic currently being served. You can perform zero-downtime upgrades by using Cloudflare's Load Balancer product or by using multiple cloudflared instances. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/downloads/update-cloudflared.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Update cloudflared Updates will cause `cloudflared` to restart which will impact traffic currently being served. You can perform zero-downtime upgrades by using Cloudflare's [Load Balancer product](#update-with-cloudflare-load-balancer) or by using [multiple cloudflared instances](#update-with-multiple-cloudflared-instances). ## Update the `cloudflared` service Refer to the following commands to update `cloudflared` for a remotely-managed tunnel or a locally-managed tunnel. Locally-managed tunnels must be set up to [run as a service](https://developers.cloudflare.com/tunnel/other-tunnel-types/local-management/as-a-service/) for the following commands to execute successfully. * [ Windows ](#tab-panel-6690) * [ macOS ](#tab-panel-6691) * [ Debian ](#tab-panel-6692) * [ Red Hat ](#tab-panel-6693) * [ Docker ](#tab-panel-6694) * [ Other ](#tab-panel-6695) Run the following command: PowerShell ``` cloudflared update ``` After running `cloudflared update` to update `cloudflared`, you must restart the service for it to take effect. Run: PowerShell ``` net start cloudflared ``` 1. Update the `cloudflared` package: Terminal window ``` brew upgrade cloudflared ``` 1. Restart the service: Terminal window ``` sudo launchctl stop com.cloudflare.cloudflared sudo launchctl unload /Library/LaunchDaemons/com.cloudflare.cloudflared.plist sudo launchctl load /Library/LaunchDaemons/com.cloudflare.cloudflared.plist sudo launchctl start com.cloudflare.cloudflared ``` **If installed via apt:** 1. Update the `cloudflared` package: Terminal window ``` sudo apt-get update && sudo apt-get install --only-upgrade cloudflared ``` 1. Restart the service: Terminal window ``` sudo systemctl restart cloudflared.service ``` **If installed via `dpkg -i`:** Use the following commands if you installed `cloudflared` using the `dpkg` package manager. You can check if `cloudflared` was installed by a package manager by running `ls -la /usr/local/etc/cloudflared/` and looking for `.installedFromPackageManager` in the output. 1. Update the `cloudflared` package: Terminal window ``` curl --location --output cloudflared.deb "https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-$(dpkg --print-architecture).deb" && sudo dpkg -i cloudflared.deb ``` 1. Restart the service: Terminal window ``` sudo systemctl restart cloudflared.service ``` 1. Update the `cloudflared` package: Terminal window ``` sudo yum update cloudflared ``` 1. Restart the service: Terminal window ``` sudo systemctl restart cloudflared.service ``` **If you created a remotely-managed tunnel using the dashboard:** 1. In [Cloudflare One ↗](https://one.dash.cloudflare.com/), go to **Networks** \> **Connectors** \> **Cloudflare Tunnels**. 2. Select your tunnel and select **Edit**. 3. Select **Docker** and copy the installation command shown in the dashboard. The copied command will contain your token. 4. Paste this command into a terminal window. This command creates a new container from the latest `cloudflared` image. You can now delete the old container. Warning Cloudflare recommends creating remotely-managed tunnels when working with Docker. **If you created a remotely or locally-managed tunnel using the API, run the following command:** Terminal window ``` docker run --pull always cloudflare/cloudflared:latest tunnel --no-autoupdate run --token ``` **If you created a locally-managed tunnel using the CLI:** 1. Mount your local `.cloudflared` directory into the Docker container using a volume. 2. Run the following command to update `cloudflared`: Terminal window ``` docker run --pull always -v :/home/nonroot/.cloudflared cloudflare/cloudflared:latest tunnel --no-autoupdate run ``` If you installed `cloudflared` from GitHub-provided binaries or from source, run the following command: Terminal window ``` cloudflared update ``` If you installed `cloudflared` with a package manager, you must update it using the same package manager. You can check if `cloudflared` was installed by a package manager by running `ls -la /usr/local/etc/cloudflared/` and looking for `.installedFromPackageManager` in the output. ## Update with Cloudflare Load Balancer You can update `cloudflared` without downtime by using Cloudflare's Load Balancer product with your Cloudflare Tunnel deployment. 1. Install a new instance of `cloudflared` and [create](https://developers.cloudflare.com/tunnel/setup/) a new Tunnel. 2. Configure the instance to point traffic to the same locally-available service as your current, active instance of `cloudflared`. 3. [Add the address](https://developers.cloudflare.com/tunnel/routing/#add-a-tunnel-to-a-load-balancer-pool) of the new instance of `cloudflared` into your Load Balancer pool as priority 2. 4. Swap the priority such that the new instance is now priority 1 and monitor to confirm traffic is being served. 5. Once confirmed, you can remove the older version from the Load Balancer pool. ## Update with multiple `cloudflared` instances If you are not using Cloudflare's Load Balancer, you can use multiple instances of `cloudflared` to update without the risk of downtime. 1. Install a new instance of `cloudflared` and [create](https://developers.cloudflare.com/tunnel/setup/) a new Tunnel. 2. Configure the instance to point traffic to the same locally-available service as your current, active instance of `cloudflared`. 3. In the Cloudflare DNS dashboard, [replace](https://developers.cloudflare.com/tunnel/routing/#dns-records) the address of the current instance of `cloudflared` with the address of the new instance. Save the record. 4. Remove the now-inactive instance of `cloudflared`. Traffic handling When the old replica is stopped, it will drop long-lived HTTP requests (for example, WebSocket) and TCP connections (for example, SSH). UDP flows will also be dropped, as they are modeled based on timeouts. When the new replica connects, it will handle all new traffic, including new HTTP requests, TCP connections, and UDP flows. ### Run multiple instances in Windows Windows systems require services to have a unique name and display name. You can run multiple instances of `cloudflared` by creating `cloudflared` services with unique names. 1. Install and configure `cloudflared`. 2. Next, create a service with a unique name and point to the `cloudflared` executable and configuration file. PowerShell ``` sc.exe create binPath='' --config '' displayname="Unique Name" ``` 1. Proceed to create additional services with unique names. 2. You can now start each unique service. PowerShell ``` sc.exe start ``` ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/downloads/","name":"Downloads"}},{"@type":"ListItem","position":4,"item":{"@id":"/tunnel/downloads/update-cloudflared/","name":"Update cloudflared"}}]} ``` --- --- title: Changelog description: Review recent changes to Cloudflare Tunnel. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/changelog.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Changelog [ Subscribe to RSS ](https://developers.cloudflare.com/changelog/rss/tunnel.xml) ## 2026-03-20 **Stream logs from multiple replicas of Cloudflare Tunnel simultaneously** In the Cloudflare One dashboard, the overview page for a specific Cloudflare Tunnel now shows all [replicas](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/configure-tunnels/tunnel-availability/) of that tunnel and supports streaming logs from multiple replicas at once. ![View replicas and stream logs from multiple connectors](https://developers.cloudflare.com/_astro/tunnel-multiconn.DEOEaLlu_ZDxArh.webp) Previously, you could only stream logs from one replica at a time. With this update: * **Replicas on the tunnel overview** — All active replicas for the selected tunnel now appear on that tunnel's overview page under **Connectors**. Select any replica to stream its logs. * **Multi-connector log streaming** — Stream logs from multiple replicas simultaneously, making it easier to correlate events across your infrastructure during debugging or incident response. To try it out, log in to [Cloudflare One ↗](https://one.dash.cloudflare.com/) and go to **Networks** \> **Connectors** \> **Cloudflare Tunnels**. Select **View logs** next to the tunnel you want to monitor. For more information, refer to [Tunnel log streams](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/monitor-tunnels/logs/) and [Deploy replicas](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/configure-tunnels/tunnel-availability/deploy-replicas/). ## 2026-03-19 **Manage Cloudflare Tunnels with Wrangler** You can now manage [Cloudflare Tunnels](https://developers.cloudflare.com/tunnel/) directly from [Wrangler](https://developers.cloudflare.com/workers/wrangler/), the CLI for the Cloudflare Developer Platform. The new [wrangler tunnel](https://developers.cloudflare.com/workers/wrangler/commands/tunnel/) commands let you create, run, and manage tunnels without leaving your terminal. ![Wrangler tunnel commands demo](https://developers.cloudflare.com/_astro/wrangler-tunnel.DOqrtGGg_7EDX0.webp) Available commands: * `wrangler tunnel create` — Create a new remotely managed tunnel. * `wrangler tunnel list` — List all tunnels in your account. * `wrangler tunnel info` — Display details about a specific tunnel. * `wrangler tunnel delete` — Delete a tunnel. * `wrangler tunnel run` — Run a tunnel using the cloudflared daemon. * `wrangler tunnel quick-start` — Start a free, temporary tunnel without an account using [Quick Tunnels](https://developers.cloudflare.com/tunnel/setup/#quick-tunnels-development). Wrangler handles downloading and managing the [cloudflared](https://developers.cloudflare.com/tunnel/downloads/) binary automatically. On first use, you will be prompted to download `cloudflared` to a local cache directory. These commands are currently experimental and may change without notice. To get started, refer to the [Wrangler tunnel commands documentation](https://developers.cloudflare.com/workers/wrangler/commands/tunnel/). ## 2026-02-20 **Manage Cloudflare Tunnel directly from the main Cloudflare Dashboard** [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/) is now available in the main Cloudflare Dashboard at [Networking > Tunnels ↗](https://dash.cloudflare.com/?to=/:account/tunnels), bringing first-class Tunnel management to developers using Tunnel for securing origin servers. ![Manage Tunnels in the Core Dashboard](https://developers.cloudflare.com/_astro/tunnel-core-dashboard.BGPqaHfo_Pi6HO.webp) This new experience provides everything you need to manage Tunnels for [public applications](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/routing-to-tunnel/), including: * **Full Tunnel lifecycle management**: Create, configure, delete, and monitor all your Tunnels in one place. * **Native integrations**: View Tunnels by name when configuring [DNS records](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/) and [Workers VPC](https://developers.cloudflare.com/workers-vpc/) — no more copy-pasting UUIDs. * **Real-time visibility**: Monitor [replicas](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/configure-tunnels/tunnel-availability/) and Tunnel [health status](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/troubleshoot-tunnels/common-errors/#tunnel-status) directly in the dashboard. * **Routing map**: Manage all ingress routes for your Tunnel, including [public applications](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/routing-to-tunnel/), [private hostnames](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/cloudflared/connect-private-hostname/), [private CIDRs](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/cloudflared/connect-cidr/), and [Workers VPC services](https://developers.cloudflare.com/workers-vpc/), from a single interactive interface. #### Choose the right dashboard for your use case **Core Dashboard**: Navigate to [Networking > Tunnels ↗](https://dash.cloudflare.com/?to=/:account/tunnels) to manage Tunnels for: * Securing origin servers and [public applications](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/routing-to-tunnel/) with CDN, WAF, Load Balancing, and DDoS protection * Connecting [Workers to private services](https://developers.cloudflare.com/workers-vpc/) via Workers VPC **Cloudflare One Dashboard**: Navigate to [Zero Trust > Networks > Connectors ↗](https://one.dash.cloudflare.com/?to=/:account/networks/connectors) to manage Tunnels for: * Securing your public applications with [Zero Trust access policies](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/self-hosted-public-app/) * Connecting users to [private applications](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/non-http/self-hosted-private-app/) * Building a [private mesh network](https://developers.cloudflare.com/reference-architecture/architectures/sase/#connecting-networks) Both dashboards provide complete Tunnel management capabilities — choose based on your primary workflow. #### Get started New to Tunnel? Learn how to [get started with Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/) or explore advanced use cases like [securing SSH servers](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/use-cases/ssh/) or [running Tunnels in Kubernetes](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/deployment-guides/kubernetes/). ## 2026-01-15 **Verify WARP Connector connectivity with a simple ping** We have made it easier to validate connectivity when deploying [WARP Connector](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/warp-connector/) as part of your [software-defined private network](https://developers.cloudflare.com/reference-architecture/architectures/sase/#connecting-networks). You can now `ping` the WARP Connector host directly on its LAN IP address immediately after installation. This provides a fast, familiar way to confirm that the Connector is online and reachable within your network before testing access to downstream services. Starting with [version 2025.10.186.0](https://developers.cloudflare.com/changelog/2026-01-13-warp-linux-ga/), WARP Connector responds to traffic addressed to its own LAN IP, giving you immediate visibility into Connector reachability. Learn more about deploying [WARP Connector](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/warp-connector/) and building private network connectivity with [Cloudflare One](https://developers.cloudflare.com/cloudflare-one/). ## 2025-11-11 **cloudflared proxy-dns command will be removed starting February 2, 2026** Starting February 2, 2026, the `cloudflared proxy-dns` command will be removed from all new `cloudflared` [releases](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/). This change is being made to enhance security and address a potential vulnerability in an underlying DNS library. This vulnerability is specific to the `proxy-dns` command and does not affect any other `cloudflared` features, such as the core [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/) service. The `proxy-dns` command, which runs a client-side [DNS-over-HTTPS (DoH)](https://developers.cloudflare.com/1.1.1.1/encryption/dns-over-https/) proxy, has been an officially undocumented feature for several years. This functionality is fully and securely supported by our actively developed products. Versions of `cloudflared` released before this date will not be affected and will continue to operate. However, note that our [official support policy](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/#deprecated-releases) for any `cloudflared` release is one year from its release date. #### Migration paths We strongly advise users of this undocumented feature to migrate to one of the following officially supported solutions before February 2, 2026, to continue benefiting from secure [DNS-over-HTTPS](https://developers.cloudflare.com/1.1.1.1/encryption/dns-over-https/). #### End-user devices The preferred method for enabling DNS-over-HTTPS on user devices is the [Cloudflare WARP client](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/). The WARP client automatically secures and proxies all DNS traffic from your device, integrating it with your organization's [Zero Trust policies](https://developers.cloudflare.com/cloudflare-one/traffic-policies/) and [posture checks](https://developers.cloudflare.com/cloudflare-one/reusable-components/posture-checks/). #### Servers, routers, and IoT devices For scenarios where installing a client on every device is not possible (such as servers, routers, or IoT devices), we recommend using the [WARP Connector](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/warp-connector/). Instead of running `cloudflared proxy-dns` on a machine, you can install the WARP Connector on a single Linux host within your private network. This connector will act as a gateway, securely routing all DNS and network traffic from your [entire subnet](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/warp-connector/site-to-internet/) to Cloudflare for [filtering and logging](https://developers.cloudflare.com/cloudflare-one/traffic-policies/). ## 2025-09-18 **Connect and secure any private or public app by hostname, not IP — with hostname routing for Cloudflare Tunnel** You can now route private traffic to [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/) based on a hostname or domain, moving beyond the limitations of IP-based routing. This new capability is **free for all Cloudflare One customers**. Previously, Tunnel routes could only be defined by IP address or [CIDR range](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/cloudflared/connect-cidr/). This created a challenge for modern applications with dynamic or ephemeral IP addresses, often forcing administrators to maintain complex and brittle IP lists. ![Hostname-based routing in Cloudflare Tunnel](https://developers.cloudflare.com/_astro/tunnel-hostname-routing.DSi8MP_7_Z1E6Ym4.webp) **What’s new:** * **Hostname & Domain Routing**: Create routes for individual hostnames (e.g., `payroll.acme.local`) or entire domains (e.g., `*.acme.local`) and direct their traffic to a specific Tunnel. * **Simplified Zero Trust Policies**: Build resilient policies in Cloudflare Access and Gateway using stable hostnames, making it dramatically easier to apply per-resource authorization for your private applications. * **Precise Egress Control**: Route traffic for public hostnames (e.g., `bank.example.com`) through a specific Tunnel to enforce a dedicated source IP, solving the IP allowlist problem for third-party services. * **No More IP Lists**: This feature makes the workaround of maintaining dynamic IP Lists for Tunnel connections obsolete. Get started in the Tunnels section of the Zero Trust dashboard with your first [private hostname](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/cloudflared/connect-private-hostname/) or [public hostname](https://developers.cloudflare.com/cloudflare-one/traffic-policies/egress-policies/egress-cloudflared/) route. Learn more in our [blog post ↗](https://blog.cloudflare.com/tunnel-hostname-routing/). ## 2025-09-02 **Cloudflare Tunnel and Networks API will no longer return deleted resources by default starting December 1, 2025** Starting **December 1, 2025**, list endpoints for the [Cloudflare Tunnel API](https://developers.cloudflare.com/api/resources/zero%5Ftrust/subresources/tunnels/) and [Zero Trust Networks API](https://developers.cloudflare.com/api/resources/zero%5Ftrust/subresources/networks/) will no longer return deleted tunnels, routes, subnets and virtual networks by default. This change makes the API behavior more intuitive by only returning active resources unless otherwise specified. No action is required if you already explicitly set `is_deleted=false` or if you only need to list active resources. This change affects the following API endpoints: * List all tunnels: [GET /accounts/{account\_id}/tunnels](https://developers.cloudflare.com/api/resources/zero%5Ftrust/subresources/tunnels/methods/list/) * List [Cloudflare Tunnels](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/): [GET /accounts/{account\_id}/cfd\_tunnel](https://developers.cloudflare.com/api/resources/zero%5Ftrust/subresources/tunnels/subresources/cloudflared/methods/list/) * List [WARP Connector](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/warp-connector/) tunnels: [GET /accounts/{account\_id}/warp\_connector](https://developers.cloudflare.com/api/resources/zero%5Ftrust/subresources/tunnels/subresources/warp%5Fconnector/methods/list/) * List tunnel routes: [GET /accounts/{account\_id}/teamnet/routes](https://developers.cloudflare.com/api/resources/zero%5Ftrust/subresources/networks/subresources/routes/methods/list/) * List subnets: [GET /accounts/{account\_id}/zerotrust/subnets](https://developers.cloudflare.com/api/resources/zero%5Ftrust/subresources/networks/subresources/subnets/methods/list/) * List virtual networks: [GET /accounts/{account\_id}/teamnet/virtual\_networks](https://developers.cloudflare.com/api/resources/zero%5Ftrust/subresources/networks/subresources/virtual%5Fnetworks/methods/list/) #### What is changing? The default behavior of the `is_deleted` query parameter will be updated. | Scenario | Previous behavior (before December 1, 2025) | New behavior (from December 1, 2025) | | -------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------- | | is\_deleted parameter is omitted | Returns **active & deleted** tunnels, routes, subnets and virtual networks | Returns **only active** tunnels, routes, subnets and virtual networks | #### Action required If you need to retrieve deleted (or all) resources, please update your API calls to explicitly include the `is_deleted` parameter before **December 1, 2025**. To get a list of only deleted resources, you must now explicitly add the `is_deleted=true` query parameter to your request: Terminal window ``` # Example: Get ONLY deleted Tunnels curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tunnels?is_deleted=true" \ -H "Authorization: Bearer $API_TOKEN" # Example: Get ONLY deleted Virtual Networks curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/teamnet/virtual_networks?is_deleted=true" \ -H "Authorization: Bearer $API_TOKEN" ``` Following this change, retrieving a complete list of both active and deleted resources will require two separate API calls: one to get active items (by omitting the parameter or using `is_deleted=false`) and one to get deleted items (`is_deleted=true`). #### Why we’re making this change This update is based on user feedback and aims to: * **Create a more intuitive default:** Aligning with common API design principles where list operations return only active resources by default. * **Reduce unexpected results:** Prevents users from accidentally operating on deleted resources that were returned unexpectedly. * **Improve performance:** For most users, the default query result will now be smaller and more relevant. To learn more, please visit the [Cloudflare Tunnel API](https://developers.cloudflare.com/api/resources/zero%5Ftrust/subresources/tunnels/) and [Zero Trust Networks API](https://developers.cloudflare.com/api/resources/zero%5Ftrust/subresources/networks/) documentation. ## 2025-07-15 **Faster, more reliable UDP traffic for Cloudflare Tunnel** Your real-time applications running over [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/) are now faster and more reliable. We've completely re-architected the way `cloudflared` proxies UDP traffic in order to isolate it from other traffic, ensuring latency-sensitive applications like private DNS are no longer slowed down by heavy TCP traffic (like file transfers) on the same Tunnel. This is a foundational improvement to Cloudflare Tunnel, delivered automatically to all customers. There are no settings to configure — your UDP traffic is already flowing faster and more reliably. **What’s new:** * **Faster UDP performance**: We've significantly reduced the latency for establishing new UDP sessions, making applications like private DNS much more responsive. * **Greater reliability for mixed traffic**: UDP packets are no longer affected by heavy TCP traffic, preventing timeouts and connection drops for your real-time services. Learn more about running [TCP or UDP applications](https://developers.cloudflare.com/reference-architecture/architectures/sase/#connecting-applications) and [private networks](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/) through [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/). ## 2024-12-19 **Troubleshoot tunnels with diagnostic logs** The latest `cloudflared` build [2024.12.2 ↗](https://github.com/cloudflare/cloudflared/releases/tag/2024.12.2) introduces the ability to collect all the diagnostic logs needed to troubleshoot a `cloudflared` instance. A diagnostic report collects data from a single instance of `cloudflared` running on the local machine and outputs it to a `cloudflared-diag` file. For more information, refer to [Diagnostic logs](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/troubleshoot-tunnels/diag-logs/). ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/changelog/","name":"Changelog"}}]} ``` --- --- title: Linux description: You can install cloudflared as a system service on Linux. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/advanced/local-management/as-a-service/linux.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Linux You can install `cloudflared` as a system service on Linux. ## Prerequisites Before you install Cloudflare Tunnel as a service on Linux, follow Steps 1 through 4 of the [Tunnel CLI setup guide](https://developers.cloudflare.com/tunnel/other-tunnel-types/local-management/create-local-tunnel/). At this point you should have a named tunnel and a `config.yml` file in your `.cloudflared` directory. ## 1\. Configure `cloudflared` as a service By default, Cloudflare Tunnel expects all of the configuration to exist in the `$HOME/.cloudflared/config.yml` [configuration file](https://developers.cloudflare.com/tunnel/other-tunnel-types/local-management/configuration-file/). At a minimum you must specify the following arguments to run as a service: | Argument | Description | | ---------------- | ---------------------------------------------------- | | tunnel | The UUID of your tunnel | | credentials-file | The location of the credentials file for your Tunnel | ## 2\. Run `cloudflared` as a service 1. Install the `cloudflared` service. Terminal window ``` cloudflared service install ``` Note Installing the `cloudflared` systemd service on Linux typically requires elevated privileges. When the install command is run with `sudo`, `$HOME` points to `/root`, which may prevent `cloudflared` from locating a configuration file created in `/home//.cloudflared/config.yml`. In this case, the config path can be passed explicitly: Terminal window ``` sudo cloudflared --config /home//.cloudflared/config.yml service install ``` 2. Start the service. Terminal window ``` systemctl start cloudflared ``` 3. (Optional) View the status of the service. Terminal window ``` systemctl status cloudflared ``` ## Next steps You can now [route traffic through your tunnel](https://developers.cloudflare.com/tunnel/other-tunnel-types/local-management/create-local-tunnel/#5-start-routing-traffic). If you add IP routes or otherwise change the configuration, restart the service to load the new configuration: Terminal window ``` systemctl restart cloudflared ``` ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/advanced/","name":"Advanced"}},{"@type":"ListItem","position":4,"item":{"@id":"/tunnel/advanced/local-management/","name":"Locally-managed tunnels"}},{"@type":"ListItem","position":5,"item":{"@id":"/tunnel/advanced/local-management/as-a-service/","name":"Run as a service"}},{"@type":"ListItem","position":6,"item":{"@id":"/tunnel/advanced/local-management/as-a-service/linux/","name":"Linux"}}]} ``` --- --- title: macOS description: You can install cloudflared as a system service on macOS. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/advanced/local-management/as-a-service/macos.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # macOS You can install `cloudflared` as a system service on macOS. ## Prerequisites Before you install Cloudflare Tunnel as a service on your OS, follow Steps 1 through 4 of the [Tunnel CLI setup guide](https://developers.cloudflare.com/tunnel/other-tunnel-types/local-management/create-local-tunnel/). At this point you should have a named tunnel and a `config.yml` file in your `$HOME/.cloudflared` directory. ## 1\. Configure `cloudflared` as a service By default, Cloudflare Tunnel expects all of the configuration to exist in the `$HOME/.cloudflared/config.yml` [configuration file](https://developers.cloudflare.com/tunnel/other-tunnel-types/local-management/configuration-file/). At a minimum you must specify the following arguments to run as a service: | Argument | Description | | ---------------- | ---------------------------------------------------- | | tunnel | The UUID of your tunnel | | credentials-file | The location of the credentials file for your tunnel | ## 2\. Run `cloudflared` as a service You can install the service to either run at login or at boot. ### Run at login Open a terminal window and run the following command: Terminal window ``` cloudflared service install ``` Cloudflare Tunnel will be installed as a launch agent and start whenever you log in, using your local user configuration found in `~/.cloudflared/`. ### Run at boot Open a terminal window and run the following command: Terminal window ``` sudo cloudflared service install ``` Cloudflare Tunnel will be installed as a launch daemon and start whenever your system boots, using your configuration found in `/etc/cloudflared`. ## 3\. Manually start the service Run the following command: Terminal window ``` sudo launchctl start com.cloudflare.cloudflared ``` The output will be logged to `/Library/Logs/com.cloudflare.cloudflared.err.log` and `/Library/Logs/com.cloudflare.cloudflared.out.log`. ## Next steps You can now [route traffic through your tunnel](https://developers.cloudflare.com/tunnel/other-tunnel-types/local-management/create-local-tunnel/#5-start-routing-traffic). If you add IP routes or otherwise change the configuration, restart the service to load the new configuration: Terminal window ``` sudo launchctl stop com.cloudflare.cloudflared sudo launchctl start com.cloudflare.cloudflared ``` ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/advanced/","name":"Advanced"}},{"@type":"ListItem","position":4,"item":{"@id":"/tunnel/advanced/local-management/","name":"Locally-managed tunnels"}},{"@type":"ListItem","position":5,"item":{"@id":"/tunnel/advanced/local-management/as-a-service/","name":"Run as a service"}},{"@type":"ListItem","position":6,"item":{"@id":"/tunnel/advanced/local-management/as-a-service/macos/","name":"macOS"}}]} ``` --- --- title: Windows description: You can install cloudflared as a system service on Windows. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/advanced/local-management/as-a-service/windows.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Windows You can install `cloudflared` as a system service on Windows. ## Configure `cloudflared` as a service By default, Cloudflare Tunnel expects all of the configuration to exist in the `%USERPROFILE%\.cloudflared\config.yml` [configuration file](https://developers.cloudflare.com/tunnel/other-tunnel-types/local-management/configuration-file/). At a minimum you must specify the following arguments to run as a service: | Argument | Description | | ---------------- | ---------------------------------------------------- | | tunnel | The UUID of your tunnel | | credentials-file | The location of the credentials file for your tunnel | ## Run `cloudflared` as a service 1. [Download](https://developers.cloudflare.com/tunnel/downloads/) the latest `cloudflared` version. 2. Create a new directory: Terminal window ``` C:\Cloudflared\bin ``` 3. Copy the `.exe` file you downloaded in step 1 to the new directory and rename it to `cloudflared.exe`. 4. Open CMD as an administrator and go to `C:\Cloudflared\bin`. 5. Run this command to install `cloudflared`: Terminal window ``` cloudflared.exe service install ``` 6. Next, run this command to create another directory: Terminal window ``` mkdir C:\Windows\System32\config\systemprofile\.cloudflared ``` 7. Log in and authenticate `cloudflared`: Terminal window ``` cloudflared.exe login ``` 8. The login command will generate a `cert.pem` file and save it to your user profile by default. Copy the file to the `.cloudflared` folder created in step 5 using this command: Terminal window ``` copy C:\Users\%USERNAME%\.cloudflared\cert.pem C:\Windows\System32\config\systemprofile\.cloudflared\cert.pem ``` 9. Next, create a tunnel: Terminal window ``` cloudflared.exe tunnel create ``` This will generate a [credentials file](https://developers.cloudflare.com/tunnel/other-tunnel-types/local-management/local-tunnel-terms/#credentials-file) in `.json` format. 10. [Create a configuration file](https://developers.cloudflare.com/tunnel/other-tunnel-types/local-management/create-local-tunnel/#4-create-a-configuration-file) with the following content: ``` tunnel: credentials-file: C:\Windows\System32\config\systemprofile\.cloudflared\.json # Uncomment the following two lines if you are using self-signed certificates in your origin server # originRequest: # noTLSVerify: true ingress: - hostname: app.mydomain.com service: https://internal.mydomain.com - service: http_status:404 logfile: C:\Cloudflared\cloudflared.log ``` 11. Copy the credentials file to the folder created in step 6: Terminal window ``` copy C:\Users\%USERNAME%\.cloudflared\.json C:\Windows\System32\config\systemprofile\.cloudflared\.json ``` 12. Validate the ingress rule entries in your configuration file using the command: Terminal window ``` cloudflared.exe tunnel ingress validate ``` 13. In the Registry Editor, go to `Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Cloudflared`. 14. In the Cloudflared registry entry, modify `ImagePath` to point to the `cloudflared.exe` and `config.yml` files. Make sure that there are no extra spaces or characters while you modify the registry entry, as this could cause problems with starting the service. Terminal window ``` C:\Cloudflared\bin\cloudflared.exe --config=C:\Windows\System32\config\systemprofile\.cloudflared\config.yml tunnel run ``` 15. If the service does not start, run the following command from `C:\Cloudflared\bin`: Terminal window ``` sc start cloudflared ``` You will see the output below: ``` SERVICE_NAME: cloudflared TYPE : 10 WIN32_OWN_PROCESS STATE : 2 START_PENDING (NOT_STOPPABLE, NOT_PAUSABLE, IGNORES_SHUTDOWN) WIN32_EXIT_CODE : 0 (0x0) SERVICE_EXIT_CODE : 0 (0x0) CHECKPOINT : 0x0 WAIT_HINT : 0x7d0 PID : 3548 FLAGS : ``` ## Next steps You can now [route traffic through your tunnel](https://developers.cloudflare.com/tunnel/other-tunnel-types/local-management/create-local-tunnel/#5-start-routing-traffic). If you add IP routes or otherwise change the configuration, restart the service to load the new configuration: Terminal window ``` sc stop cloudflared sc start cloudflared ``` ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/advanced/","name":"Advanced"}},{"@type":"ListItem","position":4,"item":{"@id":"/tunnel/advanced/local-management/","name":"Locally-managed tunnels"}},{"@type":"ListItem","position":5,"item":{"@id":"/tunnel/advanced/local-management/as-a-service/","name":"Run as a service"}},{"@type":"ListItem","position":6,"item":{"@id":"/tunnel/advanced/local-management/as-a-service/windows/","name":"Windows"}}]} ``` --- --- title: Configuration file description: Locally-managed tunnels run as an instance of cloudflared on your machine. You can configure cloudflared properties by modifying command line parameters or by editing the tunnel configuration file. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/advanced/local-management/configuration-file.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Configuration file Note [Quick tunnels](https://developers.cloudflare.com/tunnel/faq/#quick-tunnels) do not need a configuration file. Locally-managed tunnels run as an instance of `cloudflared` on your machine. You can configure `cloudflared` properties by modifying [command line parameters](https://developers.cloudflare.com/tunnel/configuration/#run-parameters) or by editing the tunnel [configuration file](https://developers.cloudflare.com/tunnel/other-tunnel-types/local-management/create-local-tunnel/#4-create-a-configuration-file). The CLI provides a quick way to handle configurations if you are connecting a single service through `cloudflared`. The tunnel configuration file is useful if you are connecting multiple services and need to configure properties or exceptions for specific origins. In the configuration file, you can define top-level properties for your `cloudflared` instance as well as [origin-specific properties](https://developers.cloudflare.com/tunnel/configuration/#origin-parameters). For a full list of configuration options, type `cloudflared tunnel help` in your terminal. In the absence of a configuration file, `cloudflared` will proxy outbound traffic through port `8080`. ## File structure for published applications If you are exposing local services to the Internet, you can assign a public hostname to each service: ``` tunnel: 6ff42ae2-765d-4adf-8112-31c55c1551ef credentials-file: /root/.cloudflared/6ff42ae2-765d-4adf-8112-31c55c1551ef.json ingress: - hostname: gitlab.widgetcorp.tech service: http://localhost:80 - hostname: gitlab-ssh.widgetcorp.tech service: ssh://localhost:22 - service: http_status:404 ``` Configuration files that contain ingress rules must always include a catch-all rule that concludes the file. In this example, `cloudflared` will respond with a `404` status code when the request does not match any of the previous hostnames. ### How traffic is matched When `cloudflared` receives an incoming request, it evaluates each ingress rule from top to bottom to find which rule matches the request. Rules can match either the hostname or path of an incoming request, or both. If a rule does not specify a hostname, all hostnames will be matched. If a rule does not specify a path, all paths will be matched. The last ingress rule must be a catch-all rule that matches all traffic. Here is an example configuration file that specifies several rules: ``` tunnel: 6ff42ae2-765d-4adf-8112-31c55c1551ef credentials-file: /root/.cloudflared/6ff42ae2-765d-4adf-8112-31c55c1551ef.json ingress: # Rules map traffic from a hostname to a local service: - hostname: example.com service: https://localhost:8000 # Rules can match the request's path to a regular expression: - hostname: static.example.com path: \.(jpg|png|css|js)$ service: https://localhost:8001 # Rules can match the request's hostname to a wildcard character: - hostname: "*.example.com" service: https://localhost:8002 # An example of a catch-all rule: - service: https://localhost:8003 ``` #### Wildcards You can use wildcards to match traffic to multiple subdomains. For example, if you set the `hostname` key to `*.example.com`, both `alpha.example.com` and `beta.example.com` will route traffic to your origin. `cloudflared` does not support wildcards in the middle of the hostname, such as `test.*.example.com`. You can also enter regular expressions for the `path` key. For example, if `hostname` is `static.example.com` and `path` is `\.(jpg|png|css|js)$`, matching URLs could include `https://static.example.com/data.js`, `http://static.example.com/images/photo.jpg`, and so on. Cloudflare parses the path regex using the [Go syntax package ↗](https://pkg.go.dev/regexp/syntax). ### Services In addition to HTTP, `cloudflared` supports protocols like SSH, RDP, arbitrary TCP services, and Unix sockets. You can also route traffic to the built-in `hello_world` test server or respond to traffic with an HTTP status. For a full list of supported service types, refer to [Protocols for published applications](https://developers.cloudflare.com/tunnel/routing/#supported-protocols). ``` tunnel: 6ff42ae2-765d-4adf-8112-31c55c1551ef credentials-file: /root/.cloudflared/6ff42ae2-765d-4adf-8112-31c55c1551ef.json ingress: # Example of a request over TCP: - hostname: example.com service: tcp://localhost:8000 # Example of an HTTP request over a Unix socket: - hostname: staging.example.com service: unix:/home/production/echo.sock # Example of a request mapping to the Hello World test server: - hostname: test.example.com service: hello_world # Example of a rule responding to traffic with an HTTP status: - service: http_status:404 ``` ### Origin configuration If you need to proxy traffic to multiple origins within one instance of `cloudflared`, you can define the way `cloudflared` sends requests to each service by specifying [configuration options](https://developers.cloudflare.com/tunnel/configuration/#origin-parameters) as part of your ingress rules. In the following example, the top-level configuration `connectTimeout: 30s` sets a 30-second connection timeout for all services within that instance of `cloudflared`. The ingress rule for `service: localhost:8002` then configures an exception to the top-level configuration by setting `connectTimeout` for that service at `10s`. The 30-second connection timeout still applies to all other services. ``` tunnel: 6ff42ae2-765d-4adf-8112-31c55c1551ef credentials-file: /root/.cloudflared/6ff42ae2-765d-4adf-8112-31c55c1551ef.json originRequest: # Top-level configuration connectTimeout: 30s ingress: # The localhost:8000 service inherits all root-level configuration. # In other words, it will use a connectTimeout of 30 seconds. - hostname: example.com service: localhost:8000 - hostname: example2.com service: localhost:8001 # The localhost:8002 service overrides some root-level config. - service: localhost:8002 originRequest: connectTimeout: 10s disableChunkedEncoding: true # Some built-in services such as `http_status` do not use any configuration. # The service below will simply respond with HTTP 404. - service: http_status:404 ``` ### Validate ingress rules To validate the ingress rules in your configuration file, run: Terminal window ``` cloudflared tunnel ingress validate ``` This will ensure that the set of ingress rules specified in your config file is valid. ### Test ingress rules To verify that `cloudflared` will proxy the right traffic to the right local service, use `cloudflared tunnel ingress rule`. This checks a URL against every rule, from first to last, and shows the first rule that matches. For example: Terminal window ``` cloudflared tunnel ingress rule https://foo.example.com ``` ``` Using rules from /usr/local/etc/cloudflared/config.yml Matched rule #3 hostname: *.example.com service: https://localhost:8000 ``` ## Update a configuration file When making changes to the configuration file for a given tunnel, we suggest relying on [cloudflared replicas](https://developers.cloudflare.com/tunnel/configuration/#replicas-and-high-availability) to propagate the new configuration with minimal downtime. 1. Have a `cloudflared` instance running with the original version of the configuration file. 2. Start a `cloudflared` replica running with the updated version of the configuration file. 3. Wait for the replica to be fully running and usable. 4. Stop the first instance of `cloudflared`. Your `cloudflared` will now be running with the updated version of your configuration file. Traffic handling When the first instance of `cloudflared` is stopped, long-lived HTTP requests (for example, Websocket) and TCP connections (for example, SSH) will be dropped. UDP flows will also be dropped, as they are modeled based on timeouts. When the new replica connects, it will handle all new traffic, including new HTTP requests, TCP connections, and UDP flows. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/advanced/","name":"Advanced"}},{"@type":"ListItem","position":4,"item":{"@id":"/tunnel/advanced/local-management/","name":"Locally-managed tunnels"}},{"@type":"ListItem","position":5,"item":{"@id":"/tunnel/advanced/local-management/configuration-file/","name":"Configuration file"}}]} ``` --- --- title: Create a locally-managed tunnel description: Follow this step-by-step guide to get your first tunnel up and running using the CLI. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/advanced/local-management/create-local-tunnel.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Create a locally-managed tunnel Follow this step-by-step guide to get your first tunnel up and running using the CLI. ## Prerequisites Before you start, make sure you: * [Add a website to Cloudflare](https://developers.cloudflare.com/fundamentals/manage-domains/add-site/). * [Change your domain nameservers to Cloudflare](https://developers.cloudflare.com/dns/zone-setups/full-setup/setup/). ## 1\. Download and install `cloudflared` * [ Windows ](#tab-panel-6670) * [ macOS ](#tab-panel-6671) * [ Linux ](#tab-panel-6672) * [ Build from source ](#tab-panel-6673) 1. Download `cloudflared` on your machine. Visit the [downloads](https://developers.cloudflare.com/tunnel/downloads/) page to find the right package for your OS. 2. Rename the executable to `cloudflared.exe` 3. In PowerShell, change directory to your Downloads folder and run `.\cloudflared.exe --version`. It should output the version of `cloudflared`. Note that `cloudflared.exe` could be `cloudflared-windows-amd64.exe` or `cloudflared-windows-386.exe` if you have not renamed it. PowerShell ``` PS C:\Users\Administrator\Downloads\cloudflared-stable-windows-amd64> .\cloudflared.exe --version ``` To download and install `cloudflared`: Terminal window ``` brew install cloudflared ``` Alternatively, you can [download the latest Darwin amd64 release](https://developers.cloudflare.com/tunnel/downloads/) directly. **Debian and Ubuntu APT** Use the apt package manager to install `cloudflared` on compatible machines. 1. Add Cloudflare's package signing key: Terminal window ``` sudo mkdir -p --mode=0755 /usr/share/keyrings curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null ``` 1. Add Cloudflare's apt repo to your apt repositories: Terminal window ``` echo "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared any main" | sudo tee /etc/apt/sources.list.d/cloudflared.list ``` 1. Update repositories and install cloudflared: Terminal window ``` sudo apt-get update && sudo apt-get install cloudflared ``` **RHEL RPM** Use the rpm package manager to install `cloudflared` on compatible machines. 1. Add Cloudflare's repository: Terminal window ``` curl -fsSl https://pkg.cloudflare.com/cloudflared.repo | sudo tee /etc/yum.repos.d/cloudflared.repo ``` 2. Update repositories and install cloudflared: Terminal window ``` sudo yum update && sudo yum install cloudflared ``` **Arch Linux** `cloudflared` is in the Arch Linux [community repository ↗](https://wiki.archlinux.org/title/official%5Frepositories#community). Use `pacman` to install `cloudflared` on compatible machines. Terminal window ``` pacman -Syu cloudflared ``` **Other** Alternatively you can download the `cloudflared` binary or the linux packages to your machine and install manually. Visit the [downloads](https://developers.cloudflare.com/tunnel/downloads/) page to find the right package for your OS. To build the latest version of `cloudflared` from source: Terminal window ``` git clone https://github.com/cloudflare/cloudflared.git cd cloudflared make cloudflared go install github.com/cloudflare/cloudflared/cmd/cloudflared ``` Depending on where you installed `cloudflared`, you can move it to a known path as well. Terminal window ``` mv /root/cloudflared/cloudflared /usr/bin/cloudflared ``` ## 2\. Authenticate `cloudflared` Terminal window ``` cloudflared tunnel login ``` Running this command will: * Open a browser window and prompt you to log in to your Cloudflare account. After logging in to your account, select your hostname. * Generate an account certificate, the [cert.pem file](https://developers.cloudflare.com/tunnel/advanced/local-management/local-tunnel-terms/#certpem), in the [default cloudflared directory](https://developers.cloudflare.com/tunnel/advanced/local-management/local-tunnel-terms/#default-cloudflared-directory). ## 3\. Create a tunnel and give it a name Terminal window ``` cloudflared tunnel create ``` Running this command will: * Create a tunnel by establishing a persistent relationship between the name you provide and a UUID for your tunnel. At this point, no connection is active within the tunnel yet. * Generate a [tunnel credentials file](https://developers.cloudflare.com/tunnel/advanced/local-management/local-tunnel-terms/#credentials-file) in the [default cloudflared directory](https://developers.cloudflare.com/tunnel/advanced/local-management/local-tunnel-terms/#default-cloudflared-directory). * Create a subdomain of `.cfargotunnel.com`. From the output of the command, take note of the tunnel's UUID and the path to your tunnel's credentials file. Confirm that the tunnel has been successfully created by running: Terminal window ``` cloudflared tunnel list ``` ## 4\. Create a configuration file 1. In your `.cloudflared` directory, create a [config.yml file](https://developers.cloudflare.com/tunnel/advanced/local-management/configuration-file/) using any text editor. This file will configure the tunnel to route traffic from a given origin to the hostname of your choice. 2. Add the following fields to the file: ``` url: http://localhost:8000 tunnel: credentials-file: /root/.cloudflared/.json ``` 3. Confirm that the configuration file has been successfully created by running: Terminal window ``` cat config.yml ``` ## 5\. Start routing traffic To route a [published application](https://developers.cloudflare.com/tunnel/routing/) through the tunnel: Terminal window ``` cloudflared tunnel route dns ``` This command will create a `CNAME` record pointing to `.cfargotunnel.com`. ## 6\. Run the tunnel Run the tunnel to proxy incoming traffic from the tunnel to any number of services running locally on your origin. Terminal window ``` cloudflared tunnel run ``` If your configuration file has a custom name or is not in the `.cloudflared` directory, add the `--config` flag and specify the path. Terminal window ``` cloudflared tunnel --config /path/your-config-file.yml run ``` Note Cloudflare Tunnel can install itself as a system service on Linux and Windows and as a launch agent on macOS. For more information, refer to [run as a service](https://developers.cloudflare.com/tunnel/advanced/local-management/as-a-service/). ## 7\. Check the tunnel To get information on the tunnel you just created, run: Terminal window ``` cloudflared tunnel info ``` Looking for private network routing? For Cloudflare One Client private network access, refer to the [Cloudflare One Tunnel documentation](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/local-management/configuration-file/#file-structure-for-private-networks). ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/advanced/","name":"Advanced"}},{"@type":"ListItem","position":4,"item":{"@id":"/tunnel/advanced/local-management/","name":"Locally-managed tunnels"}},{"@type":"ListItem","position":5,"item":{"@id":"/tunnel/advanced/local-management/create-local-tunnel/","name":"Create a locally-managed tunnel"}}]} ``` --- --- title: Useful terms description: This page contains terminology specific to locally-managed Cloudflare Tunnels. For general Tunnel terminology, refer to the Get started section. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/advanced/local-management/local-tunnel-terms.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Useful terms This page contains terminology specific to locally-managed Cloudflare Tunnels. For general Tunnel terminology, refer to the [Get started section](https://developers.cloudflare.com/tunnel/faq/). ## Default `cloudflared` directory `cloudflared` uses a default directory when storing credentials files for your tunnels, as well as the `cert.pem` file it generates when you run `cloudflared login`. The default directory is also where `cloudflared` will look for a [configuration file](#configuration-file) if no other file path is specified when running a tunnel. | OS | Path to default directory | | --------------------------- | --------------------------------------------------------------------------------- | | Windows | %USERPROFILE%\\.cloudflared | | macOS and Unix-like systems | \~/.cloudflared, /etc/cloudflared, and /usr/local/etc/cloudflared, in this order. | ## Configuration file This is a YAML file that functions as the operating manual for `cloudflared`. `cloudflared` will automatically look for the configuration file in the [default cloudflared directory](#default-cloudflared-directory), but you can store your configuration file in any directory. It is recommended to always specify the file path for your configuration file whenever you reference it. By creating a configuration file, you can have fine-grained control over how their instance of `cloudflared` will operate. This includes operations like what you want `cloudflared` to do with traffic (for example, proxy websockets to port `xxxx` or SSH to port `yyyy`), where `cloudflared` should search for authorization (credentials file, tunnel token), and what mode it should run in (for example, [warp-routing](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/)). In the absence of a configuration file, cloudflared will proxy outbound traffic through port `8080`. For more information on how to create, store, and structure a configuration file, refer to the [dedicated instructions](https://developers.cloudflare.com/tunnel/other-tunnel-types/local-management/configuration-file/). ## Cert.pem This is the certificate file issued by Cloudflare when you run `cloudflared tunnel login`. This file uses a certificate to authenticate your instance of `cloudflared` and it is required when you create new tunnels, delete existing tunnels, change DNS records, or configure tunnel routing from cloudflared. This file is not required to perform actions such as running an existing tunnel or managing tunnel routing from the Cloudflare dashboard. Refer to the [Tunnel permissions page](https://developers.cloudflare.com/tunnel/other-tunnel-types/local-management/tunnel-permissions/) for more details on when this file is needed. The `cert.pem` origin certificate is valid for at least 10 years, and the service token it contains is valid until revoked. ## Credentials file This file is created when you run `cloudflared tunnel create `. It stores your tunnel's credentials in JSON format, and is unique to each tunnel. This file functions as a token authenticating the tunnel it is associated with. Refer to the [Tunnel permissions page](https://developers.cloudflare.com/tunnel/other-tunnel-types/local-management/tunnel-permissions/) for more details on when this file is needed. ## Ingress rule Ingress rules let you specify which local services traffic should be proxied to. If a rule does not specify a path, all paths will be matched. Ingress rules can be listed in your [configuration file](https://developers.cloudflare.com/tunnel/other-tunnel-types/local-management/configuration-file/) or when running `cloudflared tunnel ingress`. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/advanced/","name":"Advanced"}},{"@type":"ListItem","position":4,"item":{"@id":"/tunnel/advanced/local-management/","name":"Locally-managed tunnels"}},{"@type":"ListItem","position":5,"item":{"@id":"/tunnel/advanced/local-management/local-tunnel-terms/","name":"Useful terms"}}]} ``` --- --- title: Tunnel permissions description: Tunnel permissions determine who can run and manage a Cloudflare Tunnel. Two files control permissions for a locally-managed tunnel: image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/advanced/local-management/tunnel-permissions.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Tunnel permissions Tunnel permissions determine who can run and manage a Cloudflare Tunnel. Two files control permissions for a locally-managed tunnel: * **An account certificate** (`cert.pem`) is issued for a Cloudflare account when you login to `cloudflared`. Make sure you are intentional about the locations and machines you store this certificate on, as this certificate allows users to create, delete, and manage all tunnels for the account. * **A tunnel credentials file** (`.json`) is issued for a tunnel when you create the tunnel. The credentials file only allows the user to run that specific tunnel, and do nothing else. Hence, as an admin, you can share tunnel credentials with users who will run the tunnel. Refer to the table below for a comparison between the two files and the purposes for which they are intended. | Account certificate | Tunnel credential | | | ----------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | **File name** | cert.pem | .json | | **Purpose** | Authenticates your instance of cloudflared against your Cloudflare account | Authenticates the tunnel it is associated with | | **Scope** | Account-wide | Tunnel-specific | | **File type** | .pem | .json | | **Stored in** | [Default directory](https://developers.cloudflare.com/tunnel/faq/#default-cloudflared-directory) | [Default directory](https://developers.cloudflare.com/tunnel/faq/#default-cloudflared-directory) | | **Issued when running** | cloudflared tunnel login | cloudflared tunnel create | | **Valid for** | At least 10 years, and the service token it contains is valid until [revoked](#revoke-account-certificate) | Does not expire | | **Needed to** | Manage tunnels (for example, create, route, delete and list tunnels) | Run a tunnel. Create a config file. | ## Tunnel ownership Tunnel ownership is bound to the Cloudflare account for which the `cert.pem` file was issued upon authenticating `cloudflared`. If a user in a Cloudflare account creates a tunnel, any other user in the same account who has access to the `cert.pem` file for the account can delete, list, or otherwise manage tunnels within it. ## Revoke account certificate Your account certificate (`cert.pem`) contains an API token which authorizes `cloudflared` to manage tunnels in your Cloudflare account. To revoke the account certificate, delete the API token associated with your tunnel: 1. Log in to the [Cloudflare dashboard ↗](https://dash.cloudflare.com/) and go to **My Profile** \> **API Tokens**. 2. Find the **Cloudflare Tunnel API Token** or **Argo Tunnel API Token** for your zone and account. 3. Select the three dots > **Delete**. Once this token is deleted, `cloudflared` can no longer use the old `cert.pem` file to read or edit tunnels in your account. To generate a new token and `cert.pem` file, run `cloudflared tunnel login`. ## Account-scoped roles Minimum permissions needed to create, delete, and configure tunnels for an account: * [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/roles-permissions/) Additional permissions needed to [route traffic to a public hostname](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/routing-to-tunnel/) and to be able to perform `cloudflared login`: * [DNS](https://developers.cloudflare.com/fundamentals/manage-members/roles/) * [Load Balancer](https://developers.cloudflare.com/fundamentals/manage-members/roles/) ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/advanced/","name":"Advanced"}},{"@type":"ListItem","position":4,"item":{"@id":"/tunnel/advanced/local-management/","name":"Locally-managed tunnels"}},{"@type":"ListItem","position":5,"item":{"@id":"/tunnel/advanced/local-management/tunnel-permissions/","name":"Tunnel permissions"}}]} ``` --- --- title: Useful commands description: This page lists the most commonly used commands for managing local tunnels. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/advanced/local-management/tunnel-useful-commands.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Useful commands This page lists the most commonly used commands for managing local tunnels. To view all CLI commands, refer to the CLI help text in your terminal. For example, to view all options for the `cloudflared tunnel` subcommand, type `cloudflared tunnel help`. ## Manage `cloudflared` | Command | Description | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | cloudflared update | Looks for a new version on the official download server. If a new version exists, it updates the agent binary and quits. Otherwise, no action is performed. This command only works if cloudflared was installed from GitHub binaries or from source. For more information, refer to the [update instructions](https://developers.cloudflare.com/tunnel/downloads/update-cloudflared/). | | cloudflared version | Prints the cloudflared version number and build date. | | cloudflared help | Shows a list of all top-level commands for cloudflared. | ## Manage tunnels | Command | Description | | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | cloudflared tunnel login | Prompts a browser window where you can authenticate your tunnel to your Cloudflare account. | | cloudflared tunnel list | Displays all active tunnels, their creation time, and associated connections. Use the \-d flag to include deleted tunnels. | | cloudflared tunnel create | Creates a tunnel, registers it with the Cloudflare edge and generates a credential file to run this tunnel. | | cloudflared tunnel --config path/config.yaml run | Runs a tunnel, creating highly available connections between your server and the Cloudflare edge. You can provide name or UUID of the tunnel to run either as the last command line argument or in the configuration file using tunnel: . | | cloudflared tunnel info | Displays details about the active connectors for a given tunnel identified by name of UUID. | | cloudflared tunnel cleanup | Deletes connections for tunnels with the given UUIDs or names. This is useful if you get an error trying to delete or run a tunnel after cloudflared is not shut down gracefully (for example, if a kill command is issued). | | cloudflared tunnel cleanup --connector-id | Disconnects and deletes a [cloudflared replica](https://developers.cloudflare.com/tunnel/configuration/#replicas-and-high-availability) with the given connector ID. You can view all replicas for a tunnel by running cloudflared tunnel info . | | cloudflared tunnel delete | Deletes tunnels with the given name or UUID. A tunnel cannot be deleted if it has active connections. To delete the tunnel unconditionally, use the \-f flag. | | cloudflared tail | Start a session to livestream logs from a specific tunnel. For more information, refer to [Tunnel logs](https://developers.cloudflare.com/tunnel/monitoring/#logs). | ## Manage published applications | Command | Description | | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | cloudflared tunnel route dns | Creates a DNS CNAME record hostname that points to the tunnel. | | cloudflared tunnel route lb | Adds a tunnel as an endpoint in a [load balancer pool](https://developers.cloudflare.com/tunnel/routing/#add-a-tunnel-to-a-load-balancer-pool). A new load balancer and pool will be created if necessary. : the public-facing hostname of the load balancer, for example lb.example.com : the name of the [pool](https://developers.cloudflare.com/load-balancing/pools/create-pool/#create-a-pool) that will contain the tunnel endpoint To load balance traffic to a [published application](https://developers.cloudflare.com/tunnel/other-tunnel-types/local-management/configuration-file/#file-structure-for-published-applications), you will also need to specify the application hostname in the [endpoint host header](https://developers.cloudflare.com/load-balancing/additional-options/override-http-host-headers/) using the dashboard or API. | ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/advanced/","name":"Advanced"}},{"@type":"ListItem","position":4,"item":{"@id":"/tunnel/advanced/local-management/","name":"Locally-managed tunnels"}},{"@type":"ListItem","position":5,"item":{"@id":"/tunnel/advanced/local-management/tunnel-useful-commands/","name":"Useful commands"}}]} ``` --- --- title: Origin parameters description: Origin parameters determine how cloudflared sends requests to the origin server of your published application. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/advanced/origin-parameters.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Origin parameters Origin parameters determine how `cloudflared` sends requests to the origin server of your [published application](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/routing-to-tunnel/). ## Update origin parameters This section describes how to update origin parameters for a remotely-managed tunnel. If you are using a locally-managed tunnel, add these parameters to your [configuration file](https://developers.cloudflare.com/tunnel/advanced/local-management/configuration-file/). * [ Dashboard ](#tab-panel-6674) 1. In [Cloudflare One ↗](https://one.dash.cloudflare.com/), go to **Networks** \> **Connectors** \> **Cloudflare Tunnels**. 2. Choose a tunnel and select **Edit**. 3. Select the **Published application routes** tab. 4. Choose an application and select **Edit**. 5. Under **Additional application settings**, modify one or more origin parameters. 6. Select **Save**. ## TLS settings ### originServerName | Default | UI name | | ------- | ------------------ | | "" | Origin Server Name | Hostname that `cloudflared` should expect from your origin server certificate. If null, the expected hostname is the service URL, for example `localhost` if the service is `https://localhost:443`. ### matchSNItoHost | Default | UI name | | ------- | ----------------- | | false | Match SNI to Host | When `true`, `cloudflared` will automatically set the Server Name Indication (SNI) during the TLS handshake to the hostname of the incoming request. This setting is useful when directing traffic to entry points that host multiple services and rely on SNI to route requests or present the correct certificate. It eliminates the need to explicitly configure [originServerName](#originservername) for individual services when using wildcard routing. ### caPool | Default | UI name | | ------- | -------------------------- | | "" | Certificate Authority Pool | Local file path to the certificate authority (CA) for your origin server certificate (for example, `/root/certs/ca.pem`). The path should point to a certificate store file or a bundle file in `.pem` or `.crt` format that contains one or more trusted root CA certificates. You should only configure this setting if your certificate is not signed by Cloudflare. ### noTLSVerify | Default | UI name | | ------- | ------------- | | false | No TLS Verify | When `false`, TLS verification is performed on the certificate presented by your origin. When `true`, TLS verification is disabled. This will allow any certificate from the origin to be accepted. ### tlsTimeout | Default | UI name | | ------- | ----------- | | 10s | TLS Timeout | Timeout for completing a TLS handshake to your origin server, if you have chosen to connect Tunnel to an HTTPS server. ### http2Origin | Default | UI name | | ------- | ---------------- | | false | HTTP2 connection | When `false`, `cloudflared` will connect to your origin with HTTP/1.1. When `true`, `cloudflared` will attempt to connect to your origin server using HTTP/2.0 instead of HTTP/1.1\. HTTP/2.0 is a faster protocol for high traffic origins but requires you to deploy an SSL certificate on the origin. We recommend using this setting in conjunction with [noTLSVerify](#notlsverify) so that you can use a self-signed certificate. ## HTTP settings ### httpHostHeader | Default | UI name | | ------- | ---------------- | | "" | HTTP Host Header | Sets the HTTP `Host` header on requests sent to the local service. ### disableChunkedEncoding | Default | UI name | | ------- | ------------------------ | | false | Disable Chunked Encoding | When `false`, `cloudflared` performs chunked transfer encoding when transferring data over HTTP/1.1. When `true`, chunked transfer encoding is disabled. This is useful if you are running a Web Server Gateway Interface (WSGI) server. ## Connection settings ### connectTimeout | Default | UI name | | ------- | --------------- | | 30s | Connect Timeout | Timeout for establishing a new TCP connection to your origin server. This excludes the time taken to establish TLS, which is controlled by tlsTimeout. ### noHappyEyeballs | Default | UI name | | ------- | ----------------- | | false | No Happy Eyeballs | When `false`, `cloudflared` uses the Happy Eyeballs algorithm for IPv4/IPv6 fallback if your local network has misconfigured one of the protocols. When `true`, Happy Eyeballs is disabled. ### proxyType | Default | UI name | | ------- | ---------- | | "" | Proxy Type | `cloudflared` starts a proxy server to translate HTTP traffic into TCP when proxying, for example, SSH or RDP. This configures what type of proxy will be started. Valid options are: * `""` for the regular proxy * `"socks"` for a SOCKS5 proxy. Refer to the [tutorial on connecting through Cloudflare Access using kubectl](https://developers.cloudflare.com/cloudflare-one/tutorials/kubectl/) for more information. ### proxyAddress Note For locally-managed tunnels only. | Default | UI name | | --------- | ------- | | 127.0.0.1 | \-- | `cloudflared` starts a proxy server to translate HTTP traffic into TCP when proxying, for example, SSH or RDP. This configures the listen address for that proxy. ### proxyPort Note For locally-managed tunnels only. | Default | UI name | | ------- | ------- | | 0 | \-- | `cloudflared` starts a proxy server to translate HTTP traffic into TCP when proxying, for example, SSH or RDP. This configures the listen port for that proxy. If set to zero, an unused port will randomly be chosen. ### keepAliveTimeout | Default | UI name | | ------- | ------------------------------- | | 1m30s | Idle Connection Expiration Time | Timeout after which an idle keepalive connection can be discarded. ### keepAliveConnections | Default | UI name | | ------- | ---------------------- | | 100 | Keep Alive Connections | Default: `100` Maximum number of idle keepalive connections between Cloudflare and your origin. This does not restrict the total number of concurrent connections. ### tcpKeepAlive | Default | UI name | | ------- | ----------------------- | | 30s | TCP Keep Alive Interval | Default: `30s` The timeout after which a TCP keepalive packet is sent on a connection between Cloudflare and the origin server. ## Access settings ### access | Default | UI name | | ------- | ------------------- | | "" | Protect with Access | Requires `cloudflared` to validate the [Cloudflare Access JWT](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/validating-json/) prior to proxying traffic to your origin. You can enforce this check on public hostname services that are protected by an Access application. For all L7 requests to these hostnames, Access will send the JWT to `cloudflared` as a `Cf-Access-Jwt-Assertion` request header. To enable this security control in a [configuration file](https://developers.cloudflare.com/tunnel/advanced/local-management/configuration-file/), [get the AUD tag](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/validating-json/#get-your-aud-tag) for your Access application and add the following rule to `originRequest`: ``` access: required: true teamName: audTag: - - ``` ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/advanced/","name":"Advanced"}},{"@type":"ListItem","position":4,"item":{"@id":"/tunnel/advanced/origin-parameters/","name":"Origin parameters"}}]} ``` --- --- title: Run parameters description: This page lists the configuration flags for the cloudflared tunnel run command. For a remotely-managed tunnel, add these flags to the tunnel service. If you are using a locally-managed tunnel, add these flags to your configuration file as key/value pairs. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/advanced/run-parameters.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Run parameters This page lists the configuration flags for the `cloudflared tunnel run` command. For a remotely-managed tunnel, add these flags to the [tunnel service](#add-run-parameters-to-tunnel-service). If you are using a locally-managed tunnel, add these flags to your [configuration file](https://developers.cloudflare.com/tunnel/advanced/local-management/configuration-file/) as key/value pairs. ## Add run parameters to tunnel service Remotely-managed tunnels run as a service on your OS. To add run parameters to the tunnel service file: * [ Linux ](#tab-panel-6675) * [ macOS ](#tab-panel-6676) * [ Windows ](#tab-panel-6677) On Linux, Cloudflare Tunnel installs itself as a system service using `systemctl`. By default, the service will be named `cloudflared.service`. To configure your tunnel on Linux: 1. Open `cloudflared.service`. Terminal window ``` sudo systemctl edit --full cloudflared.service ``` 2. Modify the `cloudflared tunnel run` command with the desired configuration flag. For example, ``` [Unit] Description=Cloudflare Tunnel After=network.target [Service] TimeoutStartSec=0 Type=notify ExecStart=/usr/local/bin/cloudflared tunnel --loglevel info --logfile /var/log/cloudflared/cloudflared.log run --token Restart=on-failure RestartSec=5s [Install] WantedBy=multi-user.target ``` 3. Restart `cloudflared.service`: Terminal window ``` sudo systemctl restart cloudflared ``` 4. To verify the new configuration, check the service status: Terminal window ``` sudo systemctl status cloudflared ``` ``` ● cloudflared.service - cloudflared Loaded: loaded (/etc/systemd/system/cloudflared.service; enabled; preset: enabled) Active: active (running) since Wed 2024-10-09 20:02:59 UTC; 2s ago Main PID: 2157 (cloudflared) Tasks: 8 (limit: 1136) Memory: 16.3M CPU: 136ms CGroup: /system.slice/cloudflared.service └─2157 /usr/bin/cloudflared tunnel --loglevel info --logfile /var/log/cloudflared/cloudflared.log run --token eyJhIjoi... ``` On macOS, Cloudflare Tunnel installs itself as a launch agent using `launchctl`. By default, the agent will be called `com.cloudflare.cloudflared`. To configure your tunnel on macOS: 1. Stop the `cloudflared` service. Terminal window ``` sudo launchctl stop com.cloudflare.cloudflared ``` 2. Unload the configuration file. Terminal window ``` sudo launchctl unload /Library/LaunchDaemons/com.cloudflare.cloudflared.plist ``` 3. Open `/Library/LaunchDaemons/com.cloudflare.cloudflared.plist` in a text editor. 4. Modify the `ProgramArguments` key with the desired configuration flag. For example, ``` Label com.cloudflare.cloudflared ProgramArguments /opt/homebrew/bin/cloudflared tunnel --logfile --loglevel debug run --token ``` 5. Load the updated configuration file. Terminal window ``` sudo launchctl load /Library/LaunchDaemons/com.cloudflare.cloudflared.plist ``` 6. Start the `cloudflared` service. Terminal window ``` sudo launchctl start com.cloudflare.cloudflared ``` On Windows, Cloudflare Tunnel installs itself as a system service using the Registry Editor. By default, the service will be named `cloudflared`. To configure your tunnel on Windows: 1. Open the Registry Editor. 2. Go to **HKEY\_LOCAL\_MACHINE** \> **SYSTEM** \> **CurrentControlSet** \> **Services** \> **cloudflared**. 3. Double-click **ImagePath**. 4. Modify **Value data** with the desired configuration flag. For example, ``` C:\Program Files (x86)\cloudflared\.\cloudflared.exe tunnel --loglevel info --logfile run --token ``` ![Modify cloudflared service in the Registry Editor](https://developers.cloudflare.com/_astro/remote-management-windows.BFUIIr2f_Z1Rbddd.webp) ## Parameters ### `autoupdate-freq` | Syntax | Default | | -------------------------------------------------------------- | ------- | | cloudflared tunnel --autoupdate-freq run | 24h | Configures the frequency of `cloudflared` updates. By default, `cloudflared` will periodically check for updates and restart with the new version. Restarts are performed by spawning a new process that connects to the Cloudflare global network. On successful connection, the old process will gracefully shut down after handling all outstanding requests. See also: [no-autoupdate](#no-autoupdate). ### `config` Note For locally-managed tunnels only. | Syntax | Default | | ----------------------------------------------------- | -------------------------- | | cloudflared tunnel --config run | \~/.cloudflared/config.yml | Specifies the path to a [configuration file](https://developers.cloudflare.com/tunnel/advanced/local-management/configuration-file/) in YAML format. ### `dns-resolver-addrs` Note Requires `cloudflared` version 2025.7.0 or later. | Syntax | Environment Variable | | -------------------------------------------------------------------- | ---------------------------- | | cloudflared tunnel run --dns-resolver-addrs | TUNNEL\_DNS\_RESOLVER\_ADDRS | Specifies custom DNS resolver addresses for `cloudflared` to use instead of the host machine's default resolvers. Each address must be in `ip:port` format — providing an IP address without a port will cause `cloudflared` to fail to start. You can specify multiple resolvers by repeating the flag. For example, Terminal window ``` cloudflared tunnel run --dns-resolver-addrs 1.1.1.1:53 --dns-resolver-addrs 1.0.0.1:53 ``` When multiple resolvers are specified, `cloudflared` randomly selects one for each DNS request. A maximum of 10 resolver addresses are allowed. ### `edge-bind-address` | Syntax | Environment Variable | | -------------------------------------------------------------- | --------------------------- | | cloudflared tunnel --edge-bind-address run | TUNNEL\_EDGE\_BIND\_ADDRESS | Specifies the outgoing IP address used to establish a connection between `cloudflared` and the Cloudflare global network. By default, `cloudflared` lets the operating system decide which IP address to use. This option is useful if you have multiple network interfaces available and want to prefer a specific interface. The IP version of `edge-bind-address` will override [edge-ip-version](#edge-ip-version) (if provided). For example, if you enter an IPv6 source address, `cloudflared` will always connect to an IPv6 destination. ### `edge-ip-version` | Syntax | Default | Environment Variable | | ----------------------------------------------------------------- | ------- | ------------------------- | | cloudflared tunnel --edge-ip-version run | 4 | TUNNEL\_EDGE\_IP\_VERSION | Specifies the IP address version (IPv4 or IPv6) used to establish a connection between `cloudflared` and the Cloudflare global network. Available values are `auto`, `4`, and `6`. The value `auto` relies on the host operating system to determine which IP version to select. The first IP version returned from the DNS resolution of the region lookup will be used as the primary set. In dual IPv6 and IPv4 network setups, `cloudflared` will separate the IP versions into two address sets that will be used to fallback in connectivity failure scenarios. ### `grace-period` | Syntax | Default | Environment Variable | | ------------------------------------------------------------- | ------- | --------------------- | | cloudflared tunnel --grace-period run | 30s | TUNNEL\_GRACE\_PERIOD | When `cloudflared` receives SIGINT/SIGTERM it will stop accepting new requests, wait for in-progress requests to terminate, then shut down. Waiting for in-progress requests will timeout after this grace period, or when a second SIGTERM/SIGINT is received. ### `logfile` | Syntax | Environment Variable | | ------------------------------------------------------ | -------------------- | | cloudflared tunnel --logfile run | TUNNEL\_LOGFILE | Saves application log to this file. Mainly useful for reporting issues. For more details on what information you need when contacting Cloudflare support, refer to [this guide](https://developers.cloudflare.com/tunnel/troubleshooting/). ### `loglevel` | Syntax | Default | Environment Variable | | -------------------------------------------------------- | ------- | -------------------- | | cloudflared tunnel --loglevel run | info | TUNNEL\_LOGLEVEL | Specifies the verbosity of logging for the local `cloudflared` instance. Available values are `debug`, `info` (default), `warn`, `error`, and `fatal`. At the `debug` level, `cloudflared` will log and display the request URL, method, protocol, content length, as well as all request and response headers. However, note that this can expose sensitive information in your logs. ### `metrics` | Syntax | Default | Environment Variable | | --------------------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------- | | cloudflared tunnel --metrics run | Refer to [Tunnel metrics](https://developers.cloudflare.com/tunnel/monitoring/#metrics) | TUNNEL\_METRICS | Exposes a Prometheus endpoint on the specified IP address and port, which you can then query for [usage metrics](https://developers.cloudflare.com/tunnel/monitoring/#cloudflared-metrics). ### `no-autoupdate` Note Does not apply if you installed `cloudflared` using a package manager. You can check if `cloudflared` was installed by a package manager by running `ls -la /usr/local/etc/cloudflared/` and looking for `.installedFromPackageManager` in the output. | Syntax | Environment Variable | | ----------------------------------------------------- | -------------------- | | cloudflared tunnel --no-autoupdate run | NO\_AUTOUPDATE | Disables automatic `cloudflared` updates. See also: [autoupdate-freq](#autoupdate-freq). ### `origincert` Note For locally-managed tunnels only. | Syntax | Default | Environment Variable | | --------------------------------------------------------- | ------------------------ | -------------------- | | cloudflared tunnel --origincert run | \~/.cloudflared/cert.pem | TUNNEL\_ORIGIN\_CERT | Specifies the [account certificate](https://developers.cloudflare.com/tunnel/advanced/local-management/tunnel-permissions/) for one of your zones, authorizing the client to serve as an origin for that zone. You can obtain a certificate by using the `cloudflared tunnel login` command or by visiting `https://dash.cloudflare.com/argotunnel`. ### `pidfile` | Syntax | Environment Variable | | ------------------------------------------------------ | -------------------- | | cloudflared tunnel --pidfile run | TUNNEL\_PIDFILE | Writes the application's process identifier (PID) to this file after the first successful connection. Mainly useful for scripting and service integration. ### `post-quantum` | Syntax | Environment Variable | | ---------------------------------------------------- | --------------------- | | cloudflared tunnel run --post-quantum | TUNNEL\_POST\_QUANTUM | By default, Cloudflare Tunnel connections over [quic](#protocol) are encrypted using [post-quantum cryptography (PQC)](https://developers.cloudflare.com/ssl/post-quantum-cryptography/) but will fall back to non-PQ if there are issues connecting. If the `--post-quantum` flag is provided, `quic` connections are only allowed to use PQ key agreements, with no fallback to non-PQ. Post-quantum key agreements are not supported when using `http2` protocol. ### `protocol` | Syntax | Default | Environment Variable | | -------------------------------------------------------- | ------- | --------------------------- | | cloudflared tunnel --protocol run | auto | TUNNEL\_TRANSPORT\_PROTOCOL | Specifies the protocol used to establish a connection between `cloudflared` and the Cloudflare global network. Available values are `auto`, `http2`, and `quic`. The `auto` value will automatically configure the `quic` protocol. If `cloudflared` is unable to establish UDP connections, it will fallback to using the `http2` protocol. ### `region` | Syntax | Environment Variable | | ------------------------------------------------------ | -------------------- | | cloudflared tunnel --region run | TUNNEL\_REGION | Allows you to choose the regions to which connections are established. Currently the only available value is `us`, which routes all connections through data centers in the United States. Omit or leave empty to connect to the global region. When the region is set to `us`, `cloudflared` uses different US-specific hostnames and IPs. Refer to [Tunnel with firewall](https://developers.cloudflare.com/tunnel/configuration/#us-region-configuration) for details. Note For [FedRAMP High ↗](https://www.cloudflare.com/cloudflare-for-government/) environments, the tunnel token determines routing to FedRAMP data centers automatically — no `--region` flag is required. Refer to [Tunnel with firewall](https://developers.cloudflare.com/tunnel/configuration/#us-region-configuration#region-fedramp-high) for the FedRAMP-specific endpoints your firewall must allow. ### `retries` | Syntax | Default | Environment Variable | | ------------------------------------------------------- | ------- | -------------------- | | cloudflared tunnel --retries run | 5 | TUNNEL\_RETRIES | Specifies the maximum number of retries for connection/protocol errors. Retries use exponential backoff (retrying at 1, 2, 4, 8, 16 seconds by default), so it is not recommended that you increase this value significantly. ### `tag` | Syntax | Environment Variable | | ----------------------------------------------------- | -------------------- | | cloudflared tunnel --tag run | TUNNEL\_TAG | Specifies custom tags used to identify this tunnel. Multiple tags may be specified by adding additional `--tag ` flags to the command. If entering multiple tags into a configuration file, delimit with commas: `tag: {KEY1=VALUE1, KEY2=VALUE2}`. ### `token` Note For remotely-managed tunnels only. | Syntax | Environment Variable | | ---------------------------------------------- | -------------------- | | cloudflared tunnel run --token | TUNNEL\_TOKEN | Associates the `cloudflared` instance with a specific tunnel. The tunnel's token is shown in the dashboard when you first [create the tunnel](https://developers.cloudflare.com/tunnel/get-started/). You can also retrieve the token using the [API](https://developers.cloudflare.com/api/resources/zero%5Ftrust/subresources/tunnels/subresources/cloudflared/subresources/token/methods/get/). ### `token-file` Note For remotely-managed tunnels only. Requires `2025.4.0` or later. | Syntax | Environment Variable | | ------------------------------------------ | -------------------- | | cloudflared tunnel run --token-file | TUNNEL\_TOKEN\_FILE | Associates the `cloudflared` instance with a specific tunnel using a file which contains the token. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/advanced/","name":"Advanced"}},{"@type":"ListItem","position":4,"item":{"@id":"/tunnel/advanced/run-parameters/","name":"Run parameters"}}]} ``` --- --- title: Tunnel tokens description: A remotely-managed tunnel only requires a token to run. Anyone with the token can run the tunnel. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/advanced/tunnel-tokens.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Tunnel tokens A remotely-managed tunnel only requires a token to run. Anyone with the token can run the tunnel. ## Get the token To get the token for a remotely-managed tunnel: * [ Dashboard ](#tab-panel-6678) * [ API ](#tab-panel-6679) 1. In the [Cloudflare dashboard ↗](https://dash.cloudflare.com/), go to **Networking** \> **Tunnels**. [ Go to **Tunnels** ](https://dash.cloudflare.com/?to=/:account/tunnels) 2. Select your tunnel. 3. Select **Add a replica**. 4. Copy the `cloudflared` installation command into a text editor (do not run the command). The token is the `eyJ...` string. Required API token permissions At least one of the following [token permissions](https://developers.cloudflare.com/fundamentals/api/reference/permissions/)is required: * `Cloudflare One Connectors Write` * `Cloudflare One Connector: cloudflared Write` * `Cloudflare Tunnel Write` Get a Cloudflare Tunnel token ``` curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/cfd_tunnel/$TUNNEL_ID/token" \ --request GET \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` ## Rotate a token Rotate tokens regularly to reduce the risk of compromise. For tunnels with multiple [replicas](https://developers.cloudflare.com/tunnel/configuration/#replicas-and-high-availability), rotate outside working hours and update replicas in batches. 1. In the [Cloudflare dashboard ↗](https://dash.cloudflare.com/), go to **Networking** \> **Tunnels**. [ Go to **Tunnels** ](https://dash.cloudflare.com/?to=/:account/tunnels) 2. Select your tunnel. 3. Select **Rotate token**. After rotating the token, `cloudflared` cannot establish new connections with the old token. Existing connectors remain active until restarted. 4. Select **Add replica** and copy the new `cloudflared` installation command. 5. On each replica, reinstall the `cloudflared` service using the new token: Terminal window ``` sudo cloudflared service uninstall sudo cloudflared service install ``` Rotate a compromised token If your tunnel token is compromised, immediately [rotate the token](#rotate-a-token), then force-disconnect all existing connections: Required API token permissions At least one of the following [token permissions](https://developers.cloudflare.com/fundamentals/api/reference/permissions/)is required: * `Cloudflare One Connectors Write` * `Cloudflare One Connector: cloudflared Write` * `Cloudflare Tunnel Write` Clean up Cloudflare Tunnel connections ``` curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/cfd_tunnel/$TUNNEL_ID/connections" \ --request DELETE \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` Then reinstall the `cloudflared` service on all replicas using the new token. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/advanced/","name":"Advanced"}},{"@type":"ListItem","position":4,"item":{"@id":"/tunnel/advanced/tunnel-tokens/","name":"Tunnel tokens"}}]} ``` --- --- title: Ansible description: Ansible is a software tool that enables at scale management of infrastructure. Ansible is agentless — all it needs to function is the ability to SSH to the target and Python installed on the target. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/deployment-guides/ansible.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Ansible Ansible is a software tool that enables at scale management of infrastructure. Ansible is agentless — all it needs to function is the ability to SSH to the target and Python installed on the target. Ansible works alongside Terraform to streamline the Cloudflare Tunnel setup process. In this guide, you will use Terraform to deploy an SSH server on Google Cloud and create a [locally-managed tunnel](https://developers.cloudflare.com/tunnel/advanced/local-management/create-local-tunnel/) that makes the server available over the Internet. Terraform will automatically run an Ansible playbook that installs and configures `cloudflared` on the server. ## Prerequisites To complete the steps in this guide, you will need: * [A Google Cloud Project ↗](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating%5Fa%5Fproject) and [GCP CLI installed and authenticated ↗](https://cloud.google.com/sdk/docs/install). * [Basic knowledge of Terraform](https://developers.cloudflare.com/tunnel/deployment-guides/terraform/) and [Terraform installed](https://developer.hashicorp.com/terraform/tutorials/certification-associate-tutorials/install-cli). * [A zone on Cloudflare](https://developers.cloudflare.com/fundamentals/manage-domains/add-site/). * [A Cloudflare API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) with `Cloudflare Tunnel` and `DNS` permissions. ## 1\. Install Ansible Refer to the [Ansible installation instructions ↗](https://docs.ansible.com/ansible/latest/installation%5Fguide/index.html). ## 2\. (Optional) Create an SSH key pair Terraform and Ansible require an unencrypted SSH key to connect to the GCP server. If you do not already have a key, you can generate one as follows: 1. Open a terminal and type the following command: Terminal window ``` ssh-keygen -t rsa -f ~/.ssh/gcp_ssh -C ``` 2. When prompted for a passphrase, press the `Enter` key twice to leave it blank. Terraform cannot decode encrypted private keys. Two files will be generated: `gcp_ssh` which contains the private key, and `gcp_ssh.pub` which contains the public key. ## 3\. Create a configuration directory 1. Create a folder for your Terraform and Ansible configuration files: Terminal window ``` mkdir ansible-tunnel ``` 2. Change to the new directory: Terminal window ``` cd ansible-tunnel ``` ## 4\. Create Terraform configuration files ### Define input variables The following variables will be passed into your GCP and Cloudflare configuration. 1. In your configuration directory, create a `.tf` file: Terminal window ``` touch variables.tf ``` 2. Open the file in a text editor and copy and paste the following: ``` # GCP variables variable "gcp_project_id" { description = "Google Cloud Platform (GCP) project ID" type = string } variable "zone" { description = "Geographical zone for the GCP VM instance" type = string } variable "machine_type" { description = "Machine type for the GCP VM instance" type = string } # Cloudflare variables variable "cloudflare_zone" { description = "Domain used to expose the GCP VM instance to the Internet" type = string } variable "cloudflare_zone_id" { description = "Zone ID for your domain" type = string } variable "cloudflare_account_id" { description = "Account ID for your Cloudflare account" type = string sensitive = true } variable "cloudflare_email" { description = "Email address for your Cloudflare account" type = string sensitive = true } variable "cloudflare_token" { description = "Cloudflare API token" type = string sensitive = true } ``` ### Assign values to the variables 1. In your configuration directory, create a `.tfvars` file: Terminal window ``` touch terraform.tfvars ``` Terraform will automatically use these variables if the file is named `terraform.tfvars`, otherwise the variable file will need to be manually passed in. 2. Add the following variables to `terraform.tfvars`. Be sure to modify the example with your own values. ``` cloudflare_zone = "example.com" cloudflare_zone_id = "023e105f4ecef8ad9ca31a8372d0c353" cloudflare_account_id = "372e67954025e0ba6aaa6d586b9e0b59" cloudflare_email = "user@example.com" cloudflare_token = "y3AalHS_E7Vabk3c3lX950F90_Xl7YtjSlzyFn_X" gcp_project_id = "testvm-123" zone = "us-central1-a" machine_type = "e2-medium" ``` Warning To prevent accidentally exposing sensitive credentials, do not save `terraform.tfvars` in your version control system. For example, if your version control is git, add `terraform.tfvars` to your `.gitignore` file. ### Configure Terraform providers You will need to declare the [providers ↗](https://registry.terraform.io/browse/providers) used to provision the infrastructure. 1. In your configuration directory, create a `.tf` file: Terminal window ``` touch providers.tf ``` 2. Add the following providers to `providers.tf`. The `random` provider is used to generate a tunnel secret. ``` terraform { required_providers { cloudflare = { source = "cloudflare/cloudflare" version = ">= 5.8.2" } google = { source = "hashicorp/google" } } required_version = ">= 1.2" } # Providers provider "cloudflare" { api_token = var.cloudflare_token } provider "google" { project = var.gcp_project_id } provider "random" { } ``` ### Configure Cloudflare resources The following configuration will modify settings in your Cloudflare account. 1. In your configuration directory, create a `.tf` file: Terminal window ``` touch Cloudflare-config.tf ``` 2. Add the following resources to `Cloudflare-config.tf`: ``` # Creates a new remotely-managed tunnel for the GCP VM. resource "cloudflare_zero_trust_tunnel_cloudflared" "gcp_tunnel" { account_id = var.cloudflare_account_id name = "Ansible GCP tunnel" config_src = "cloudflare" } # Reads the token used to run the tunnel on the server. data "cloudflare_zero_trust_tunnel_cloudflared_token" "gcp_tunnel_token" { account_id = var.cloudflare_account_id tunnel_id = cloudflare_zero_trust_tunnel_cloudflared.gcp_tunnel.id } # Creates the CNAME record that routes http_app.${var.cloudflare_zone} to the tunnel. resource "cloudflare_dns_record" "http_app" { zone_id = var.cloudflare_zone_id name = "http_app" content = "${cloudflare_zero_trust_tunnel_cloudflared.gcp_tunnel.id}.cfargotunnel.com" type = "CNAME" ttl = 1 proxied = true } # Configures tunnel with a published application for clientless access. resource "cloudflare_zero_trust_tunnel_cloudflared_config" "gcp_tunnel_config" { tunnel_id = cloudflare_zero_trust_tunnel_cloudflared.gcp_tunnel.id account_id = var.cloudflare_account_id config = { ingress = [ { hostname = "http_app.${var.cloudflare_zone}" service = "http://localhost:80" }, { service = "http_status:404" } ] } } ``` ### Configure GCP resources The following configuration defines the specifications for the GCP virtual machine and installs Python3 on the machine. Python3 allows Ansible to configure the GCP instance instead of having to run a [startup script](https://developers.cloudflare.com/tunnel/deployment-guides/terraform/#create-a-startup-script) on boot. 1. In your configuration directory, create a `.tf` file: Terminal window ``` touch GCP-config.tf ``` 2. Open the file in a text editor and copy and paste the following example. Be sure to insert your own GCP username and SSH key pair. ``` # Selects the OS for the GCP VM. data "google_compute_image" "image" { family = "ubuntu-2204-lts" project = "ubuntu-os-cloud" } # Sets up a GCP VM instance. resource "google_compute_instance" "http_server" { name = "ansible-inst" machine_type = var.machine_type zone = var.zone tags = [] boot_disk { initialize_params { image = data.google_compute_image.image.self_link } } network_interface { network = "default" access_config { // Ephemeral IP } } scheduling { preemptible = true automatic_restart = false } // Installs Python3 on the VM. provisioner "remote-exec" { inline = [ "sudo apt update", "sudo apt install python3 -y", "echo Done!" ] connection { host = self.network_interface.0.access_config.0.nat_ip user = "" type = "ssh" private_key= file("") } } provisioner "local-exec" { // If specifying an SSH key and user, add `--private-key -u var.name` command = "ANSIBLE_HOST_KEY_CHECKING=False ansible-playbook -u --private-key -i ${self.network_interface.0.access_config.0.nat_ip}, playbook.yml" } metadata = { cf-email = var.cloudflare_email cf-zone = var.cloudflare_zone ssh-keys = ":${file("")}" } depends_on = [ local_file.tf_ansible_vars_file ] } ``` ### Export variables to Ansible The following Terraform resource exports the [tunnel token](https://developers.cloudflare.com/tunnel/configuration/#tunnel-tokens) and other variables to `tf_ansible_vars_file.yml`. Ansible will use the tunnel token to configure and run `cloudflared` on the server. 1. In your configuration directory, create a new `tf` file: Terminal window ``` touch export.tf ``` 2. Copy and paste the following content into `export.tf`: ``` resource "local_file" "tf_ansible_vars_file" { content = <<-DOC # Ansible vars_file containing variable values from Terraform. tunnel_id: ${cloudflare_zero_trust_tunnel_cloudflared.gcp_tunnel.id} tunnel_name: ${cloudflare_zero_trust_tunnel_cloudflared.gcp_tunnel.name} tunnel_token: ${data.cloudflare_zero_trust_tunnel_cloudflared_token.gcp_tunnel_token.token} DOC filename = "./tf_ansible_vars_file.yml" } ``` ## 5\. Create the Ansible playbook Ansible playbooks are YAML files that declare the configuration Ansible will deploy. 1. Create a new `.yml` file: Terminal window ``` touch playbook.yml ``` 2. Open the file in a text editor and copy and paste the following content: ``` --- - hosts: all become: yes # Import tunnel variables into the VM. vars_files: - ./tf_ansible_vars_file.yml # Execute the following commands on the VM. tasks: - name: Download the cloudflared Linux package. shell: wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb - name: Depackage cloudflared. shell: sudo dpkg -i cloudflared-linux-amd64.deb - name: Install the tunnel as a systemd service. shell: "cloudflared service install {{ tunnel_token }}" - name: Start the tunnel. systemd: name: cloudflared state: started enabled: true masked: no - name: Deploy an example Apache web server on port 80. shell: apt update && apt -y install apache2 - name: Edit the default Apache index file. copy: dest: /var/www/html/index.html content: |

Hello Cloudflare!

This page was created for a Cloudflare demo.

``` [Keywords ↗](https://docs.ansible.com/ansible/latest/reference%5Fappendices/playbooks%5Fkeywords.html#play) define how Ansible will execute the configuration. In the example above, the `vars_files` keyword specifies where variable definitions are stored, and the `tasks` keyword specifies the actions Ansible will perform. [Modules ↗](https://docs.ansible.com/ansible/2.9/user%5Fguide/modules.html) specify what tasks to complete. In this example, the `copy` module creates a file and populates it with content. ## 6\. Deploy the configuration Once you have created the configuration files, you can deploy them through Terraform. The Ansible deployment happens within the Terraform deployment when the `ansible-playbook` command is run. 1. Initialize your configuration directory: Terminal window ``` terraform init ``` 2. (Optional) Preview everything that will be created: Terminal window ``` terraform plan ``` 3. Deploy the configuration: Terminal window ``` terraform apply ``` It may take several minutes for the GCP instance and tunnel to come online. You can view your new tunnel in the [Cloudflare dashboard](https://dash.cloudflare.com/) under **Networking** \> **Tunnels**. ## 7\. Test the connection To test, open a browser and go to `http://http_app..com` (for example, `http_app.example.com`). You should see the **Hello Cloudflare!** test page. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/deployment-guides/","name":"Deployment guides"}},{"@type":"ListItem","position":4,"item":{"@id":"/tunnel/deployment-guides/ansible/","name":"Ansible"}}]} ``` --- --- title: AWS description: This guide covers how to connect an Amazon Web Services (AWS) EC2 instance to Cloudflare using cloudflared and publish a web application through a Cloudflare Tunnel. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/deployment-guides/aws.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # AWS This guide covers how to connect an Amazon Web Services (AWS) EC2 instance to Cloudflare using `cloudflared` and publish a web application through a Cloudflare Tunnel. ### Prerequisites * [Add a website to Cloudflare](https://developers.cloudflare.com/fundamentals/manage-domains/add-site/) ## 1\. Create an EC2 instance 1. From the AWS console, go to **Compute** \> **EC2** \> **Instances** 2. Select **Launch instance**. 3. Name your VM instance. In this example we will name it `http-test-server`. 4. For \*_Amazon Machine Image (AMI)_ choose your desired operating system and specifications. For this example, we will use _Ubuntu Server 24.04 LTS (HVM), SSD Volume Type_. 5. For **Instance type:**, you can select _t2.micro_ which is available on the free tier. 6. In **Key pair (login)**, create a new key pair to use for SSH. You will need to download the `.pem` file onto your local machine. 7. In **Network settings**, select **Create security group**. 8. Turn on the following Security Group rules: * **Allow SSH traffic from _My IP_** to prevent the instance from being publicly accessible. * **Allow HTTPS traffic from the internet** * **Allow HTTP traffic from the internet** 9. Select **Launch instance**. 10. Once the instance is up and running, go to the **Instances** summary page and copy its **Public IPv4 DNS** hostname (for example, `ec2-44-202-59-16.compute-1.amazonaws.com`). 11. To log in to the instance over SSH, open a terminal and run the following commands: Terminal window ``` cd Downloads ``` ``` chmod 400 "YourKeyPair.pem" ``` Terminal window ``` ssh -i "YourKeyPair.pem" ubuntu@ec2-44-202-59-16.compute-1.amazonaws.com ``` 1. Run `sudo su` to gain full admin rights to the instance. 2. For testing purposes, you can deploy a basic Apache web server on port `80`: Terminal window ``` apt update apt -y install apache2 cat < /var/www/html/index.html

Hello Cloudflare!

This page was created for a Cloudflare demo.

EOF ``` 1. To verify that the Apache server is running, open a browser and go to `http://ec2-44-202-59-16.compute-1.amazonaws.com` (make sure to connect over `http`, not `https`). You should see the **Hello Cloudflare!** test page. ## 2\. Create a tunnel 1. In the [Cloudflare dashboard ↗](https://dash.cloudflare.com/), go to **Networking** \> **Tunnels**. 2. Select **Create Tunnel** and enter a name (for example, `aws-tunnel`). 3. Select **Create Tunnel**. 4. Under **Setup Environment**, select **Debian 64-bit**. 5. Copy the install commands and run them on your EC2 instance. 6. Once the tunnel connects, select **Continue**. ## 3\. Publish an application 1. Under **Routes**, select **Add route** \> **Published application**. 2. Enter a hostname (for example, `hellocloudflare..com`). 3. Under **Service**, enter `http://localhost:80`. 4. Select **Add route**. To test, open a browser and go to the hostname you configured. You should see your web server's page. Looking for private network access? To connect to your EC2 instance via private IP using the Cloudflare One Client, refer to the [Cloudflare One Tunnel documentation](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/). ## Firewall configuration To secure your AWS instance, you can configure your [Security Group rules ↗](https://docs.aws.amazon.com/vpc/latest/userguide/security-group-rules.html) to deny all inbound traffic and allow only outbound traffic to the [Cloudflare Tunnel IP addresses](https://developers.cloudflare.com/tunnel/configuration/#required-ports). All Security Group rules are Allow rules; traffic that does not match a rule is blocked. Therefore, you can delete all inbound rules and leave only the relevant outbound rules. Note If you delete the inbound rule for port `22`, you will be unable to SSH back into the instance. After configuring your Security Group rules, verify that you can still access the service through Cloudflare Tunnel via its [public hostname](#3-publish-an-application). The service should no longer be accessible from outside Cloudflare Tunnel -- for example, if you go to `http://ec2-44-202-59-16.compute-1.amazonaws.com` the test page should no longer load. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/deployment-guides/","name":"Deployment guides"}},{"@type":"ListItem","position":4,"item":{"@id":"/tunnel/deployment-guides/aws/","name":"AWS"}}]} ``` --- --- title: Azure description: This guide covers how to connect an Azure Virtual Machine to Cloudflare using cloudflared and publish a web application through a Cloudflare Tunnel. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/deployment-guides/azure.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Azure This guide covers how to connect an Azure Virtual Machine to Cloudflare using `cloudflared` and publish a web application through a Cloudflare Tunnel. ### Prerequisites * [Add a website to Cloudflare](https://developers.cloudflare.com/fundamentals/manage-domains/add-site/) ## 1\. Create a Virtual Machine 1. In the Azure portal, go to **Virtual Machines** \> **Create** \> **Azure virtual machine**. 2. Select a **Resource group** or create a new one. ![Azure group](https://developers.cloudflare.com/_astro/azure-1.f9lJ2gl2_Z9H61D.webp) 3. Enter a name for the VM and select a region. For **Image**, select _Ubuntu Server 24.04 LTS_. For **Size**, select an appropriate size (for example, _Standard\_B1s_). 4. Under **Administrator account**, select **SSH public key** and enter your key pair. ![Azure keypair](https://developers.cloudflare.com/_astro/azure-2.TRbZo2Tb_28kqwy.webp) 5. Under **Inbound port rules**, allow SSH (`22`). For testing purposes, also allow HTTP (`80`) and HTTPS (`443`). ![Azure ports](https://developers.cloudflare.com/_astro/azure-3.MZiED3ci_1bszbc.webp) 6. Select **Review + create**, then **Create**. 7. Once the VM is running, copy its **Public IP address** from the VM overview page. 8. SSH into the instance: Terminal window ``` ssh -i "your-key.pem" azureuser@ ``` 9. Run `sudo su` to gain full admin rights to the VM. 10. For testing purposes, you can deploy a basic Apache web server on port `80`: Terminal window ``` apt update apt -y install apache2 cat < /var/www/html/index.html

Hello Cloudflare!

This page was created for a Cloudflare demo.

EOF ``` 11. To verify that the Apache server is running, open a browser and go to `http://` (make sure to connect over `http`, not `https`). You should see the **Hello Cloudflare!** test page. ## 2\. Create a tunnel 1. In the [Cloudflare dashboard ↗](https://dash.cloudflare.com/), go to **Networking** \> **Tunnels**. 2. Select **Create Tunnel** and enter a name (for example, `azure-tunnel`). 3. Select **Create Tunnel**. 4. Under **Setup Environment**, select **Debian 64-bit**. 5. Copy the install commands and run them on your Azure VM. 6. Once the tunnel connects, select **Continue**. ## 3\. Publish an application 1. Under **Routes**, select **Add route** \> **Published application**. 2. Enter a hostname (for example, `hellocloudflare..com`). 3. Under **Service**, enter `http://localhost:80`. 4. Select **Add route**. To test, open a browser and go to the hostname you configured. You should see the **Hello Cloudflare!** test page. Looking for private network access? To connect to your Azure VM via private IP using the Cloudflare One Client, refer to the [Cloudflare One Tunnel documentation](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/). ## Firewall configuration To secure your Azure VM, you can configure your [Network Security Group (NSG) ↗](https://learn.microsoft.com/en-us/azure/virtual-network/network-security-groups-overview) to deny all inbound traffic and allow only outbound traffic to the [Cloudflare Tunnel IP addresses](https://developers.cloudflare.com/tunnel/configuration/#required-ports). All NSG rules are evaluated by priority; traffic that does not match an allow rule is blocked by the default deny rules. Therefore, you can delete all custom inbound rules and leave only the relevant outbound rules. Note If you delete the inbound rule for port `22`, you will be unable to SSH back into the VM. After configuring your NSG rules, verify that you can still access the service through Cloudflare Tunnel via its [public hostname](#3-publish-an-application). The service should no longer be accessible from outside Cloudflare Tunnel — for example, direct access to the VM's public IP should no longer work. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/deployment-guides/","name":"Deployment guides"}},{"@type":"ListItem","position":4,"item":{"@id":"/tunnel/deployment-guides/azure/","name":"Azure"}}]} ``` --- --- title: GCP description: This guide covers how to connect a Google Cloud Platform (GCP) virtual machine to Cloudflare using cloudflared and publish a web application through a Cloudflare Tunnel. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/deployment-guides/google-cloud-platform.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # GCP This guide covers how to connect a Google Cloud Platform (GCP) virtual machine to Cloudflare using `cloudflared` and publish a web application through a Cloudflare Tunnel. ### Prerequisites * [A Google Cloud Project ↗](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating%5Fa%5Fproject) * [A zone on Cloudflare](https://developers.cloudflare.com/fundamentals/manage-domains/add-site/) ## 1\. Create a VM instance 1. In your [Google Cloud Console ↗](https://console.cloud.google.com/), [create a new project ↗](https://developers.google.com/workspace/guides/create-project). 2. Go to **Compute Engine** \> **VM instances**. 3. Select **Create instance**. 4. Name your VM instance. In this example we will name it `http-test-server`. 5. Choose your desired operating system and specifications. For this example, you can use the following settings: * **Machine family:** General Purpose * **Series:** E2 * **Machine type:** e2-micro * **Boot disk image:** Debian GNU/Linux 12 * **Firewalls**: Allow HTTP and HTTPS traffic 6. Under **Advanced options** \> **Management** \> **Automation**, add the following startup script. This example deploys a basic Apache web server on port `80`. ``` #!/bin/bash apt update apt -y install apache2 cat < /var/www/html/index.html

Hello Cloudflare!

This page was created for a Cloudflare demo.

EOF ``` 7. Select **Create**. 8. The operating system automatically starts the Apache HTTP server. To verify that the server is running: 1. Copy the **External IP** for the VM instance. 2. Open a browser and go to `http://`. You should see the **Hello Cloudflare!** test page. 9. To login to the VM instance, open the dropdown next to **SSH** and select _Open in browser window_. ## 2\. Create a tunnel 1. In the [Cloudflare dashboard ↗](https://dash.cloudflare.com/), go to **Networking** \> **Tunnels**. 2. Select **Create Tunnel** and enter a name (for example, `gcp-tunnel`). 3. Select **Create Tunnel**. 4. Under **Setup Environment**, select **Debian 64-bit**. 5. SSH into your VM and run the install commands shown in the dashboard. 6. Once the tunnel connects, select **Continue**. ## 3\. Publish an application 1. Under **Routes**, select **Add route** \> **Published application**. 2. Enter a hostname (for example, `hellocloudflare..com`). 3. Under **Service**, enter `http://localhost:80`. 4. Select **Add route**. To test, open a browser and go to the hostname you configured. You can optionally add [Cloudflare Access](https://developers.cloudflare.com/tunnel/integrations/#cloudflare-access) to control who can reach the service. Looking for private network access? To connect to your VM via private IP using the Cloudflare One Client, refer to the [Cloudflare One Tunnel documentation](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/). ## Firewall configuration To secure your VM instance, you can [configure your VPC firewall rules ↗](https://cloud.google.com/firewall/docs/using-firewalls) to deny all ingress traffic and allow only egress traffic to the [Cloudflare Tunnel IP addresses](https://developers.cloudflare.com/tunnel/configuration/#required-ports). Since GCP denies ingress traffic by [default ↗](https://cloud.google.com/firewall/docs/firewalls#default%5Ffirewall%5Frules), you can delete all ingress rules and leave only the relevant egress rules. Note If you delete the default `allow-ssh` rule, you will be unable to SSH back into the VM. After configuring your VPC firewall rules, verify that you can still access the service through Cloudflare Tunnel via its [public hostname](#3-publish-an-application). The service should no longer be accessible from outside Cloudflare Tunnel -- for example, if you go to `http://` the test page should no longer load. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/deployment-guides/","name":"Deployment guides"}},{"@type":"ListItem","position":4,"item":{"@id":"/tunnel/deployment-guides/google-cloud-platform/","name":"GCP"}}]} ``` --- --- title: Kubernetes description: Kubernetes is a container orchestration tool that is used to deploy applications onto physical or virtual machines, scale the deployment to meet traffic demands, and push updates without downtime. The Kubernetes cluster, or environment, where the application instances are running is connected internally through a private network. You can install the cloudflared daemon inside of the Kubernetes cluster in order to connect applications inside of the cluster to Cloudflare. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/deployment-guides/kubernetes.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Kubernetes [Kubernetes ↗](https://kubernetes.io/) is a container orchestration tool that is used to deploy applications onto physical or virtual machines, scale the deployment to meet traffic demands, and push updates without downtime. The Kubernetes cluster, or environment, where the application instances are running is connected internally through a private network. You can install the `cloudflared` daemon inside of the Kubernetes cluster in order to connect applications inside of the cluster to Cloudflare. This guide will cover how to expose a Kubernetes service to the public Internet using a remotely-managed Cloudflare Tunnel. For the purposes of this example, we will deploy a basic web application alongside `cloudflared` in Google Kubernetes Engine (GKE). The same principles apply to any other Kubernetes environment (such as `minikube`, `kubeadm`, or a cloud-based Kubernetes service) where `cloudflared` can connect to Cloudflare's network. Locally-managed tunnels If you are looking to set up a locally-managed tunnel in Kubernetes, refer to the [example code in GitHub ↗](https://github.com/cloudflare/argo-tunnel-examples/tree/master/named-tunnel-k8s). ## Architecture ![Diagram showing how a user connects to Kubernetes services through Cloudflare Tunnel](https://developers.cloudflare.com/_astro/kubernetes-tunnel.C8IQcJlu_h8gOW.webp) As shown in the diagram, we recommend setting up `cloudflared` as an adjacent [deployment ↗](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) to the application deployments. Having a separate Kubernetes deployment for `cloudflared` allows you to scale `cloudflared` independently of the application. In the `cloudflared` deployment, you can spin up [multiple replicas](https://developers.cloudflare.com/tunnel/configuration/#replicas-and-high-availability) running the same Cloudflare Tunnel — there is no need to build a dedicated tunnel for each `cloudflared` pod. Each `cloudflared` replica / pod can reach all Kubernetes services in the cluster. Note We do not recommend using `cloudflared` in autoscaling setups because downscaling (removing replicas) will break existing user connections to that replica. Additionally, `cloudflared` does not load balance across replicas; replicas are strictly for high availability. To load balance traffic to your nodes, you can use [Cloudflare Load Balancer](https://developers.cloudflare.com/load-balancing/private-network/) or a third-party load balancer. Once the cluster is connected to Cloudflare, you can configure Cloudflare Tunnel routes to control how `cloudflared` will proxy traffic to services within the cluster. For example, you may wish to publish certain Kubernetes applications to the Internet and restrict other applications to internal Cloudflare One Client users. ## Prerequisites To complete the following procedure, you will need: * [A Google Cloud Project ↗](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating%5Fa%5Fproject) * [A zone on Cloudflare](https://developers.cloudflare.com/fundamentals/manage-domains/add-site/) ## 1\. Create a GKE cluster To create a new Kubernetes cluster in Google Cloud: 1. Open [Google Cloud ↗](https://console.cloud.google.com/) and go to **Kubernetes Engine**. 2. In **Clusters**, select **Create**. 3. Name the cluster. In this example, we will name it `cloudflare-tunnel`. 4. (Optional) Choose your desired region and other cluster specifications. For this example, we will use the default specifications. 5. Select **Create**. 6. To connect to the cluster: 1. Select the three-dot menu. 2. Select **Connect**. 3. Select **Run in Cloud Shell** to open a terminal in the browser. 4. Select **Authorize**. 5. Press `Enter` to run the pre-populated `gcloud` command. 6. (Recommended) In the Cloud Shell menu, select **Open Editor** to launch the built-in IDE. 7. In the Cloud Shell terminal, run the following command to check the cluster status: Terminal window ``` kubectl get all ``` ``` NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/kubernetes ClusterIP 34.118.224.1 443/TCP 15m ``` ## 2\. Create pods for the web app A pod represents an instance of a running process in the cluster. In this example, we will deploy the [httpbin ↗](https://httpbin.org/) application with two pods and make the pods accessible inside the cluster at `httpbin-service:80`. 1. Create a folder for your Kubernetes manifest files: Terminal window ``` mkdir tunnel-example ``` 2. Change into the directory: Terminal window ``` cd tunnel-example ``` 3. In the `tunnel-example` directory, create a new file called `httpbin.yaml`. This file defines the Kubernetes deployment for the httpbin app. httpbin.yaml ``` apiVersion: apps/v1 kind: Deployment metadata: name: httpbin-deployment namespace: default spec: replicas: 2 selector: matchLabels: app: httpbin template: metadata: labels: app: httpbin spec: containers: - name: httpbin image: kennethreitz/httpbin:latest imagePullPolicy: IfNotPresent ports: - containerPort: 80 ``` 4. Create a new `httpbinsvc.yaml` file. This file defines a Kubernetes service that allows other apps in the cluster (such as `cloudflared`) to access the set of httpbin pods. httpbinsvc.yaml ``` apiVersion: v1 kind: Service metadata: name: httpbin-service namespace: default spec: type: LoadBalancer selector: app: httpbin ports: - port: 80 targetPort: 80 ``` 5. Use the following command to run the application inside the cluster: Terminal window ``` kubectl create -f httpbin.yaml -f httpbinsvc.yaml ``` 6. Check the status of your deployment: Terminal window ``` kubectl get all ``` ``` NAME READY STATUS RESTARTS AGE pod/httpbin-deployment-bc6689c5d-b5ftk 1/1 Running 0 79s pod/httpbin-deployment-bc6689c5d-cbd9m 1/1 Running 0 79s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/httpbin-service LoadBalancer 34.118.225.147 34.75.201.60 80:31967/TCP 79s service/kubernetes ClusterIP 34.118.224.1 443/TCP 24h NAME READY UP-TO-DATE AVAILABLE AGE deployment.apps/httpbin-deployment 2/2 2 2 79s NAME DESIRED CURRENT READY AGE replicaset.apps/httpbin-deployment-bc6689c5d 2 2 2 79s ``` ## 3\. Create a tunnel To create a Cloudflare Tunnel: 1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Networking** \> **Tunnels**. 2. Select **Create Tunnel**. 3. Enter a name for your tunnel (for example, `gke-tunnel`). 4. Select **Save tunnel**. 5. Under **Choose an environment**, select **Docker**. Applications must be packaged into a containerized image before you can run it in Kubernetes. Therefore, we will use the `cloudflared`Docker container image to deploy the tunnel in Kubernetes. 6. Instead of running the installation command, copy just the token value rather than the whole command. The token value is of the form `eyJhIjoiNWFiNGU5Z...` You will need the token for the Kubernetes manifest file. Leave the Cloudflare Tunnel browser tab open while we focus on the Kubernetes deployment. ## 4\. Store the tunnel token `cloudflared` uses a tunnel token to run a remotely-managed Cloudflare Tunnel. You can store the tunnel token in a [Kubernetes secret ↗](https://kubernetes.io/docs/concepts/configuration/secret/). 1. In GKE Cloud Shell, create a `tunnel-token.yaml` file with the following content. Make sure to replace `` with your tunnel token (`eyJhIjoiNWFiNGU5Z...`). tunnel-token.yaml ``` apiVersion: v1 kind: Secret metadata: name: tunnel-token stringData: token: ``` 2. Create the secret: Terminal window ``` kubectl create -f tunnel-token.yaml ``` 3. Check the newly created secret: Terminal window ``` kubectl get secrets ``` ``` NAME TYPE DATA AGE tunnel-token Opaque 1 100s ``` ## 5\. Create pods for cloudflared To run the Cloudflare Tunnel in Kubernetes: 1. Create a Kubernetes deployment for a remotely-managed Cloudflare Tunnel: tunnel.yaml ``` apiVersion: apps/v1 kind: Deployment metadata: name: cloudflared-deployment namespace: default spec: replicas: 2 selector: matchLabels: pod: cloudflared template: metadata: labels: pod: cloudflared spec: securityContext: sysctls: # Allows ICMP traffic (ping, traceroute) to resources behind cloudflared. - name: net.ipv4.ping_group_range value: "65532 65532" containers: - image: cloudflare/cloudflared:latest name: cloudflared env: # Defines an environment variable for the tunnel token. - name: TUNNEL_TOKEN valueFrom: secretKeyRef: name: tunnel-token key: token command: # Configures tunnel run parameters - cloudflared - tunnel - --no-autoupdate - --loglevel - info - --metrics - 0.0.0.0:2000 - run livenessProbe: httpGet: # Cloudflared has a /ready endpoint which returns 200 if and only if # it has an active connection to Cloudflare's network. path: /ready port: 2000 failureThreshold: 1 initialDelaySeconds: 10 periodSeconds: 10 ``` 2. Deploy `cloudflared` to the cluster: Terminal window ``` kubectl create -f tunnel.yaml ``` Kubernetes will install the `cloudflared` image on two pods and run the tunnel using the command `cloudflared tunnel --no-autoupdate --loglevel info --metrics 0.0.0.0:2000 run`. `cloudflared` will consume the tunnel token from the `TUNNEL_TOKEN` environment variable. 3. Check the status of your cluster: Terminal window ``` kubectl get all ``` ``` NAME READY STATUS RESTARTS AGE pod/cloudflared-deployment-6d5f9f9666-85l5w 1/1 Running 0 21s pod/cloudflared-deployment-6d5f9f9666-wb96x 1/1 Running 0 21s pod/httpbin-deployment-bc6689c5d-b5ftk 1/1 Running 0 3m36s pod/httpbin-deployment-bc6689c5d-cbd9m 1/1 Running 0 3m36s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/httpbin-service LoadBalancer 34.118.225.147 34.75.201.60 80:31967/TCP 3m36s service/kubernetes ClusterIP 34.118.224.1 443/TCP 24h NAME READY UP-TO-DATE AVAILABLE AGE deployment.apps/cloudflared-deployment 2/2 2 2 22s deployment.apps/httpbin-deployment 2/2 2 2 3m37s NAME DESIRED CURRENT READY AGE replicaset.apps/cloudflared-deployment-6d5f9f9666 2 2 2 22s replicaset.apps/httpbin-deployment-bc6689c5d 2 2 2 3m37s ``` You should see two `cloudflared` pods and two `httpbin` pods with a `Running` status. If your `cloudflared` pods keep restarting, check the `command` syntax in `tunnel.yaml` and make sure that the [tunnel run parameters](https://developers.cloudflare.com/tunnel/configuration/#run-parameters) are in the correct order. ## 6\. Verify tunnel status To print logs for a `cloudflared` instance: Terminal window ``` kubectl logs pod/cloudflared-deployment-6d5f9f9666-85l5w ``` ``` 2025-06-11T22:00:47Z INF Starting tunnel tunnelID=64c359b6-e111-40ec-a3a9-199c2a656613 2025-06-11T22:00:47Z INF Version 2025.6.0 (Checksum 72f233bb55199093961bf099ad62d491db58819df34b071ab231f622deff33ce) 2025-06-11T22:00:47Z INF GOOS: linux, GOVersion: go1.24.2, GoArch: amd64 2025-06-11T22:00:47Z INF Settings: map[loglevel:debug metrics:0.0.0.0:2000 no-autoupdate:true token:*****] 2025-06-11T22:00:47Z INF Generated Connector ID: aff7c4a0-85a3-4ac9-8475-1e0aa1af8d94 2025-06-11T22:00:47Z DBG Fetched protocol: quic 2025-06-11T22:00:47Z INF Initial protocol quic ... ``` ## 7\. Add a tunnel route Now that the tunnel is up and running, we can route the httpbin service through the tunnel. 1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Networking** \> **Tunnels** and select your tunnel. 2. Under **Routes**, select **Add route** \> **Published application**. 3. Enter a hostname for the application (for example, `httpbin..com`). 4. Under **Service**, enter `http://httpbin-service`. `httpbin-service` is the name of the Kubernetes service defined in `httpbinsvc.yaml`. 5. Select **Add route**. ## 8\. Test the connection To test, open a new browser tab and go to `httpbin..com`. You should see the httpbin homepage. You can optionally add [Cloudflare Access](https://developers.cloudflare.com/tunnel/integrations/#cloudflare-access) to control who can access the service. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/deployment-guides/","name":"Deployment guides"}},{"@type":"ListItem","position":4,"item":{"@id":"/tunnel/deployment-guides/kubernetes/","name":"Kubernetes"}}]} ``` --- --- title: Terraform description: Learn how to deploy a Cloudflare Tunnel using Terraform and our lightweight server-side daemon, cloudflared. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/tunnel/deployment-guides/terraform.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Terraform [Terraform ↗](https://www.terraform.io/) is an infrastructure as code tool that lets you define and manage your tunnels alongside other infrastructure. This guide deploys: * A GCP virtual machine that runs a web server * A Cloudflare Tunnel that makes the server available over the Internet * (Optional) A Cloudflare Access policy that defines who can connect ## Prerequisites * [A Google Cloud Project ↗](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating%5Fa%5Fproject) * [A zone on Cloudflare](https://developers.cloudflare.com/fundamentals/manage-domains/add-site/) ## 1\. Install Terraform Refer to the [Terraform installation guide ↗](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) for your operating system. ## 2\. Install the gcloud CLI 1. [Install the gcloud CLI ↗](https://cloud.google.com/sdk/docs/install) so that Terraform can interact with your GCP account. 2. Authenticate with the CLI by running: Terminal window ``` gcloud auth application-default login ``` ## 3\. Create a Cloudflare API token [Create an API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) so that Terraform can interact with your Cloudflare account. At minimum, your token should include the following permissions: | Type | Item | Permission | | ------- | ------------------------- | ---------- | | Account | Cloudflare Tunnel | Edit | | Account | Access: Apps and Policies | Edit | | Zone | DNS | Edit | ## 4\. Create a configuration directory Terraform functions through a working directory that contains configuration files. You can store your configuration in multiple files or just one — Terraform will evaluate all of the configuration files in the directory as if they were in a single document. 1. Create a folder for your Terraform configuration: Terminal window ``` mkdir cloudflare-tf ``` 2. Change into the directory: Terminal window ``` cd cloudflare-tf ``` ## 5\. Create Terraform configuration files ### Define input variables The following variables will be passed into your GCP and Cloudflare configuration. 1. In your configuration directory, create a `.tf` file: Terminal window ``` touch variables.tf ``` 2. Open the file in a text editor and copy and paste the following: ``` # GCP variables variable "gcp_project_id" { description = "Google Cloud Platform (GCP) project ID" type = string } variable "zone" { description = "Geographical zone for the GCP VM instance" type = string } variable "machine_type" { description = "Machine type for the GCP VM instance" type = string } # Cloudflare variables variable "cloudflare_zone" { description = "Domain used to expose the GCP VM instance to the Internet" type = string } variable "cloudflare_zone_id" { description = "Zone ID for your domain" type = string } variable "cloudflare_account_id" { description = "Account ID for your Cloudflare account" type = string sensitive = true } variable "cloudflare_email" { description = "Email address for your Cloudflare account" type = string sensitive = true } variable "cloudflare_token" { description = "Cloudflare API token" type = string sensitive = true } ``` ### Assign values to the variables 1. In your configuration directory, create a `.tfvars` file: Terminal window ``` touch terraform.tfvars ``` Terraform will automatically use these variables if the file is named `terraform.tfvars`, otherwise the variable file will need to be manually passed in. 2. Add the following variables to `terraform.tfvars`. Be sure to modify the example with your own values. ``` cloudflare_zone = "example.com" cloudflare_zone_id = "023e105f4ecef8ad9ca31a8372d0c353" cloudflare_account_id = "372e67954025e0ba6aaa6d586b9e0b59" cloudflare_email = "user@example.com" cloudflare_token = "y3AalHS_E7Vabk3c3lX950F90_Xl7YtjSlzyFn_X" gcp_project_id = "testvm-123" zone = "us-central1-a" machine_type = "e2-medium" ``` Warning To prevent accidentally exposing sensitive credentials, do not save `terraform.tfvars` in your version control system. For example, if your version control is git, add `terraform.tfvars` to your `.gitignore` file. ### Configure Terraform providers You will need to declare the [providers ↗](https://registry.terraform.io/browse/providers) used to provision the infrastructure. 1. In your configuration directory, create a `.tf` file: Terminal window ``` touch providers.tf ``` 2. Add the following providers to `providers.tf`. The `random` provider is used to generate a tunnel secret. * [ Terraform (v5) ](#tab-panel-6686) * [ Terraform (v4) ](#tab-panel-6687) ``` terraform { required_providers { cloudflare = { source = "cloudflare/cloudflare" version = ">= 5.8.2" } google = { source = "hashicorp/google" } } required_version = ">= 1.2" } # Providers provider "cloudflare" { api_token = var.cloudflare_token } provider "google" { project = var.gcp_project_id } provider "random" { } ``` ``` terraform { required_providers { cloudflare = { source = "cloudflare/cloudflare" version = ">= 4.40.0, < 5.0.0" } google = { source = "hashicorp/google" } random = { source = "hashicorp/random" } } required_version = ">= 1.2" } # Providers provider "cloudflare" { api_token = var.cloudflare_token } provider "google" { project = var.gcp_project_id } provider "random" { } ``` ### Configure Cloudflare resources The following configuration will modify settings in your Cloudflare account. 1. In your configuration directory, create a `.tf` file: Terminal window ``` touch Cloudflare-config.tf ``` 2. Add the following resources to `Cloudflare-config.tf`: * [ Terraform (v5) ](#tab-panel-6682) * [ Terraform (v4) ](#tab-panel-6683) ``` # Creates a new remotely-managed tunnel for the GCP VM. resource "cloudflare_zero_trust_tunnel_cloudflared" "gcp_tunnel" { account_id = var.cloudflare_account_id name = "Terraform GCP tunnel" config_src = "cloudflare" } # Reads the token used to run the tunnel on the server. data "cloudflare_zero_trust_tunnel_cloudflared_token" "gcp_tunnel_token" { account_id = var.cloudflare_account_id tunnel_id = cloudflare_zero_trust_tunnel_cloudflared.gcp_tunnel.id } # Creates the CNAME record that routes http_app.${var.cloudflare_zone} to the tunnel. resource "cloudflare_dns_record" "http_app" { zone_id = var.cloudflare_zone_id name = "http_app" content = "${cloudflare_zero_trust_tunnel_cloudflared.gcp_tunnel.id}.cfargotunnel.com" type = "CNAME" ttl = 1 proxied = true } # Configures tunnel with a published application for clientless access. resource "cloudflare_zero_trust_tunnel_cloudflared_config" "gcp_tunnel_config" { tunnel_id = cloudflare_zero_trust_tunnel_cloudflared.gcp_tunnel.id account_id = var.cloudflare_account_id config = { ingress = [ { hostname = "http_app.${var.cloudflare_zone}" service = "http://httpbin:80" }, { service = "http_status:404" } ] } } # (Optional) Routes internal IP of GCP instance through the tunnel for private network access using WARP. resource "cloudflare_zero_trust_tunnel_cloudflared_route" "example_tunnel_route" { account_id = var.cloudflare_account_id tunnel_id = cloudflare_zero_trust_tunnel_cloudflared.gcp_tunnel.id network = google_compute_instance.http_server.network_interface.0.network_ip comment = "Example tunnel route" } # Creates a reusable Access policy. resource "cloudflare_zero_trust_access_policy" "allow_emails" { account_id = var.cloudflare_account_id name = "Allow email addresses" decision = "allow" include = [ { email = { email = var.cloudflare_email } }, { email_domain = { domain = "@example.com" } } ] } # Creates an Access application to control who can connect to the public hostname. resource "cloudflare_zero_trust_access_application" "http_app" { account_id = var.cloudflare_account_id type = "self_hosted" name = "Access application for http_app.${var.cloudflare_zone}" domain = "http_app.${var.cloudflare_zone}" policies = [ { id = cloudflare_zero_trust_access_policy.allow_emails.id precedence = 1 } ] } ``` ``` # Generates a 32-byte secret for the tunnel. resource "random_bytes" "tunnel_secret" { byte_length = 32 } # Creates a new remotely-managed tunnel for the GCP VM. resource "cloudflare_zero_trust_tunnel_cloudflared" "gcp_tunnel" { account_id = var.cloudflare_account_id name = "Terraform GCP tunnel" secret = random_bytes.tunnel_secret.base64 } # Creates the CNAME record that routes http_app.${var.cloudflare_zone} to the tunnel. resource "cloudflare_record" "http_app" { zone_id = var.cloudflare_zone_id name = "http_app" content = "${cloudflare_zero_trust_tunnel_cloudflared.gcp_tunnel.cname}" type = "CNAME" proxied = true } # Configures tunnel with a published application for clientless access. resource "cloudflare_zero_trust_tunnel_cloudflared_config" "gcp_tunnel_config" { tunnel_id = cloudflare_zero_trust_tunnel_cloudflared.gcp_tunnel.id account_id = var.cloudflare_account_id config { ingress_rule { hostname = "${cloudflare_record.http_app.hostname}" service = "http://httpbin:80" } ingress_rule { service = "http_status:404" } } } # (Optional) Route internal IP of GCP instance through the tunnel for private network access using WARP. resource "cloudflare_zero_trust_tunnel_route" "example_tunnel_route" { account_id = var.cloudflare_account_id tunnel_id = cloudflare_zero_trust_tunnel_cloudflared.gcp_tunnel.id network = google_compute_instance.http_server.network_interface.0.network_ip comment = "Example tunnel route" } # Creates an Access application to control who can connect to the public hostname. resource "cloudflare_zero_trust_access_application" "http_app" { account_id = var.cloudflare_account_id name = "Access application for http_app.${var.cloudflare_zone}" domain = "http_app.${var.cloudflare_zone}" } # Creates a (legacy) Access policy for the Access application. resource "cloudflare_zero_trust_access_policy" "allow_emails" { application_id = cloudflare_zero_trust_access_application.http_app.id account_id = var.cloudflare_account_id name = "Example policy for http_app.${var.cloudflare_zone}" precedence = "1" decision = "allow" include { email = [var.cloudflare_email] } } ``` To learn more about these resources, refer to the [Cloudflare provider documentation ↗](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs). ### Configure GCP resources The following configuration defines the specifications for the GCP virtual machine and configures a startup script to run upon boot. 1. In your configuration directory, create a `.tf` file: Terminal window ``` touch GCP-config.tf ``` 2. Add the following content to `GCP-config.tf`: * [ Terraform (v5) ](#tab-panel-6684) * [ Terraform (v4) ](#tab-panel-6685) ``` # OS the server will use data "google_compute_image" "image" { family = "ubuntu-2204-lts" project = "ubuntu-os-cloud" } # GCP Instance resource resource "google_compute_instance" "http_server" { name = "test" machine_type = var.machine_type zone = var.zone tags = [] boot_disk { initialize_params { image = data.google_compute_image.image.self_link } } network_interface { network = "default" access_config { //Ephemeral IP } } // Optional config to make instance ephemeral /* scheduling { preemptible = true automatic_restart = false } */ // Pass the tunnel token to the GCP server so that the server can install and run the tunnel upon startup. metadata_startup_script = templatefile("./install-tunnel.tftpl", { tunnel_token = data.cloudflare_zero_trust_tunnel_cloudflared_token.gcp_tunnel_token.token }) } ``` ``` # OS the server will use data "google_compute_image" "image" { family = "ubuntu-2204-lts" project = "ubuntu-os-cloud" } # GCP Instance resource resource "google_compute_instance" "http_server" { name = "test" machine_type = var.machine_type zone = var.zone tags = [] boot_disk { initialize_params { image = data.google_compute_image.image.self_link } } network_interface { network = "default" access_config { //Ephemeral IP } } // Optional config to make instance ephemeral /* scheduling { preemptible = true automatic_restart = false } */ // Pass the tunnel token to the GCP server so that the server can install and run the tunnel upon startup. metadata_startup_script = templatefile("./install-tunnel.tftpl", { tunnel_token = cloudflare_zero_trust_tunnel_cloudflared.gcp_tunnel.tunnel_token }) } ``` ### Create a startup script The following script will install `cloudflared` and run the tunnel as a service. This example also installs a lightweight HTTP application that you can use to test connectivity. 1. In your configuration directory, create a Terraform template file: Terminal window ``` touch install-tunnel.tftpl ``` 2. Open the file in a text editor and copy and paste the following bash script: Terminal window ``` # Script to install Cloudflare Tunnel and Docker resources # Docker configuration cd /tmp sudo apt-get install software-properties-common # Retrieving the docker repository for this OS curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu bionic stable" # The OS is updated and docker is installed sudo apt update -y && sudo apt upgrade -y sudo apt install docker docker-compose -y # Add the HTTPBin application and run it on localhost:8080. cat > /tmp/docker-compose.yml << "EOF" version: '3' services: httpbin: image: kennethreitz/httpbin restart: always container_name: httpbin ports: - 8080:80 cloudflared: image: cloudflare/cloudflared:latest restart: always container_name: cloudflared command: tunnel run --token ${tunnel_token} EOF cd /tmp sudo docker-compose up -d ``` ## 6\. Deploy Terraform To deploy the configuration files: 1. Initialize your configuration directory: Terminal window ``` terraform init ``` 2. Preview everything that will be created: Terminal window ``` terraform plan ``` 3. Apply the configuration: Terminal window ``` terraform apply ``` It may take several minutes for the GCP instance and tunnel to come online. You can view your new tunnel in the [Cloudflare dashboard ↗](https://dash.cloudflare.com/) under **Networking** \> **Tunnels**. Remove Terraform resources If you need to roll back the configuration, run `terraform destroy` to delete everything created through Terraform. Both `terraform apply` and `terraform destroy` prompt for user input before applying the changes. To run without requiring user input, you can add the `-auto-approve` flag to the command. ## 7\. Test the connection 1. In the [Cloudflare dashboard ↗](https://dash.cloudflare.com/), go to **Networking** \> **Tunnels** and verify that your tunnel is **Active**. 2. (Optional) If you configured Access, go to **Security** \> **Access** \> **Applications** and verify that your Cloudflare email is allowed by the Access policy. 3. From any device, open a browser and go to `http_app.` (for example, `http_app.example.com`). If you configured Access, you will see the Access login page. Log in with your Cloudflare email. 4. You should see the HTTPBin homepage, confirming that your tunnel is routing traffic correctly. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/tunnel/","name":"Cloudflare Tunnel"}},{"@type":"ListItem","position":3,"item":{"@id":"/tunnel/deployment-guides/","name":"Deployment guides"}},{"@type":"ListItem","position":4,"item":{"@id":"/tunnel/deployment-guides/terraform/","name":"Terraform"}}]} ```