Skip to main content


For any problems that arise, a good first bet is to check the Firezone logs. Firezone logs are stored in /var/log/firezone and can be viewed with sudo firezone-ctl tail.

Application Crash Loop Preventing Config Changes

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

For example, to clear OIDC configs:

psql -d firezone -h -U postgres -c "UPDATE configurations SET openid_connect_providers = '{}'"

Similarly, to clear SAML configs:

psql -d firezone -h -U postgres -c "UPDATE configurations SET saml_providers = '{}'"

Debugging Portal Websocket Connectivity Issues

The portal UI requires a secure websocket connection to function. To facilitate this, the Firezone phoenix service checks the Host header for inbound websocket connections and only permits the connection if it matches the host portion of your default['firezone']['external_url'] variable.

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 default['firezone']['external_url'] variable from above, the issue is likely to be in your reverse proxy configuration.

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

  • Your browser's developer tool logs, specifically the Network tab.
  • sudo firezone-ctl tail nginx
  • sudo firezoen-ctl tail phoenix

If the websocket connection is successful, you should see output in the phoenix service logs similar the following:

2022-09-23_15:05:47.29158 15:05:47.291 [info] CONNECTED TO Phoenix.LiveView.Socket in 24µs
2022-09-23_15:05:47.29160 Transport: :websocket
2022-09-23_15:05:47.29160 Serializer: Phoenix.Socket.V2.JSONSerializer
2022-09-23_15:05:47.29161 Parameters: %{"_csrf_token" => "XFEFCHQ2fRQABQwtKQdCJDlFAzEcCCJvn7LqDsMXE4eGZtsBzuwVRCJ6", "_mounts" => "0", "_track_static" => %{"0" => "", "1" => ""}, "vsn" => "2.0.0"}
2022-09-23_15:05:47.33655 15:05:47.336 [info] CONNECTED TO FzHttpWeb.UserSocket in 430µs
2022-09-23_15:05:47.33657 Transport: :websocket
2022-09-23_15:05:47.33658 Serializer: Phoenix.Socket.V2.JSONSerializer
2022-09-23_15:05:47.33658 Parameters: %{"token" => "SFMyNTY.g2gDYQFuBgB6HeJqgwFiAAFRgA.qKoC2bi9DubPkE0tfaRSPERWUFyQQPQV5n4nFKVppxc", "vsn" => "2.0.0"}
2022-09-23_15:05:47.35063 15:05:47.350 [info] JOINED notification:session in 636µs
2022-09-23_15:05:47.35065 Parameters: %{"token" => "SFMyNTY.g2gDYQFuBgB6HeJqgwFiAAFRgA.zSG7pefm-Vgf_zvduxa5E9VK4s8PKqzc0xBDGNx5FQE", "user_agent" => "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:106.0) Gecko/20100101 Firefox/106.0"}

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)

Need additional help?

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

We highly recommend considering priority support if you're deploying Firezone in a production capacity.