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

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

Installation

Download the .deb package from our releases page, or from the direct link below:

• Download the Linux GUI .deb for x86-64

Run these commands:

# Install the package
# The leading `./` is needed so `apt-get` can tell this is a local file
sudo apt-get install ./firezone-client-gui-linux_<VERSION>_<ARCH>.deb

# Add yourself to the `firezone-client` group so you can use the tunnel service
sudo usermod -aG firezone-client "$USER"

# Reboot to finish adding yourself to the group
reboot

To auto-start the Client when you log in, run firezone-client-gui debug set-autostart true

Usage

Signing in

1. Start the GUI by running firezone-client-gui 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

1. Download the latest .deb installer package from "Installation" above.
2. Quit firezone-client-gui if it's running.
3. Install the new package: sudo apt-get install ./firezone-client-gui-linux_<VERSION>_<ARCH>.deb
4. Restart firezone-client-gui.

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.

Uninstalling

1. Remove the auto-start link: firezone-client-gui debug set-autostart false
2. Quit firezone-client-gui 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

Revert Firezone DNS control

The Firezone GUI Client for Linux uses systemd-resolved to control DNS, which will automatically revert DNS to the system defaults when you quit the Firezone GUI, which destroys the tun-firezone virtual network interface.

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-ipc

Known issues

• DNS Resources: Web browsers that enable "Secure DNS" or DNS-over-HTTPS by default may interfere with DNS resolution because they force all DNS traffic through the browser's configured resolvers. See Administer / Troubleshooting / Some browsers break DNS routing to disable DNS-over-HTTPS if you're experiencing issues connecting to DNS Resources within your browser.
• After clearing diagnostic logs, no more logs are written until the GUI and tunnel service each restart. #4764
• The GUI Client does not run on Ubuntu 24.04 yet #4883