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

The Linux GUI Client ships as a .deb package which uses dependencies from the Ubuntu apt repos. The package can be downloaded from our main repository's releases page or using the direct link below:

• Download the Linux Client for x86-64

After downloading:

1. Install the package: sudo apt-get install ./firezone-client-gui-linux_<VERSION>_<ARCH>.deb
2. Refresh the system users and groups: sudo systemd-sysusers
3. Grant your user account permissions to control the Client: sudo adduser "$USER" firezone-client
4. Set the tunnel service to start automatically: sudo systemctl enable --now firezone-client-ipc
5. Reboot: reboot

Ubuntu requires a reboot in order to finish adding your user account to the Firezone group.

Usage

Signing in

1. Start the GUI from your desktop environment's application menu or by running firezone-client-gui 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"
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, the tunnel is ready.

The Welcome screen only appears for your first sign-in. After that, you can use the tray menu to sign in.

Accessing a Resource

1. Click on the Firezone tray icon to open the menu.
2. Open a Resource and click on its address to copy it.
3. Paste the address into your web browser's URL bar and hit Enter. The web browser will use Firezone to securely connect to the Resource.

Signing out

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

The tunnel is now stopped until you sign in again.

Upgrading

1. Quit firezone-client-gui if it's running.
2. Install the new package: sudo apt-get install ./firezone-client-gui-linux_<VERSION>_<ARCH>.deb
3. Restart the tunnel service: sudo systemctl restart firezone-client-ipc
4. Restart firezone-client-gui.

Diagnostic logs

Firezone writes logs to the local disk. These logs stay on the disk and are not shared with Firezone unless you manually send them to us.

To export your logs as a zip archive, or clear your log directory:

1. Click on the Firezone tray icon to open the menu.
2. Click "Settings".
3. Click "Diagnostic Logs".

Un-installing

1. Quit firezone-client-gui if it's running.
2. Stop the tunnel service: sudo systemctl stop firezone-client-ipc.service
3. Remove the package: sudo apt-get remove firezone-client-gui
4. Refresh systemd: sudo systemctl daemon-reload

Known issues

• After clearing diagnostic logs, no more logs are written until the GUI and tunnel service each restart. #4764