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

Files

Thomas Eizinger 0310bafbcd feat(clients): gracefully close connections on shutdown (#10400 )

In #10076, connlib gained the ability to gracefully close connections
between peers. The Gateway already uses this when it is being gracefully
shutdown such as during an upgrade. This allows Clients to immediately
fail-over to a different Gateway instead of waiting for an ICE timeout.

When a Client signs out, we currently just drop all the state, resulting
in an ICE timeout on the Gateway ~15 seconds later. This makes it
difficult for us to analyze, whether an ICE timeout in the logs presents
an actual problem where a network connection got cut or whether the
Client simply signed out.

Whilst not water-tight, attempting to gracefully close our connections
when the Client signs out is better than nothing so we implement this
here.

All Clients use the `Session` abstraction from `client-shared` which
spawns the event-loop into a dedicated task.

- For the Linux and Windows GUI client, the already present tokio
runtime instance of the tunnel service is used for this.
- For Android and Apple, we create a dedicated, single-threaded runtime
instance for connlib.
- For the headless client, we also reuse the already existing tokio
runtime instance of the binary.

In case of Android, Apple and the headless client, this means we need to
ensure the tokio runtime instances stays alive long enough to actually
complete the graceful shutdown task. We achieve this by draining the
`EventStream` returned from `Session`. The `EventStream` is a wrapper
around a channel connected to the event-loop. This stream only finishes
once the event-loop is entirely dropped (and therefore completed the
graceful shutdown) as it holds the sender-end of the channel.

In case of the Linux and Windows GUI client, the runtime outlives the
`Session` because it is scoped to the entire tunnel process. Therefore,
no additional measures are necessary there to ensure the graceful
shutdown task completes.

2025-09-23 03:40: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(clients): gracefully close connections on shutdown (#10400 )

2025-09-23 03:40:52 +00:00

Cargo.toml

feat(linux): try to set rmem_max and wmem_max on startup (#10349 )

2025-09-17 23:05:01 +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.