Troubleshooting - IPTunnel Docs

Activation error codes

Code	HTTP	Meaning and action
`install_code_not_found`	404	The code does not exist. Check for typos or generate a new one.
`install_code_used`	403	The code was already consumed by a previous activation. Generate a new code.
`install_code_expired`	403	The 5-minute window elapsed. Generate a new code and run the installer immediately.
`install_code_max_activations`	403	The code was cycled through activate/release too many times (limit: 5). Generate a new code.
`rate_limit_exceeded`	429	Too many requests from your IP in the current window. See Rate Limits. Wait before retrying.
`token_invalid`	403	The install token signature is wrong or the token has expired (10-minute window). Restart the install from step 1.
`token_mismatch`	403	The token does not match the activation_id. This should not happen in normal flow; restart the install.
`token_used`	409	Confirm was called twice for the same activation. The install is already confirmed; check the server is running correctly.
`activation_not_found`	404	The activation_id no longer exists (already released or never created). Restart the install.

Service-layer checks

Run these after install to verify all three services are active:

systemctl status slowdns-api slowdns-dnstt slowdns-udp53-redirect --no-pager

Check the API health endpoint directly:

curl -s http://127.0.0.1:8091/api/v2/healthz

Expected response: {"data":{"status":"ok"}, ...}

Check the license metadata written by the installer:

cat /opt/slowdns/config/license.json

If this file is missing or empty, the install did not complete the confirm step.

Log collection

Collect the last 120 lines from all three service logs before making changes:

journalctl -u slowdns-api -u slowdns-dnstt -u slowdns-udp53-redirect --no-pager -n 120

For API-layer errors only:

journalctl -u slowdns-api -n 50 --no-pager

For dnstt tunnel errors (no client connections, key mismatch):

journalctl -u slowdns-dnstt -n 50 --no-pager

DNS verification

If services are healthy but clients cannot connect, verify DNS before changing any config:

# A record for the public host must return the VPS IPv4
dig +short A ns1.example.com

# NS delegation must return the public host
dig +short NS slowdns.example.com

# Test that the NS delegation resolves through the dnstt server
dig @ns1.example.com slowdns.example.com NS

If the NS record is missing or points to the wrong host, no amount of service restarts will fix client connections.

Reinstalling on an existing server

The installer is idempotent. Re-running it on a server where SlowDNS is already installed will:

Require a fresh install code (the old one was consumed at first install).
Preserve existing SSH accounts and the SQLite database.
Overwrite the dnstt binary and service files with the latest versions.
Restart all services at the end.

Generate a new code from /slowdns, then rerun the install command.