Linux Client

Firezone supports Linux with a native, headless client for ARMv7l, ARM64, and x86-64 architectures.

The Linux Client is a lightweight, standalone binary that runs in the background using a service account token.

Prerequisites

• Any Linux-based OS with kernel 3.10 or higher
• ARM64, ARMv7l, or x86-64 CPU
• Administrator access to your Firezone account in order to create a Service Account and generate a token

Installation

The Linux Client is currently in beta and can be downloaded from our main repository's releases page. Alternatively, download the latest Client binary using one of the links below:

• Download the Linux Client for x86-64
• Download the Linux Client for ARMv7l
• Download the Linux Client for ARM64

Usage

The Linux Client requires a Service Account token to authenticate to Firezone. If you don't already have a token generated, follow the instructions in the Service Account documentation.

Once you have a token, you can start the Linux Client using the following command:

sudo ./linux-client-x64 <TOKEN>

Set some environment variables to configure it:

FIREZONE_NAME="Development Webserver"
FIREZONE_ID="some unique identifier"
DNS_CONTROL="systemd-resolved" # or "etc-resolv-conf"
LOG_DIR="./"
sudo -E ./linux-client-x64 <TOKEN>

See below for a full list of environment variables.

A sample output of the help command is shown below:

> sudo ./linux-client-x64 -h

Usage: linux-client-x64 [OPTIONS] --firezone-id <FIREZONE_ID> <TOKEN> [MAX_PARTITION_TIME]

Arguments:
  <TOKEN>               Token generated by the portal to authorize websocket connection [env: FIREZONE_TOKEN=]
  [MAX_PARTITION_TIME]  Maximum length of time to retry connecting to the portal if we're having internet issues or it's down [env: MAX_PARTITION_TIME=] [default: 30d]

Options:
  -n, --firezone-name <FIREZONE_NAME>  Friendly name to display in the UI [env: FIREZONE_NAME=]
  -i, --firezone-id <FIREZONE_ID>      Identifier generated by the portal to identify and display the device [env: FIREZONE_ID=]
  -l, --log-dir <LOG_DIR>              File logging directory. Should be a path that's writeable by the current user [env: LOG_DIR=]
  -h, --help                           Print help
  -V, --version                        Print version

Split DNS

The Linux Client supports Split DNS, which you can enable by setting the FIREZONE_DNS_CONTROL environment variable to systemd-resolved or etc-resolv-conf. If you don't set this variable, Split DNS will be disabled.

When Split DNS is enabled, the Linux Client will override the system's DNS resolver with its internal proxy. To do this, the Linux client needs to know how DNS resolution is currently being handled on your system.

systemd-resolved

On most modern Linux distributions, DNS resolution is handled by systemd-resolved. If this is the case for you, set FIREZONE_DNS_CONTROL to systemd-resolved. If you're not sure, you can check by running the following command:

systemctl status systemd-resolved

NetworkManager

In most cases, if you're using NetworkManager your system is likely already using systemd-resolved, and you should set FIREZONE_DNS_CONTROL to systemd-resolved. You'll need to ensure that /etc/resolv.conf is a symlink to /run/systemd/resolve/stub-resolv.conf:

stat /etc/resolv.conf
sudo ln -sf /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf

When NetworkManager detects that symlink exists, it will automatically use systemd-resolved for DNS resolution.

/etc/resolv.conf

If you're not using systemd-resolved, Firezone supports using the /etc/resolv.conf file to configure Split DNS as a fallback. To do this, set FIREZONE_DNS_CONTROL to etc-resolv-conf, and the Linux Client will override the /etc/resolv.conf file with the Firezone internal proxy.

Read more about how DNS works in Firezone.

Environment variable reference

Here's an exhaustive list of environment variables you can use for the Linux client.