End-user Client Instructions

Follow these instructions if you're an end-user trying to set up your WireGuard client to work with Firezone.

Install and setup

Follow this guide to establish a VPN session through the WireGuard native client.

Step 1: Install the native WireGuard client

Firezone is compatible with the official WireGuard clients found here:

For operating systems not listed above see the Official WireGuard site: https://www.wireguard.com/install/.

Step 2: Download the device config file

The device config file can either be obtained from your Firezone administrator or self-generated via the Firezone portal.

To self generate a device config file, visit the domain provided by your Firezone administrator. This URL will be specific to your company (in this example it is https://firezone.example.com)

firezone okta sso login

Step 3 (optional): Enable on boot

Open the WireGuard client and import the .conf file. Activate the VPN session by toggling the Activate switch.

activate tunnel

Re-authenticating your session

If your network admin has required periodic authentication to maintain your VPN session, follow the steps below. You will need:

  • URL of the Firezone portal: Ask your Network Admin for the link.
  • Credentials: Your username and password should be provided by your Network Admin. If your company is using a Single Sign On provider (like Google or Okta), the Firezone portal will prompt you to authenticate via that provider.

Step 1: Deactivate VPN session

wireguard deactivate

Step 2: Re-authenticate

Visit the URL of your Firezone portal and sign in using credentials provided by your network admin. If you are already logged into the portal, click the Reauthenticate button, then sign in again.

re-authenticate

Step 3: Activate VPN session

activate session

Linux: Network Manager

The following steps can be used on Linux devices to import the WireGuard configuration profile using Network Manager CLI (nmcli).

Importing the configuration file using the Network Manager GUI may fail with the following error if the profile has IPv6 support enabled: ipv6.method: method "auto" is not supported for WireGuard

Step 1: Install the WireGuard tools

The WireGuard userspace tools need to be installed. For most Linux distributions this will be a package named wireguard or wireguard-tools.

For Debian/Ubuntu:

sudo apt install wireguard

For Fedora:

sudo dnf install wireguard-tools

For Arch Linux:

sudo pacman -S wireguard-tools

For distributions not listed above see the Official WireGuard site: https://www.wireguard.com/install/.

Step 2: Download configuration

The device config file can either be obtained from your Firezone administrator or self-generated via the Firezone portal.

To self generate a device config file, visit the domain provided by your Firezone administrator. This URL will be specific to your company (in this example it is https://firezone.example.com)

firezone okta sso login

Step 3: Import configuration

Using nmcli, import the downloaded configuration file:

sudo nmcli connection import type wireguard file /path/to/configuration.conf

The WireGuard connection/interface will match the name of the configuration file. If required, the connection can be renamed after import: nmcli connection modify [old name] connection.id [new name]

Step 4: Connect/disconnect

To connect to the VPN via the command line:

nmcli connection up [vpn name]

To disconnect:

nmcli connection down [vpn name]

If using a GUI, the relevant Network Manager applet can also be used to control the connection.

Auto connection

The VPN connection can be set to automatically connect by setting the autoconnect option to yes:

nmcli connection modify [vpn name] connection.autoconnect yes

To disable the automatic connection set it back to no:

nmcli connection modify [vpn name] connection.autoconnect no

Enable multi-factor authentication

To enable MFA navigate to /user_account/register_mfa in the Firezone portal. After generating the QR code, scan using your authenticator app and input the 6 digit code.

If you lose your authenticator app, contact your Admin to reset access to your account.