import SupportOptions from "@/components/SupportOptions"; import Alert from "@/components/DocsAlert";

Linux GUI Client

The Linux GUI Client is designed for Linux desktop environments where a user is present to authenticate with your identity provider interactively.

Prerequisites

• x86-64 or ARM64 CPU architecture
• Ubuntu 22.04 or higher, or CentOS 10 or higher. Other distributions may work, but are not officially supported.
• systemd-resolved. Ubuntu already uses this by default.

Installation (Ubuntu)

Add the Firezone APT repository:

sudo mkdir --parents /etc/apt/keyrings
wget -qO- https://artifacts.firezone.dev/apt/key.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/firezone.gpg
echo "deb [signed-by=/etc/apt/keyrings/firezone.gpg] https://artifacts.firezone.dev/apt/ stable main" | sudo tee /etc/apt/sources.list.d/firezone.list

Install the Client:

sudo apt update
sudo apt install firezone-client-gui

To finish the setup, reboot your machine. This is necessary to fully reflect group membership changes. The GUI client cannot function until the current user is in the firezone-client group.

Installation (CentOS 10)

Step 1: Install repositories

These are required for both GNOME extensions and the WebKit and other dependencies of the Firezone Client.

1. sudo dnf config-manager --set-enabled crb
2. sudo dnf install epel-release

Step 2: Install system tray

GNOME Shell in CentOS does not have a system tray by default. Use these steps to install it. For other desktops like xfce4 or KDE, the system tray may already work properly.

1. sudo dnf install gnome-shell-extension-appindicator
2. Log out and back in to restart GNOME
3. gnome-extensions enable [email protected]
4. Optionally: To manage GNOME extensions via a GUI, install gnome-extensions-app

Step 3: Install Firezone

1. Download the RPM: Download the latest Linux GUI .rpm from GitHub Releases
2. sudo dnf install systemd-resolved (Installing it explicitly prevents it from being auto-removed if Firezone is removed)
3. sudo dnf install ./firezone-client-gui-*.rpm
4. sudo usermod -aG firezone-client $USER
5. Reboot to finish adding yourself to the group. Logging out and back in is not enough. This also starts the new services for us.
6. sudo cp /etc/resolv.conf /etc/resolv.conf.before-firezone Back up your resolv.conf file. If anything goes wrong with your DNS, you can copy this back into place.
7. sudo ln --force --symbolic /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf This puts systemd-resolved, and therefore Firezone, in control of the system's DNS. systemd-resolved does not do this automatically, since it's under /etc.
8. Run Firezone from the app menu.

Usage

Signing in

1. Start the GUI by running Firezone from your desktop environment's application menu or from an interactive shell.
2. At the Welcome screen, click Sign in. This will open the Firezone sign-in page in your default web browser.
3. Sign in using your account slug and identity provider
4. On the first run, check Always allow to allow your web browser to sign in to Firezone, then click Open or Open link
5. Unlock your desktop's keyring, or create one if needed. Most desktops, including GNOME, encrypt the keyring with your login password, so your Firezone token is encrypted at rest.
6. When you see the Firezone connected notification, Firezone is running.

The Welcome screen only appears during your first sign-in. After that, you can click on the Firezone icon in the system tray to open the tray menu and sign in.

Accessing a Resource

When Firezone is signed in, web browsers and other programs will automatically use it to securely connect to Resources.

To copy-paste the address of a Resource:

1. Click on the Firezone tray icon to open the menu.
2. Open a Resource's submenu and click on its address to copy it.
3. Paste the address into your browser's URL bar and press Enter.

Quitting

1. Click on the Firezone tray icon to open the menu.
2. Click Disconnect and Quit or Quit.

When Firezone is not running, you can't access private Resources, and the computer will use its normal DNS and Internet behavior.

If you were signed in, then you will still be signed in the next time you start Firezone.

Signing out

1. Click on the Firezone tray icon to open the menu.
2. Click Sign out.

When you're signed out, you can't access private Resources, and the computer will use its normal DNS and Internet behavior.

Upgrading

If you installed the Client via apt you can upgrade it like any other package:

sudo apt update
sudo apt upgrade firezone-client-gui

If you installed the package manually, follow these upgrade steps:

1. Download the latest .deb or .rpm installer package from GitHub Releases.
2. Quit Firezone Client if it's running.
3. Install the new package: sudo apt-get install ./firezone-client-gui-linux_<VERSION>_<ARCH>.(deb|rpm)
4. Restart Firezone Client.

Diagnostic logs

Firezone writes log files to disk. These logs stay on your computer and are not transmitted anywhere. If you find a bug, you can send us a .zip archive of your logs to help us fix the bug.

To export or clear your logs:

1. Click on the Firezone tray icon.
2. Click Settings.
3. Click Diagnostic Logs.
4. Click Export Logs or Clear Log Directory.

The Tunnel service (firezone-client-tunnel.service) also logs to stdout which is captured by systemd and sent to journald. To view the logs of the Tunnel service, use:

journalctl --pager-end --follow --unit firezone-client-tunnel.service

The GUI client logs to journald directly as well with the syslog identifier firezone-client-gui. To view the logs via journalctl, use:

journalctl --pager-end --follow --identifier firezone-client-gui

Uninstalling

1. Remove the auto-start link: firezone-client-gui debug set-autostart false
2. Quit Firezone Client if it's running.
3. Remove the package: sudo apt-get remove firezone-client-gui

Troubleshooting

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/

Known issues

• The update checker notification does not work for RPM installations #7646
• If you update Firezone while the GUI is running, you must manually restart the GUI #5790
• If a search domain is applied, the system search domains set manually or by DHCP are ignored. #8430.