Cloudflare Tunnel Recovery Tutorial

Problem Overview

Missing Cloudflare Tunnel Credentials

You have a Cloudflare tunnel configuration file but the credentials JSON file is missing or corrupted.

Config file exists: config.yml
Missing credentials file: /home/user/.cloudflared/{tunnel-id}.json
Error: "Cannot determine default origin certificate path"
Error: "credentials file not found"

Prerequisites

Cloudflare Account

Active account with tunnel access permissions

Cloudflared CLI

Latest version of cloudflared installed

Existing Tunnel

Tunnel not deleted from Cloudflare dashboard

Step 1: Authenticate with Cloudflare

First, authenticate your local cloudflared client with your Cloudflare account:

bash

cloudflared tunnel login

What happens:

Opens browser to Cloudflare dashboard
You select your domain/account
Creates certificate file (usually in /root/.cloudflared/cert.pem if run with sudo)

Step 2: List Your Existing Tunnels

Check what tunnels are available in your account:

bash

# Use sudo if certificate is in /root/.cloudflared/
sudo cloudflared tunnel list

output

ID                                   NAME            CREATED              CONNECTIONS
12345678-1234-1234-1234-123456789012 my-tunnel       2025-06-29T12:05:42Z

📝 Important: Note down your tunnel ID and name for the next steps.

Step 3: Generate Tunnel Token

Generate a token that contains all the credentials you need:

bash

sudo cloudflared tunnel token YOUR_TUNNEL_NAME

output

eyJhIjoiYWJjZGVmZ2hpams...rest_of_token

✨ Success: This token contains all the credentials you need! Save it safely.

Step 4: Decode Token to Extract Credentials

The token is base64 encoded JSON. Let's decode it to see the credentials structure:

bash

echo "YOUR_TOKEN_HERE" | base64 -d

json

{
  "a": "your_account_id_here",
  "s": "your_tunnel_secret_here",
  "t": "your_tunnel_id_here"
}

Credential Mapping:

"a" → AccountTag

"s" → TunnelSecret

"t" → TunnelID

Step 5: Create Credentials File

Create the missing JSON file with the decoded values:

bash

sudo tee /home/user/.cloudflared/YOUR_TUNNEL_ID.json << 'EOF'
{
  "AccountTag": "your_account_id_from_step_4",
  "TunnelSecret": "your_tunnel_secret_from_step_4",
  "TunnelID": "your_tunnel_id_from_step_4"
}
EOF

File Location Pattern:

/home/user/.cloudflared/{tunnel-id}.json

Step 6: Configure & Test

Verify your config file and test the tunnel:

yaml config.yml

tunnel: your-tunnel-name
credentials-file: /home/user/.cloudflared/YOUR_TUNNEL_ID.json
ingress:
  - hostname: example.yourdomain.com
    service: http://localhost:8000
  - service: http_status:404

bash

# Try without sudo first (preferred)
cloudflared tunnel --config ~/.cloudflared/config.yml run your-tunnel-name

# If permission issues, use sudo
sudo cloudflared tunnel --config ~/.cloudflared/config.yml run your-tunnel-name

Alternative: Using Token Directly

Instead of creating a credentials file, you can run the tunnel directly with the token (simpler approach):

bash

cloudflared tunnel --token "YOUR_TOKEN_FROM_STEP_3" run

✅ Pros:

Simpler setup
No file management
Works immediately

❌ Cons:

Token in command history
No config file benefits
Harder to manage multiple ingress rules

Troubleshooting

🚫 Permission Denied

Problem: Certificate saved to /root/.cloudflared/ but running as regular user

Solution:

# Copy certificate
sudo cp /root/.cloudflared/cert.pem ~/.cloudflared/
# OR run commands with sudo

🔐 Directory Ownership

Problem: .cloudflared directory owned by root

Solution:

sudo chown -R $USER:$USER ~/.cloudflared/

❌ Tunnel Not Found

Problem: Tunnel was deleted from Cloudflare dashboard

Solution:

cloudflared tunnel create new-tunnel-name
cloudflared tunnel route dns new-tunnel-name your-hostname.domain.com

Key Points to Remember

🎯

Token contains everything

The base64 token from cloudflared tunnel token has all credentials

📁

File naming matters

Credentials file must be named exactly {tunnel-id}.json

📍

Location is crucial

Credentials file path in config must match actual file location

🔒

Permissions matter

Ensure proper ownership of .cloudflared directory and files

⚡

Security first

Avoid running with sudo when possible

🗂️

File structure

Keep organized: cert.pem, config.yml, {tunnel-id}.json