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

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

sudo apt update
sudo apt install firezone-client-gui

# flake.nix
{
inputs.firezone.url = "github:firezone/firezone/gui-client-1.5.15";
}

# configuration.nix
{ inputs, ... }:
{
  imports = [ inputs.firezone.nixosModules.gui-client ];

  # Substitute pre-built, Firezone-signed binaries instead of compiling the
  # Client from source. Optional, but strongly recommended.
  nix.settings = {
    extra-substituters = [ "https://artifacts.firezone.dev/nix" ];
    extra-trusted-public-keys = [
      "artifacts.firezone.dev/nix-1:T4LHdL1HeA6LE9qgu0Po0j3RIlelKZz8pzqnzEAIRfI="
    ];
  };

  services.firezone.gui-client = {
    enable = true;

    # Required. Desktop users allowed to control the tunnel daemon. They are
    # added to the firezone-client group; this takes effect on next login.
    allowedUsers = [ "alice" ];
  };
}

sudo nixos-rebuild switch

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

See Upgrade Firezone to keep the Client up to date.

Diagnostic logs

See Diagnostic logs for where logs are stored and how to export them.

Uninstalling

To remove the Firezone Client, see Uninstall Firezone.

Troubleshooting

For Client troubleshooting, see the troubleshooting guide and select the Linux tab.

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.

Need help? See all support options.