Troubleshooting#

Service not starting#

PosternProxy fails to start#

journalctl -u posternproxy -n 50 --no-pager

Common causes:

Caddy fails to start#

journalctl -u caddy -n 50 --no-pager
caddy validate --config /etc/caddy/Caddyfile  # if using Caddyfile fallback

Common causes:

Traffic not routing#

Proxy host created but getting connection refused#

1. Check the proxy host is enabled in the UI

2. Verify Caddy is running: systemctl status caddy

3. Check Caddy’s config includes the route:

   curl -s http://localhost:2019/config/apps/http/servers/https/routes | jq .

4. Verify the upstream is actually listening:

   curl -I http://<upstream-host>:<port>/

Getting 502 Bad Gateway#

The upstream is not reachable. Check:

1. The upstream service is running on the configured host and port
2. There is no firewall between PosternProxy and the upstream
3. If using a hostname, it resolves correctly: dig <hostname>

If health checks are configured, check the upstream health widget on the Dashboard.

Getting wrong certificate / TLS error#

1. Check which certificate is assigned to the proxy host (SSL tab)
2. If using automatic Let’s Encrypt, verify the domain resolves to this server: dig +short <domain>
3. Check Caddy’s certificate status: curl http://localhost:2019/pki/ca/local
4. Force a cert renewal from the Certificates page

Management UI issues#

Can’t log in#

• Verify credentials: default email is admin@posternproxy.local; the password is randomly generated on first boot and printed to the service logs (journalctl -u posternproxy | grep password)
• Check fail2ban has not banned your IP: fail2ban-client status posternproxy
• Unban: fail2ban-client set posternproxy unbanip <your-ip>
• Check the service is running: systemctl status posternproxy

UI shows stale data#

Click the ↻ refresh button on the relevant page, or force a full page reload (Ctrl+Shift+R). PosternProxy does not push real-time updates to the frontend (except the provisioning terminal and dashboard health widget).

Force Caddy sync#

If you suspect Caddy’s config has drifted from the database (e.g. after a manual caddy reload):

1. Go to Settings → Force Caddy Sync
2. Click the button — PosternProxy rebuilds and pushes the full config

Or via API:

curl -X POST -H "Authorization: Bearer <token>" \
     http://localhost:81/api/settings/caddy-sync

Multi-server issues#

Agent shows as Offline#

1. SSH into the remote server and check the agent:

   systemctl status posternproxy-agent
   journalctl -u posternproxy-agent -n 30

2. Verify the agent can reach the controller:

   curl http://<controller-ip>:81/api/auth/me

3. Check the agent token in /etc/posternproxy-agent/config.env matches what is registered on the controller (re-provision to regenerate)

Config changes not reaching remote server#

• Check agent is online on the Servers page
• If recently reconnected, a full sync is sent automatically — wait a few seconds
• Check the agent journal for errors: journalctl -u posternproxy-agent -n 50

Log locations#

Getting help#

If the above steps do not resolve your issue, collect the following for a bug report:

# System info
uname -a
cat /etc/os-release

# Service status
systemctl status posternproxy caddy
journalctl -u posternproxy -n 100 --no-pager
journalctl -u caddy -n 100 --no-pager

# Caddy config (sanitise any secrets)
curl -s http://localhost:2019/config/ | jq .