1# Tunnel Configuration
2 
3## Config Source
4 
5Tunnels use one of two config sources:
6 
7| Config Source | Storage | Updates | Use Case |
8|---------------|---------|---------|----------|
9| Local | `config.yml` file | Edit file, restart | Dev, multi-env, version control |
10| Cloudflare | Dashboard/API | Instant, no restart | Production, centralized management |
11 
12**Token-based tunnels** = config source: Cloudflare
13**Locally-managed tunnels** = config source: local
14 
15## Config File Location
16 
17```
18~/.cloudflared/config.yml          # User config
19/etc/cloudflared/config.yml        # System-wide (Linux)
20```
21 
22## Basic Structure
23 
24```yaml
25tunnel: <UUID>
26credentials-file: /path/to/<UUID>.json
27 
28ingress:
29  - hostname: app.example.com
30    service: http://localhost:8000
31  - service: http_status:404  # Required catch-all
32```
33 
34## Ingress Rules
35 
36Rules evaluated **top to bottom**, first match wins.
37 
38```yaml
39ingress:
40  # Exact hostname + path regex
41  - hostname: static.example.com
42    path: \.(jpg|png|css|js)$
43    service: https://localhost:8001
44  
45  # Wildcard hostname
46  - hostname: "*.example.com"
47    service: https://localhost:8002
48  
49  # Path only (all hostnames)
50  - path: /api/.*
51    service: http://localhost:9000
52  
53  # Catch-all (required)
54  - service: http_status:404
55```
56 
57**Validation**:
58```bash
59cloudflared tunnel ingress validate
60cloudflared tunnel ingress rule https://foo.example.com
61```
62 
63## Service Types
64 
65| Protocol | Format | Client Requirement |
66|----------|--------|-------------------|
67| HTTP | `http://localhost:8000` | Browser |
68| HTTPS | `https://localhost:8443` | Browser |
69| TCP | `tcp://localhost:2222` | `cloudflared access tcp` |
70| SSH | `ssh://localhost:22` | `cloudflared access ssh` |
71| RDP | `rdp://localhost:3389` | `cloudflared access rdp` |
72| Unix | `unix:/path/to/socket` | Browser |
73| Test | `hello_world` | Browser |
74 
75## Origin Configuration
76 
77### Connection Settings
78```yaml
79originRequest:
80  connectTimeout: 30s
81  tlsTimeout: 10s
82  tcpKeepAlive: 30s
83  keepAliveTimeout: 90s
84  keepAliveConnections: 100
85```
86 
87### TLS Settings
88```yaml
89originRequest:
90  noTLSVerify: true                      # Disable cert verification
91  originServerName: "app.internal"       # Override SNI
92  caPool: /path/to/ca.pem                # Custom CA
93```
94 
95### HTTP Settings
96```yaml
97originRequest:
98  disableChunkedEncoding: true
99  httpHostHeader: "app.internal"
100  http2Origin: true
101```
102 
103## Private Network Mode
104 
105```yaml
106tunnel: <UUID>
107credentials-file: /path/to/creds.json
108 
109warp-routing:
110  enabled: true
111```
112 
113```bash
114cloudflared tunnel route ip add 10.0.0.0/8 my-tunnel
115cloudflared tunnel route ip add 192.168.1.100/32 my-tunnel
116```
117 
118## Config Source Comparison
119 
120### Local Config
121```yaml
122# config.yml
123tunnel: <UUID>
124credentials-file: /path/to/<UUID>.json
125 
126ingress:
127  - hostname: app.example.com
128    service: http://localhost:8000
129  - service: http_status:404
130```
131 
132```bash
133cloudflared tunnel run my-tunnel
134```
135 
136**Pros:** Version control, multi-environment, offline edits
137**Cons:** Requires file distribution, manual restarts
138 
139### Cloudflare Config (Token-Based)
140```bash
141# No config file needed
142cloudflared tunnel --no-autoupdate run --token <TOKEN>
143```
144 
145Configure routes in dashboard: **Zero Trust** > **Networks** > **Tunnels** > [Tunnel] > **Public Hostname**
146 
147**Pros:** Centralized updates, no file management, instant route changes
148**Cons:** Requires dashboard/API access, less portable
149 
150## Environment Variables
151 
152```bash
153TUNNEL_TOKEN=<token>                    # Token for config source: cloudflare
154TUNNEL_ORIGIN_CERT=/path/to/cert.pem   # Override cert path (local config)
155NO_AUTOUPDATE=true                      # Disable auto-updates
156TUNNEL_LOGLEVEL=debug                   # Log level
157```
158