Troubleshooting Guide

This guide documents common configuration and connectivity issues. For any problems that arise, a good first bet is to check the Firezone logs.

Each container stores logs as a JSON file on the host machine. These can be shown with the docker logs {CONTAINER} command. Log files are found at var/lib/docker/containers/{CONTAINER_ID}/{CONTAINER_ID}-json.log by default.

See debug logs for additional details.

Application crash loop preventing config changes

In cases where the application is crash looping because of corrupt, inaccessible, or invalid OIDC or SAML configuration in the DB, you can try clearing the affected fields.

For example, to clear OIDC configs:

psql -d firezone -h 127.0.0.1 -U postgres -c "UPDATE configurations SET openid_connect_providers = '[]'"

Similarly, to clear SAML configs:

psql -d firezone -h 127.0.0.1 -U postgres -c "UPDATE configurations SET saml_identity_providers = '[]'"

Debugging WebSocket connectivity issues

The Web UI requires a secure websocket connection to function. If a secure websocket connection can't be established, you'll see a red dot indicator in the upper-right portion of the Firezone web UI and a corresponding message when you hover over it:

Secure websocket not connected! ...

If you're accessing Firezone using the same URL defined in your EXTERNAL_URL variable from above, the issue is likely to be in your reverse proxy configuration. Ensure your reverse proxy has WebSocket support enabled for Firezone. If you're using the default Caddy reverse proxy, WebSocket is enabled and configured automatically.

In most cases, you'll find clues in one or more of the following locations:

  • firezone service logs: docker compose logs firezone
  • caddy service logs: docker compose logs caddy

Debugging WireGuard connectivity issues

Most connectivity issues with Firezone are caused by other iptables or nftables rules which interfere with Firezone's operation. If you have rules active, you'll need to ensure these don't conflict with the Firezone rules.

Internet connectivity drops when tunnel is active

If your Internet connectivity drops whenever you activate your WireGuard tunnel, you should make sure that the FORWARD chain allows packets from your WireGuard clients to the destinations you want to allow through Firezone.

If you're using ufw, this can be done by making sure the default routing policy is allow:

ubuntu@fz:~$ sudo ufw default allow routed
Default routed policy changed to 'allow'
(be sure to update your rules accordingly)

A ufw status for a typical Firezone server might look like this:

ubuntu@fz:~$ sudo ufw status verbose
Status: active
Logging: on (low)
Default: deny (incoming), allow (outgoing), allow (routed)
New profiles: skip

To                         Action      From
--                         ------      ----
22/tcp                     ALLOW IN    Anywhere
80/tcp                     ALLOW IN    Anywhere
443/tcp                    ALLOW IN    Anywhere
51820/udp                  ALLOW IN    Anywhere
22/tcp (v6)                ALLOW IN    Anywhere (v6)
80/tcp (v6)                ALLOW IN    Anywhere (v6)
443/tcp (v6)               ALLOW IN    Anywhere (v6)
51820/udp (v6)             ALLOW IN    Anywhere (v6)

Admin login isn't working

If the password for the account with email DEFAULT_ADMIN_EMAIL isn't working, you can reset it using the process below.

First change directory to your Firezone installation directory ($HOME/.firezone by default), then run the bin/create-or-reset-admin script to reset the admin user's password. The password for the user specified by DEFAULT_ADMIN_EMAIL in $HOME/.firezone/.env will be reset to the DEFAULT_ADMIN_PASSWORD variable.

cd $HOME/.firezone
docker compose exec firezone bin/create-or-reset-admin

Note: If local authentication is disabled, resetting the admin user's password will not re-enable it.

Re-enable local authentication via CLI

If you've configured an OIDC or SAML provider, you can consider disabling local authentication for additional security.

If, however, issues arise with your identity provider integration, it's possible you could be locked out of the admin portal. To re-enable local authentication so you can log in and resolve the issue, you can temporarily re-enable local authentication via the REST API.

If that's not an option, you can re-enable local authentication by running the following commands on the host of your Firezone instance:

cd $HOME/.firezone
docker compose exec postgres psql -U postgres -h 127.0.0.1 -d firezone -c "UPDATE configurations SET local_auth_enabled = 't'"

Need additional help?

Try asking on one of our community-powered support channels:

Or try searching the docs: