Troubleshooting Guide

If you deployed the Gateway using one of our Terraform examples, the Gateways are configured using the systemd deployment method.

Obtain a shell on the affected Gateway and check the status of the service:

sudo systemctl status firezone-gateway

Check the logs with:

sudo journalctl -u firezone-gateway.service

Check that the container is running:

docker ps --filter "name=firezone-gateway"

Check the container logs:

docker logs firezone-gateway

Check the status of the service:

sudo systemctl status firezone-gateway

Check the logs:

sudo journalctl -u firezone-gateway.service

resolvectl dns

With Firezone's Split DNS active, the tun-firezone link lists Firezone's resolver:

Global:
Link 2 (enp0s6): 10.0.2.3 fec0::3
Link 3 (tun-firezone): 100.100.111.1 fd00:2021:1111:8000:100:100:111:0

Without it, only the normal system links appear:

Global:
Link 2 (enp0s6): 10.0.2.3 fec0::3

With Split DNS active, /etc/resolv.conf carries Firezone's header and resolver:

# BEGIN Firezone DNS configuration
# If you modify this file, delete the above magic header line so that Firezone will
# obey your new default DNS config.
nameserver 100.100.111.1
search .
options edns0
options trust-ad

Without it, you'll see your normal resolver:

nameserver 192.168.1.1

In PowerShell:

Get-DnsClientNrptPolicy

With Firezone's Split DNS active, the policy lists Firezone's name servers:

Namespace    : .
NameServers  : {100.100.111.1, fd00:2021:1111:8000:100:100:111:0}

If Firezone's Split DNS is not active, the output will be empty.

Firezone is signed in, but I can't access Resources

If the Firezone client shows that you are signed in, but you can't access Resources, it's possible that the WinTUN driver is corrupted or in a failed state.

To fix, perform these steps:

1. Uninstall Firezone and any other WireGuard-based VPN software from your computer.
2. Reset your network settings by going to Settings → Network and Internet → Additional network settings → Network Reset → Reset now.
3. Reinstall Firezone and any other software you previously uninstalled.

Check if the Firezone Client Tunnel service is running

In the Start Menu, search for "Windows Powershell". Open it and run this command:

Get-Service -Name FirezoneClientTunnelService

Good output

Status   Name               DisplayName
------   ----               -----------
Running  FirezoneClientI... Firezone Tunnel Service

Bad output

Status   Name               DisplayName
------   ----               -----------
Stopped  FirezoneClientI... Firezone Tunnel Service

If the service isn't running or behaving not as expected, you can restart it with the following command:

Restart-Service -Name FirezoneClientTunnelService

Relaunch Firezone from the Start Menu afterwards.

Check if Firezone is controlling DNS

In the Start Menu, search for "Windows Powershell". Open it and run this command:

Get-DnsClientNrptPolicy

Firezone Split DNS example:

Namespace                        : .
QueryPolicy                      :
SecureNameQueryFallback          :
DirectAccessIPsecCARestriction   :
DirectAccessProxyName            :
DirectAccessDnsServers           :
DirectAccessEnabled              :
DirectAccessProxyType            : NoProxy
DirectAccessQueryIPsecEncryption :
DirectAccessQueryIPsecRequired   : False
NameServers                      : {100.100.111.1, fd00:2021:1111:8000:100:100:111:0}
DnsSecIPsecCARestriction         :
DnsSecQueryIPsecEncryption       :
DnsSecQueryIPsecRequired         : False
DnsSecValidationRequired         : False
NameEncoding                     : Utf8WithoutMapping

If Firezone's Split DNS is not active, the output will be empty.

Revert Firezone DNS control

If Firezone crashes and does not revert control of the system's DNS, you can revert it manually with this command:

Get-DnsClientNrptRule | where Comment -eq firezone-fd0020211111 | foreach { Remove-DnsClientNrptRule -Name $_.Name -Force }

1. Right-click on the Start Menu
2. Click "Terminal (Admin)" to open a Powershell terminal with admin privileges
3. When UAC asks "Do you want to allow this app to make changes to your device?" click Yes
4. Enter the above command, then re-run the Get-DnsClientNrptPolicy check above to confirm DNS control was reverted.

Viewing logs

The Firezone Client is split into 2 main processes: A Tunnel service which runs the tunnel, and a GUI which allows the user to control Firezone.

• Tunnel service logs are stored at %PROGRAMDATA%\dev.firezone.client\data\logs\, where %PROGRAMDATA% is almost always C:\ProgramData
• GUI logs are stored at %LOCALAPPDATA%\dev.firezone.client\data\logs, where %LOCALAPPDATA% is, e.g. C:\Users\username\AppData\Local

Signing in doesn't do anything

If you go through the sign in process successfully and nothing happens, it could be that the System Extension is not enabled or installed correctly. To fix this, perform the following steps:

Step 1: Remove the VPN Profile

1. Quit the Firezone Client.
2. Open System Settings.
3. Go to VPN.
4. Click the in the Firezone entry to open its settings.
5. Click the Remove Configuration... button and confirm the removal.

Step 2: Remove the Network Extension

1. Open System Settings.
2. Go to General → Login Items & Extensions.
3. Scroll to the bottom and look for the Network Extensions section.
4. Click the in the Network Extensions section to open its settings.
5. Click the ellipsis (...) button in the Firezone.app entry to open the contextual menu.
6. Click Delete Extension.

Step 3: Open the Firezone Client

1. Open the Firezone Client.
2. Click Enable System Extension and follow the instructions to enable the system extension.
3. Click Grant VPN Permission and follow the instructions to allow the VPN profile.

Step 4: Sign in

The system extension and related VPN profile should now be installed correctly. If you still have issues, please contact support.

Check if Firezone is controlling DNS

1. Open the Terminal app.
2. Run dig firezone.dev and look for a line starting with ;; SERVER:.

If the Firezone is controlling the system's DNS, then the server will be 100.100.111.1 or some other IP in the 100.100.111.0/24 range or fd00:2021:1111:8000:100:100:111:0/120 range.

Firezone Split DNS:

;; SERVER: 100.100.111.1#53(100.100.111.1)
;; WHEN: Thu May 30 00:00:00 UTC 2024
;; MSG SIZE  rcvd: 57

Normal system DNS:

;; SERVER: fe80::96a6:7eff:fe78:edb7%15#53(fe80::96a6:7eff:fe78:edb7%15)
;; WHEN: Thu May 30 00:00:00 UTC 2024
;; MSG SIZE  rcvd: 57

Firezone keeps reappearing if stopped via the Activity Monitor

Firezone installs a Launch Agent called KeepFirezoneRunning. This Launch Agent restarts the application whenever it terminates non-gracefully. To quit Firezone without it being restarted, use the "Quit" entry from the menu bar.

Check if systemd-resolved is enabled

systemctl status systemd-resolved
stat /etc/resolv.conf

systemctl should show that systemd-resolved is enabled and active (running).

stat should show that resolv.conf is a symlink to stub-resolv.conf: File: /etc/resolv.conf -> ../run/systemd/resolve/stub-resolv.conf

If systemd-resolved is not running, or the symlink is not set up, Firezone may not be able to start, or may not be able to access DNS resources.

Check if Firezone is controlling DNS

resolvectl dns

Firezone Split DNS:

Global:
Link 2 (enp0s6): 10.0.2.3 fec0::3
Link 3 (tun-firezone): 100.100.111.1 fd00:2021:1111:8000:100:100:111:0

Normal system DNS:

Global:
Link 2 (enp0s6): 10.0.2.3 fec0::3

cat /etc/resolv.conf

Normal resolv.conf if systemd-resolved is installed, whether or not Firezone is running:

# This file is managed by man:systemd-resolved(8). Do not edit.
...

Firezone resolv.conf if you set FIREZONE_DNS_CONTROL=etc-resolv-conf:

# BEGIN Firezone DNS configuration
...

Revert Firezone DNS control

By default, the Firezone GUI Client for Linux controls DNS using systemd-resolved, which will automatically revert DNS to the system defaults when Firezone is disconnected.

If the network interface stays up and DNS does not revert, you can try restarting the tunnel service. Quit the Firezone GUI, then run:

sudo systemctl restart firezone-client-tunnel

Viewing logs

The Firezone Client is split into 2 main processes: A Tunnel service which runs the tunnel, and a GUI which allows the user to control Firezone.

• Tunnel service logs are stored at /var/log/dev.firezone.client/
• GUI logs are stored at $HOME/.cache/dev.firezone.client/data/logs/, where $HOME is, e.g. /home/username/

There are no Android-specific troubleshooting steps yet. If you're having trouble, contact support.

There are no iOS-specific troubleshooting steps yet. If you're having trouble, contact support.