Skip to content
Cloudflare Docs

Remotely-managed tunnel

If you created a Cloudflare Tunnel from the dashboard, the tunnel runs as a service on your OS.

Add tunnel run parameters

You can modify the Cloudflare Tunnel service with one or more general-purpose tunnel parameters.

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 debug --logfile /var/log/cloudflared/cloudflared.log run --token <TOKEN VALUE>
    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 debug --logfile /var/log/cloudflared/cloudflared.log run --token eyJhIjoi...

Update origin configuration

To configure how cloudflared sends requests to your public hostname services:

  1. In Zero Trust ↗, go to Networks > Tunnels.
  2. Choose a tunnel and select Configure.
  3. Select the Public Hostname tab.
  4. Choose a route and select Edit.
  5. Under Additional application settings, modify one or more origin configuration parameters.
  6. Select Save hostname.

Tunnel permissions

A remotely-managed tunnel only requires the tunnel token to run. Anyone with access to the token will be able to run the tunnel.

View the tunnel token

To get the token for a remotely-managed tunnel:

  1. In Zero Trust ↗, go to Networks > Tunnels.
  2. Select a cloudflared tunnel and select Edit.
  3. Copy cloudflared installation command.
  4. Paste the installation command into any text editor. The token value is of the form eyJhIjoiNWFiNGU5Z...

Rotate a token without service disruption

Cloudflare recommends rotating the tunnel token at a regular cadence to reduce the risk of token compromise. You can rotate a token with minimal disruption to users as long as the tunnel is served by at least two cloudflared replicas. To ensure service availability, we recommend performing token rotations outside of working hours or in a maintenance window.

To rotate a tunnel token:

  1. Refresh the token on Cloudflare:

    1. In Zero Trust ↗, go to Networks > Tunnels.
    2. Select a cloudflared tunnel and select Edit.
    3. Select Refresh token.
    4. Copy the cloudflared installation command for your operating system. This command contains the new token.

    After refreshing the token, cloudflared can no longer establish new connections to Cloudflare using the old token. However, existing connectors will remain active and the tunnel will continue serving traffic.

  2. On half of your cloudflared replicas, update cloudflared to use the new token. For example, on a Linux host:

    Terminal window
    sudo cloudflared service install <TOKEN>

  3. Restart cloudflared:

    Terminal window
    sudo systemctl restart cloudflared.service

  4. Confirm that the service started correctly:

    Terminal window
    sudo systemctl status cloudflared

    While these replicas are connecting to Cloudflare with the new token, traffic will automatically route through the other replicas.

  5. Wait 10 minutes for traffic to route through the new connectors.

  6. Repeat steps 2, 3, and 4 for the second half of the replicas.

The tunnel token is now fully rotated. The old token is no longer in use.

Rotate a compromised token

If your tunnel token is compromised, we recommend taking the following steps:

  1. Refresh the token using the dashboard or API. Refer to Step 1 of Rotate a token without service disruption.

  2. Delete all connections between cloudflared and Cloudflare:

    Terminal window
    curl --request DELETE \
    https://api.cloudflare.com/client/v4/accounts/{account_id}/cfd_tunnel/{tunnel_id}/connections \
    --header "Authorization: Bearer <API_TOKEN>"

    This will clean up any unauthorized connections and prevent users from connecting to your network.

  3. On each cloudflared replica, update cloudflared to use the new token. For example, on a Linux host:

    Terminal window
    sudo cloudflared service install <TOKEN>

  4. Restart cloudflared:

    Terminal window
    sudo systemctl restart cloudflared.service

  5. Confirm that the service started correctly:

    Terminal window
    sudo systemctl status cloudflared

The tunnel token is now fully rotated. The old token is no longer in use.

Account-scoped roles

Minimum permissions needed to create, delete, and configure tunnels for an account:

Additional permissions needed to route traffic to a public hostname: