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.


  • 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


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:


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 FIREZONE_TOKEN=<TOKEN> ./headless-client-x64

Set some environment variables to configure it:

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

See below for a full list of environment variables.

A sample output of the help command is shown below:

> sudo ./headless-client-x64 -h

Usage: headless-client [OPTIONS] [COMMAND]

  standalone  Act as a CLI-only Client
  help        Print this message or the help of the given subcommand(s)

      --token-path <TOKEN_PATH>
          A filesystem path where the token can be found [env: FIREZONE_TOKEN_PATH=] [default: /etc/dev.firezone.client/token]
  -i, --firezone-id <FIREZONE_ID>
          Identifier used 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=]
  -m, --max-partition-time <MAX_PARTITION_TIME>
          Maximum length of time to retry connecting to the portal if we're having internet issues or it's down. Accepts human times. e.g. "5m" or "1h" or "30d" [env: MAX_PARTITION_TIME=]
  -h, --help
          Print help
  -V, --version
          Print version

Split DNS

By default, Split DNS is disabled for the Linux Client. This means that access to DNS-based Resources won't be routed through Firezone.

To enable Split DNS for the Linux Client, set the FIREZONE_DNS_CONTROL environment variable to systemd-resolved or etc-resolv-conf.

Read more below to figure out which DNS control method is appropriate for your system.


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


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:

# Check if /etc/resolv.conf is already a symlink to /run/systemd/resolve/stub-resolv.conf
stat /etc/resolv.conf

# If it's not, create the symlink
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 and no other configuration is necessary.


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.

When the Linux Client process exits, it will revert the /etc/resolv.conf file back to its original state. If for some reason this isn't the case, you can easily restore it by running the following command:

sudo mv /etc/resolv.conf.before-firezone /etc/resolv.conf

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.

Variable NameDefault ValueDescription
FIREZONE_TOKENService account token generated by the portal to authenticate this Client.
FIREZONE_NAME<system hostname>Friendly name for this client to display in the UI.
FIREZONE_IDIdentifier used by the portal to identify this client for metadata and display purposes.
FIREZONE_DNS_CONTROLThe DNS control method to use. Set to systemd-resolved to use systemd-resolved for Split DNS, or etc-resolv-conf to use the /etc/resolv.conf file. If left blank, Split DNS will be disabled.
LOG_DIRFile logging directory. Should be a path that's writeable by the current user. If unset, logs will be written to STDOUT only.
RUST_LOGerrorLog level for the client. Set to debug for verbose logging. Read more about configuring Rust log levels here.


  1. Stop the running Client.
  2. Download a newer binary from one of the links above.
  3. Replace the existing binary with the new one.
  4. Start the Client with the same environment variables as before.

Need additional help?

Try asking on one of our community-powered support channels:

Or try searching the docs:
Last updated: May 16, 2024