Linux Headless Client

Headless Clients are designed to authenticate with long-lived service account tokens to enable system-to-system connectivity where a user isn't present to authenticate with your identity provider interactively.

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
• Root access or sudo for Split DNS

Installation

Download the Linux headless Client from our releases page, or use one of the direct links below:

• Download the Linux Client for x86_64
• Download the Linux Client for ARMv7l
• Download the Linux Client for ARM64

Mark the binary as executable:

chmod +x firezone-client-headless-linux_1.0.0_x86_64

Usage

Signing in

Headless Clients require a service account token to authenticate to Firezone. You can generate a token using the instructions in the service account documentation.

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

sudo FIREZONE_TOKEN=<TOKEN> ./firezone-client-headless-linux_1.0.0_x86_64

Set some environment variables to configure it:

export FIREZONE_NAME="Development API test client"
export FIREZONE_ID="some unique identifier like a UUID"
export FIREZONE_TOKEN=<TOKEN>
export DNS_CONTROL="systemd-resolved" # or "etc-resolv-conf"
export LOG_DIR="./"
sudo -E ./firezone-client-headless-linux_1.0.0_x86_64

See below for a full list of environment variables.

Accessing a Resource

When Firezone is signed in, HTTP clients, SQL clients, and other programs will automatically use it to securely connect to Resources.

Split DNS

By default, Split DNS is disabled for the Linux headless 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.

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:

# 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.

/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.

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

Help output

> sudo ./firezone-client-headless-linux_1.0.0_x86_64 -h

Usage: firezone-headless-client [OPTIONS] [COMMAND]

Commands:
  standalone
  help        Print this message or the help of the given subcommand(s)

Options:
      --check
          Check the configuration and return 0 before connecting to the API
      --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 (see more with '--help')
  -V, --version
          Print version

Upgrading

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

Diagnostic logs

Firezone writes log files to disk. These logs stay on your computer and are not transmitted anywhere. If you encounter a bug, sending us the files may help us fix the bug.

Uninstalling

1. Stop the running Client
2. Delete the binary

Troubleshooting

Check if Firezone is controlling DNS with systemd-resolved DNS

resolvectl dns

Firezone Split DNS example:

Global:
Link 2 (enp0s6): 10.0.2.3 fec0::3
Link 3 (tun-firezone: 100.100.111.1) fd00:2021:1111:8000:100:100:111:0

Normal DNS example:

Global:
Link 2 (enp0s6): 10.0.2.3 fec0::3

Check if Firezone is being used

Check if curl reports a remote IP in Firezone's range when you connect to a resource:

> curl --silent --output /dev/null --write-out %{remote_ip}\\n https://example.com
100.96.0.2

Firezone resources use the ranges 100.96.0.0/11 and fd00:2021:1111:8000::/107.

Check if Firezone failed to revert DNS control

The systemd-resolved method reverts by itself when Firezone closes. However, the etc-resolv-conf method can fail to revert if Firezone crashes.

TODO

Known issues

None at time of writing.