TuneVault Agent Connection Failure — Diagnosis & Recovery Runbook

1. How the Agent Connection Works

TuneVault's architecture is outbound-only. The agent on your Oracle server initiates all connections — TuneVault's cloud never opens inbound connections to your network.

• oracle-proxy.py runs as a systemd service (tunevault-proxy) on the Oracle server.
• The proxy opens a long-poll HTTPS connection to https://tunevault.app/api/agent/poll every 10 seconds.
• TuneVault sends health check jobs through this channel. The proxy executes them against the local Oracle listener and returns results.
• No inbound ports required. No DNS records. No third-party tunnel services.

2. Quick Diagnostic Checks

Run these from the Oracle server to pinpoint the failure mode fast.

# 1. Check proxy service status
sudo systemctl status tunevault-proxy

# 2. Check last 50 log lines
sudo journalctl -u tunevault-proxy -n 50 --no-pager

# 3. Confirm outbound connectivity to TuneVault
curl -sf https://tunevault.app/health
# Expected: {"status":"ok",...}

# 4. Check agent registration status (requires API key from installer)
curl -sf -H "X-API-Key: YOUR_AGENT_API_KEY" \
  "https://tunevault.app/api/agent/status?connection_id=YOUR_CONNECTION_ID"
# Expected: {"registered":true,"last_poll_at":"..."}

3. Verify Proxy Service on the Oracle Server

SSH to the Oracle server where the agent is installed. All commands run as root or the install user.

# Check service state
sudo systemctl status tunevault-proxy

# If inactive or failed — restart
sudo systemctl restart tunevault-proxy

# Re-check after restart
sudo systemctl status tunevault-proxy

# Follow logs in real time to see poll loop activity
sudo journalctl -u tunevault-proxy -f

A healthy agent logs a poll attempt every 10 seconds. If you see poll loop error repeating, the outbound connection is failing — go to Step 4.

Common log errors and their causes

• ConnectionError: Failed to establish a new connection — outbound HTTPS to tunevault.app is blocked. Go to Step 4.
• 401 Unauthorized on the poll endpoint — API key was revoked or is missing. Go to Step 6.
• cx_Oracle.DatabaseError: ORA-12541: TNS:no listener — Oracle listener is down. Go to Step 5.
• cx_Oracle.DatabaseError: ORA-01017: invalid username/password — reader credentials need updating. Regenerate via Settings → Connections.
• SSL: CERTIFICATE_VERIFY_FAILED — system time is wrong. Run timedatectl and sync NTP.

# Check system time (clock skew breaks TLS)
timedatectl status

# Sync if needed (RHEL/OL)
sudo chronyc makestep

# Sync if needed (older systems)
sudo ntpdate -u pool.ntp.org

4. Outbound Network Connectivity

The agent only needs outbound HTTPS (port 443) to tunevault.app. No inbound rules. No special DNS. No third-party services.

# Confirm outbound 443 works from the Oracle server
curl -sv https://tunevault.app/health 2>&1 | grep -E "Connected|HTTP|SSL"

# If curl fails — test raw TCP connectivity
nc -zv tunevault.app 443
# Expected: Connection to tunevault.app 443 port [tcp/https] succeeded!

# Check local iptables for outbound DROP/REJECT rules
sudo iptables -L OUTPUT -n | grep -E "DROP|REJECT"

# On RHEL/OL with firewalld
sudo firewall-cmd --list-all

sudo systemctl edit tunevault-proxy
# Add under [Service]:
Environment=HTTPS_PROXY=http://proxy.corp.example.com:3128

5. Oracle Listener Checks

The agent connects to Oracle locally. If the listener is down, the agent polls fine but health check jobs fail.

# Check listener status (run as oracle user)
lsnrctl status

# If listener is down
lsnrctl start

# Verify connection works with the reader account
sqlplus tunevault_reader/PASSWORD@//YOUR_DB_HOST:YOUR_DB_PORT/YOURDBSID

# Check listener log for ORA- errors
tail -50 $ORACLE_BASE/diag/tnslsnr/$(hostname -s)/listener/alert/log.xml

6. Re-register or Reinstall the Agent

If the API key is invalid, the connection was deleted, or the agent config is corrupted — re-run the installer with a fresh token.

# Get a fresh install token from TuneVault:
# Settings → Connections → [your connection] → Reinstall Agent → Copy token

# Re-run the installer — it detects an existing install and upgrades in place
curl -sSL https://tunevault.app/install.sh | bash -s -- --token YOUR_NEW_TOKEN

# The installer will:
# - Update oracle-proxy.py to the latest version
# - Write a new API key to /etc/tunevault/agent.conf
# - Restart tunevault-proxy
# - Run self-test and print PASS/FAIL for each check

Manual re-registration (without full reinstall)

# If you only need to re-register (service is running, key is stale):
curl -sf -X POST https://tunevault.app/api/agent/confirm \
  -H "Content-Type: application/json" \
  -d '{"token":"YOUR_INSTALL_TOKEN"}'
# Expected: {"ok":true,"connection_id":"..."}

# Restart the proxy to pick up the new registration
sudo systemctl restart tunevault-proxy

7. Fallback: Switch to Direct TCP Mode

If the agent cannot run on the Oracle server (strict egress policy, no Python, no root access), switch to Direct TCP. This bypasses the agent entirely — TuneVault connects directly to the Oracle listener over the network.

1. Go to Settings → Connections in TuneVault.
2. Edit the affected connection.
3. Change Connection Type to Direct TCP.
4. Enter the Oracle server's public IP (or VPN-accessible IP) and listener port (default 1521).
5. Save and run a new health check to verify connectivity.

8. Prevention

# Enable autostart
sudo systemctl enable tunevault-proxy

# Verify enabled
sudo systemctl is-enabled tunevault-proxy
# Expected: enabled

# Quick connectivity self-test (run anytime)
curl -sf https://tunevault.app/health | python3 -m json.tool