mirror of
https://github.com/ksyasuda/dotfiles.git
synced 2026-03-22 06:11:27 -07:00
148 lines
3.8 KiB
Markdown
148 lines
3.8 KiB
Markdown
# Tunnel Gotchas
|
|
|
|
## Common Errors
|
|
|
|
### "Error 1016 (Origin DNS Error)"
|
|
|
|
**Cause:** Tunnel not running or not connected
|
|
**Solution:**
|
|
```bash
|
|
cloudflared tunnel info my-tunnel # Check status
|
|
ps aux | grep cloudflared # Verify running
|
|
journalctl -u cloudflared -n 100 # Check logs
|
|
```
|
|
|
|
### "Self-signed certificate rejected"
|
|
|
|
**Cause:** Origin using self-signed certificate
|
|
**Solution:**
|
|
```yaml
|
|
originRequest:
|
|
noTLSVerify: true # Dev only
|
|
caPool: /path/to/ca.pem # Custom CA
|
|
```
|
|
|
|
### "Connection timeout"
|
|
|
|
**Cause:** Origin slow to respond or timeout settings too low
|
|
**Solution:**
|
|
```yaml
|
|
originRequest:
|
|
connectTimeout: 60s
|
|
tlsTimeout: 20s
|
|
keepAliveTimeout: 120s
|
|
```
|
|
|
|
### "Tunnel not starting"
|
|
|
|
**Cause:** Invalid config, missing credentials, or tunnel doesn't exist
|
|
**Solution:**
|
|
```bash
|
|
cloudflared tunnel ingress validate # Validate config
|
|
ls -la ~/.cloudflared/*.json # Verify credentials
|
|
cloudflared tunnel list # Verify tunnel exists
|
|
```
|
|
|
|
### "Connection already registered"
|
|
|
|
**Cause:** Multiple replicas with same connector ID or stale connection
|
|
**Solution:**
|
|
```bash
|
|
# Check active connections
|
|
cloudflared tunnel info my-tunnel
|
|
|
|
# Wait 60s for stale connection cleanup, or restart with new connector ID
|
|
cloudflared tunnel run my-tunnel
|
|
```
|
|
|
|
### "Tunnel credentials rotated but connections fail"
|
|
|
|
**Cause:** Old cloudflared processes using expired credentials
|
|
**Solution:**
|
|
```bash
|
|
# Stop all cloudflared processes
|
|
pkill cloudflared
|
|
|
|
# Verify stopped
|
|
ps aux | grep cloudflared
|
|
|
|
# Restart with new credentials
|
|
cloudflared tunnel run my-tunnel
|
|
```
|
|
|
|
## Limits
|
|
|
|
| Resource/Limit | Value | Notes |
|
|
|----------------|-------|-------|
|
|
| Free tier | Unlimited tunnels | Unlimited traffic |
|
|
| Tunnel replicas | 1000 per tunnel | Max concurrent |
|
|
| Connection duration | No hard limit | Hours to days |
|
|
| Long-lived connections | May drop during updates | WebSocket, SSH, UDP |
|
|
| Replica registration | ~5s TTL | Old replica dropped after 5s no heartbeat |
|
|
| Token rotation grace | 24 hours | Old tokens work during grace period |
|
|
|
|
## Best Practices
|
|
|
|
### Security
|
|
1. Use token-based tunnels (config source: cloudflare) for centralized control
|
|
2. Enable Access policies for sensitive services
|
|
3. Rotate tunnel credentials regularly
|
|
4. After rotation: stop all old cloudflared processes within 24h grace period
|
|
5. Verify TLS certs (`noTLSVerify: false`)
|
|
6. Restrict `bastion` service type
|
|
|
|
### Performance
|
|
1. Run multiple replicas for HA (2-4 typical, load balanced automatically)
|
|
2. Replicas share same tunnel UUID, get unique connector IDs
|
|
3. Place `cloudflared` close to origin (same network)
|
|
4. Use HTTP/2 for gRPC (`http2Origin: true`)
|
|
5. Tune keepalive for long-lived connections
|
|
6. Monitor connection counts
|
|
|
|
### Configuration
|
|
1. Use environment variables for secrets
|
|
2. Version control config files
|
|
3. Validate before deploying (`cloudflared tunnel ingress validate`)
|
|
4. Test rules (`cloudflared tunnel ingress rule <URL>`)
|
|
5. Document rule order (first match wins)
|
|
|
|
### Operations
|
|
1. Monitor tunnel health in dashboard (shows active replicas)
|
|
2. Set up disconnect alerts (when replica count drops to 0)
|
|
3. Graceful shutdown for config updates
|
|
4. Update replicas in rolling fashion (update 1, wait, update next)
|
|
5. Keep `cloudflared` updated (1 year support window)
|
|
6. Use `--no-autoupdate` in prod; control updates manually
|
|
|
|
## Debug Mode
|
|
|
|
```bash
|
|
cloudflared tunnel --loglevel debug run my-tunnel
|
|
cloudflared tunnel ingress rule https://app.example.com
|
|
```
|
|
|
|
## Migration Strategies
|
|
|
|
### From Ngrok
|
|
```yaml
|
|
# Ngrok: ngrok http 8000
|
|
# Cloudflare Tunnel:
|
|
ingress:
|
|
- hostname: app.example.com
|
|
service: http://localhost:8000
|
|
- service: http_status:404
|
|
```
|
|
|
|
### From VPN
|
|
```yaml
|
|
# Replace VPN with private network routing
|
|
warp-routing:
|
|
enabled: true
|
|
```
|
|
|
|
```bash
|
|
cloudflared tunnel route ip add 10.0.0.0/8 my-tunnel
|
|
```
|
|
|
|
Users install WARP client instead of VPN.
|