ZEFFAQ & Troubleshooting
Fast answers to common problems.
Login & access
start-lan.bat) serves the panel over plain HTTP. Anyone on that network can sniff your session — only use it on networks you trust, or reach the panel through an encrypted SSH tunnel instead.“Too many attempts, try again in a few minutes”
You (or someone) failed login 8+ times in 15 minutes. Wait, then log in carefully. If it persists with the right password, restart the panel service — in-memory counters reset: systemctl restart zefira.
Password lost
SSH into the server and set a new one via environment + restart, or edit ZEFIRA_ADMIN_PASSWORD in /opt/zefira/.env — note this only applies to a fresh database. On an existing DB, stop the service, delete instance/zefira.db (you lose data — restore from backup after), and restart to trigger first-run creation.
API returns 403 “forbidden” on POST
You forgot the X-Requested-With: XMLHttpRequest header — the CSRF guard. Browsers using the panel send it automatically.
Panel not responding
systemctl status zefira journalctl -u zefira -n 100 --no-pager curl -fsS http://127.0.0.1:8000/login && echo PANEL-UP ss -tlnp | grep 8000
If the port is taken, another copy is already running — stop it before starting a new one.
Subscriptions show 404 for everyone
- Tokens rotate on Reset token — resend the new link.
- Check the user is active, not expired and not out of volume.
- If you renamed
SUBSCRIPTION_PATH, old/sub/…links stop working.
SSL fails
- Port 80 must be free and the domain's DNS must point at the server.
- Let's Encrypt rate-limits repeated issuance — wait an hour and retry.
- Behind Nginx, make sure the HTTP vhost exists before issuing.
Clients can't connect but the sub link loads
- Open the VPN ports on the firewall (
ufw allow 443/tcp, plus inbound / Hy2 / WG ports). - Verify Settings → Server domain/ports match reality, and the REALITY public key is generated.
- WireGuard shows a warning comment until you paste the server's public key in Settings.
Do I have to pay for any of this?
No. Zefira is MIT-licensed, the docs site is plain static files in this repo, and GitHub Pages hosting is free. Let's Encrypt certificates are free too.