mirror of https://github.com/outbackdingo/firezone.git synced 2026-01-27 10:18:54 +00:00

Files

Thomas Eizinger 166b0d1573 feat(linux): compute device ID from /etc/machine-id (#10805 )

All of our Linux applications have a soft-dependency on systemd. That
is, in the default configuration, we expect systemd to be present on the
machine. The only exception here are the docker containers for Headless
Client and Gateway.

For the GUI client in particular, systemd is a hard-dependency in order
to control DNS on the system which we do via `systemd-resolved`. To
secure the communication between the GUI client and its tunnel process,
we automatically create a group called `firezone-client` to which the
user gets added. All members of the group are allowed to access the unix
socket which is used for IPC between the two processes. Membership in
this group is also a prerequisite for accessing any of the configuration
files.

On the first launch of the GUI client on a Linux system, this presents a
problem. For group membership changes to take the effect, the user needs
to reboot. We say that in the documentation but it is unclear whether
all users will read that thoroughly enough. To help the user, the GUI
client checks for membership of the current user in the group and alerts
the user via a dialog box if that isn't the case. This would all be fine
if it would actually work. Unfortunately, that check ends up being too
late in the process. If we aren't a member of the group, we cannot read
the device ID and bail early, thus never reaching the check and
terminating the process without any dialog box or user-visible error.

We could attempt to fix this by shuffling around some of the startup
init code. That is a sub-optimal solution however because it a) may get
broken again in the future and b) it means we have to delay
initialisation of telemetry until a much later point.

Given that this is only a problem on Linux, a better solution is to
simply not rely on the disk-based device ID at all. Instead, we can
integrate with systemd and deterministically derive a device ID from the
unique machine ID and a randomly chosen "app ID".

For backwards-compatibility reasons, the disk-based device ID is still
prioritised. For all new installs however, we will use the one based on
`/etc/machine-id`.

2025-11-10 02:29:52 +00:00

docs

refactor(linux-client): replace client-tunnel with headless-client which is the same thing (#4516 )

2024-04-10 22:01:55 +00:00

src

feat(linux): compute device ID from /etc/machine-id (#10805 )

2025-11-10 02:29:52 +00:00

Cargo.toml

chore: publish headless-client 1.5.4 (#10590 )

2025-10-16 09:15:32 +00:00

README.md

fix(docs): use sha256sum over sha256 (#9690 )

2025-06-27 20:08:41 +00:00

README.md

headless-client

This crate acts as the CLI / headless Client, and the privileged tunnel service for the GUI Client, for both Linux and Windows.

It is built as:

headless-client to act as the Linux / Windows headless Client
firezone-headless-client to act as the Linux tunnel service, Windows headless Client, or Windows tunnel service

In general, the brand name should be part of the file name, but the OS name should not be.

Running

To run the headless Client:

Generate a new Service account token from the "Actors -> Service Accounts" section of the admin portal and save it in your secrets manager. The Firezone Linux client requires a service account at this time.
Ensure /etc/dev.firezone.client/token is only readable by root (i.e. chmod 400)
Ensure /etc/dev.firezone.client/token contains the Service account token. The Client needs this before it can start
Set FIREZONE_ID to a unique string to identify this client in the portal, e.g. export FIREZONE_ID=$(head -c 32 /dev/urandom | sha256sum | cut -d' ' -f1). The client requires this variable at startup. We recommend this to be a 64 character hex string.

Set LOG_DIR to a suitable directory for writing logs

export LOG_DIR=/tmp/firezone-logs
mkdir $LOG_DIR

Now, you can start the client with:

./firezone-headless-client standalone

If you're running as an unprivileged user, you'll need the CAP_NET_ADMIN capability to open /dev/net/tun. You can add this to the client binary with:

sudo setcap 'cap_net_admin+eip' /path/to/firezone-headless-client

Building

Assuming you have Rust installed, you can build the headless Client with:

cargo build --release -p firezone-headless-client

The binary will be in target/release/firezone-headless-client

The release on Github are built with musl. To build this way, use:

rustup target add x86_64-unknown-linux-musl
sudo apt-get install musl-tools
cargo build --release -p headless-client --target x86_64-unknown-linux-musl

Files

/etc/dev.firezone.client/token - The service account token, provided by the human administrator. Must be owned by root and have 600 permissions (r/w by owner, nobody else can read) If present, the tunnel will ignore any GUI Client and run as a headless Client. If absent, the tunnel will wait for commands from a GUI Client
/usr/bin/firezone-headless-client - The tunnel binary. This must run as root so it can modify the system's DNS settings. If DNS is not needed, it only needs CAP_NET_ADMIN.
/usr/lib/systemd/system/firezone-headless-client.service - A systemd service unit, installed by the deb package.
/var/lib/dev.firezone.client/config/firezone-id - The device ID, unique across an organization. The tunnel will generate this if it's not present.