Report bugs and issues

Send problems you cannot solve to support@netzilo.com. A report with the facts below can be investigated straight away. One without them usually comes back with questions first.

Before you write, rule out the common causes in Troubleshooting client issues: another VPN, a wrong clock, an unfinished captive portal, a policy that does not cover the two peers.

What to include

The problem

  • What happens, with the exact error text, and where it appears (dashboard, client, browser, agent).
  • What you expected, and the setting that says so: the policy, route, filter or guardrail by name.
  • How often: every time, now and then, or once. The shortest steps that reproduce it.

Impact and severity

SeverityMeaning
S1nobody can work and there is no workaround: control plane down, every peer disconnected, nobody can sign in
S2a group or a site is blocked; the workaround is painful
S3one user or device; a workaround exists
S4a suspected defect with no outage, or a documentation error

Say how many users and devices are affected, since when, and what changed just before: an upgrade, a policy edit, a certificate, a network change.

The facts that make logs readable

  • The exact time of an occurrence, with the time zone.
  • The client version (netzilo version). For a self-hosted server, the image versions (docker compose images).
  • The affected peer's Netzilo IP, name (FQDN) and WireGuard public key, from netzilo status -d.
  • The user's e-mail address, or the name of the setup key the device enrolled with.
  • The deployment: Netzilo Cloud, or a self-hosted Netzilo Server with its install path (on-premises, AWS, Azure) and domain.

Collect from the device

On the affected device, raise the log level, reproduce the problem, then collect:

Linux and macOS

netzilo debug log level trace
# reproduce the problem now
sudo netzilo debug bundle
netzilo status -d > ~/netzilo-status.txt
netzilo version  >> ~/netzilo-status.txt
sudo cp /var/log/Netzilo.err.log ~/ 2>/dev/null     # macOS only, not in the bundle

Windows (PowerShell as Administrator)

netzilo debug log level trace
# reproduce the problem now
netzilo debug bundle
netzilo status -d | Out-File "$env:USERPROFILE\netzilo-status.txt"

Send the zip path that debug bundle prints, and netzilo-status.txt. Set the log level back with netzilo debug log level info.

  • Use the CLI, not the tray's Support > Collect Data: the tray bundle has no status snapshot.
  • Do not anonymize the bundle by default (-A). Anonymizing breaks the link between the status file and the logs. Use it only when your policy requires it, and say so in the report.
  • Avoid netzilo debug for: it logs the device out.

Remove credentials before you send

On Windows the bundle includes the client's configuration folder. Open the zip and delete these files before you send it:

  • config.json (contains the WireGuard private key)
  • token.dat and pat.dat
  • netzilo-ca-key.pem
  • every usservice*.json
  • mcp.db, if present
  • any workspace .json file next to them

Keep the log files: they are the evidence. If you cannot edit the zip, do not send it. Send the status file and the relevant log lines instead, and say that the bundle was withheld.

Logs written at debug or trace level can contain tokens or connection strings. Read the lines you send.

Collect from a self-hosted server

On Netzilo Cloud, Netzilo already has the server logs; do not send any. Give the account and the time window instead.

On a self-hosted server, the management log is the most important file. Collect it over a window from one hour before the first occurrence to one hour after the last:

cd /opt/netzilo/run 2>/dev/null || cd /opt/netzilo
sudo docker compose ps     > ~/netzilo-server.txt
sudo docker compose images >> ~/netzilo-server.txt
for s in management zitadel caddy signal coturn; do
  sudo docker compose logs --no-color --timestamps --since 24h $s > ~/netzilo-$s.log
done

Say in the report which window, in UTC, the logs cover. Never send management.json, zitadel.env, dashboard.env, .env, turnserver.conf, the CREDENTIALS file, certificates, keys or database dumps.

AI Gateway problems

For a problem with an agent calling the Netzilo AI Gateway, add:

  • netzilo-aigw --version and the last hour of journalctl -u netzilo-aigw.
  • The gateway's run flags, without --service-pat, --pat, --setup-key and the NZ_GATEWAY_* values.
  • The failing request's status code and response body, without the token. The body's type field says which part of the gateway refused it.

Report from the dashboard assistant

An administrator can also ask the dashboard's AI assistant to prepare the report. It collects what it can through the API and the device tools, writes the summary, and asks the administrator to approve before anything is sent. Where escalation is not set up for your deployment, it gives the administrator the summary to send to support@netzilo.com. Regular users hand the case to their administrator.