# Secure Tunnel Agent Setup & Troubleshooting (Legacy)

> **Note:** This documentation references the legacy cloudflared-based tunnel setup.
> For new installations, use the **TuneVault Agent Installer** (`install.sh`) which provides
> automatic tunnel agent provisioning with no manual tunnel configuration needed.

This runbook covers the complete secure tunnel agent → tunevault-proxy setup and how to diagnose the most common failure modes.

## Architecture

```
Browser / TuneVault dashboard
        │
        ▼ HTTPS
proxy.tunevault.app (DNS → Secure Tunnel)
        │
        ▼ Secure Tunnel Agent (tunnel-agent daemon)
localhost:8080 (oracle-proxy.py = tunevault-proxy.service)
        │
        ▼ cx_Oracle / TCP 1521
Oracle DB
```

Two systemd services must be running simultaneously:

| Service | What it does | Port |
|---------|-------------|------|
| `tunevault-proxy` | Python Oracle HTTP proxy | localhost:8080 |
| `tunnel-agent` | Tunnel daemon connecting to secure tunnel service | no inbound port |

---

## Initial Setup

The new installer (`install.sh` via TuneVault UI) handles everything automatically:

```bash
# Generated by TuneVault UI after connection creation
curl -fsSL https://tunevault.app/install.sh | sudo TUNEVAULT_TOKEN=<token> bash
```

If you have a legacy tunnel setup, you can still use the old installer:

```bash
sudo ./oracle-proxy-install.sh \
  --tunnel-token <token-from-ui> \
  --hostname proxy.yourdomain.com
```

After installing via `install.sh`, the DNS is automatically configured. If using the legacy setup:

```bash
tunnel-agent tunnel route dns ebs-proxy proxy.tunevault.app
```

---

## config.yml Reference

`/etc/tunnel-agent/config.yml` must contain:

```yaml
tunnel: <tunnel-uuid>
credentials-file: /etc/tunnel-agent/<tunnel-uuid>.json

ingress:
  - hostname: proxy.tunevault.app
    service: http://localhost:8080
  - service: http_status:404
```

**The catch-all `- service: http_status:404` line is required** — tunnel-agent will refuse to start without it.

To force regenerate (if config is wrong):

```bash
sudo ./oracle-proxy-install.sh --tunnel-uuid <uuid> --creds-file /path/to/creds.json --force
```

---

## Error Code Reference

### Error 1016 — No Origin / Ingress Rule Missing

**Meaning:** Cloudflare received the request but has no rule routing `proxy.tunevault.app` to your tunnel.

**Root causes:**
- DNS route not registered: `tunnel-agent tunnel route dns` was never run
- `config.yml` is missing the ingress block
- Wrong tunnel UUID (config references a different tunnel than the DNS points to)

**Fix:**
```bash
# 1. Register DNS route
tunnel-agent tunnel route dns ebs-proxy proxy.tunevault.app

# 2. Verify config.yml has the ingress block
cat /etc/cloudflared/config.yml

# 3. Restart cloudflared to pick up config
systemctl restart cloudflared
journalctl -u cloudflared --no-pager -n 20
```

---

### Error 521 — Origin Down

**Meaning:** cloudflared connected to Cloudflare successfully, but the Python proxy at `localhost:8080` is not responding.

**Fix:**
```bash
# Check service status
systemctl status tunevault-proxy

# View recent logs
journalctl -u tunevault-proxy --no-pager -n 30

# Check the proxy actually listens on 8080
curl http://localhost:8080/health

# If PORT is wrong in .env:
grep PORT /opt/tunevault-proxy/.env
# Add or correct: PORT=8080
systemctl restart tunevault-proxy
```

---

### Error 522 — Tunnel Agent Not Connected

**Meaning:** Tunnel agent is installed but not maintaining a connection to the tunnel service.

**Fix:**
```bash
# Check daemon status
systemctl status tunnel-agent
journalctl -u tunnel-agent --no-pager -n 30

# Common causes:
# - credentials JSON path in config.yml points to a file that doesn't exist
# - Tunnel UUID mismatch between config.yml and credentials JSON
# - Outbound TCP 7844 or UDP QUIC blocked by firewall

# Verify credentials file
cat /etc/tunnel-agent/config.yml | grep credentials-file
ls -la <path shown above>

# Test manually
tunnel-agent tunnel --config /etc/tunnel-agent/config.yml run
```

---

### Error 530 — Tunnel Service Not Configured / DNS Not Propagated

**Meaning:** The tunnel service can't resolve the tunnel. Usually a DNS propagation delay or missing DNS record.

**Fix:**
```bash
# Wait 2-5 minutes, then retry
curl https://proxy.tunevault.app/health

# Verify DNS record is configured
# Zero Trust → Access → Tunnels → ebs-proxy → Public Hostnames

# If missing, re-add:
tunnel-agent tunnel route dns ebs-proxy proxy.tunevault.app
```

---

## Idempotent Re-run

Re-running the installer is safe. It skips existing config unless you pass `--force`:

```bash
# Re-run without overwriting existing config
sudo ./oracle-proxy-install.sh --tunnel-uuid <uuid> --creds-file /path/to/creds.json

# Force overwrite all config files
sudo ./oracle-proxy-install.sh --tunnel-uuid <uuid> --creds-file /path/to/creds.json --force
```

**Never silently overwritten:** The credentials JSON (`--creds-file`) is validated but never modified by the installer.

---

## Manual Health Verification

```bash
# 1. Python proxy local health
curl http://localhost:8080/health
# Expected: {"status":"ok", ...}

# 2. Cloudflare tunnel end-to-end
curl https://proxy.tunevault.app/health
# Expected: same JSON (proxied via cloudflared)

# 3. Service status
systemctl status tunevault-proxy cloudflared

# 4. Live log tail
journalctl -u tunevault-proxy -f &
journalctl -u cloudflared -f
```

---

## proxy.env Security

```bash
# Restrict permissions (installer does this automatically)
chmod 600 /opt/tunevault-proxy/.env

# Encrypt for compliance environments
openssl enc -aes-256-cbc -pbkdf2 -in /opt/tunevault-proxy/.env -out /opt/tunevault-proxy/.env.enc

# Decrypt when needed
openssl enc -d -aes-256-cbc -pbkdf2 -in /opt/tunevault-proxy/.env.enc -out /opt/tunevault-proxy/.env
```

---

*Last updated: 2026-05-15 — Installer v2.0*
