mirror of
https://github.com/outbackdingo/firezone.git
synced 2026-01-27 10:18:54 +00:00
29bc276bf2
Currently, `connlib` is entirely single-threaded. This allows us to reuse a single buffer for processing IP packets and makes reasoning of the packet processing code very simple. Being single-threaded also means we can only make use of a single CPU core and all operations have to be sequential. Analyzing `connlib` using `perf` shows that we spend 26% of our CPU time writing packets to the TUN interface [0]. Because we are single-threaded, `connlib` cannot do anything else during this time. If we could offload the writing of these packets to a different thread, `connlib` could already process the next packet while the current one is writing. Packets that we send to the TUN interface arrived as an encrypted WG packet over UDP and get decrypted into a - currently - shared buffer. Moving the writing to a different thread implies that we have to have more of these buffer that the next packet(s) can be decrypted into. To avoid IP fragmentation, we set the maximum IP MTU to 1280 bytes on the TUN interface. That actually isn't very big and easily fits into a stackframe. The default stack size for threads is 2MB [1]. Instead of creating more buffers and cycling through them, we can also simply stack-allocate our IP packets. This incurs some overhead from copying packets but it is only ~3.5% [2] (This was measured without a separate thread). With stack-allocated packets, almost all lifetime-annotations go away which in itself is already a welcome ergonomics boost. Stack-allocated packets also means we can simply spawn a new thread for the packet processing. This thread is connected with two channel to connlib's main thread. The capacity of 1000 packets will at most consume an additional 3.5 MB of memory which is fine even on our most-constrained devices such as iOS. [0]: https://share.firefox.dev/3z78CzD [1]: https://doc.rust-lang.org/std/thread/#stack-size [2]: https://share.firefox.dev/3Bf4zla Resolves: #6653. Resolves: #5541.
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-clientto act as the Linux / Windows headless Clientfirezone-headless-clientto 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/tokenis only readable by root (i.e.chmod 400) - Ensure
/etc/dev.firezone.client/tokencontains the Service account token. The Client needs this before it can start - Set
FIREZONE_IDto a unique string to identify this client in the portal, e.g.export FIREZONE_ID=$(uuidgen). The client requires this variable at startup. - Set
LOG_DIRto a suitable directory for writing logsexport 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.