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

Files

Thomas Eizinger 6d87bb4009 feat(connlib): expand single-label queries using search-domain (#8378 )

Search domains are a way of performing a DNS lookup without typing the
full-qualified domain name. For example, with a search domain of
`example.com`, performing a DNS query for `app` will automatically
expand the query to `app.example.com`. At present, this doesn't work
with Firezone because there is no way to configure an account-wide
search-domain.

With this PR, we extend the `Interface` message sent by the portal to
also include an optional `search_domain` field that must be a valid
domain name. If set, `connlib`'s DNS stub resolver will now append this
domain to all single-label queries and match the resulting domain
against all active DNS resource.

On Linux - with `systemd-resolved` as the DNS backend - we need to set
the search domain on the TUN interface as well and enable LLMNR in order
to be able to intercept these queries. `resolved` expands the query for
us, however, meaning with this configuration, we don't actually receive
a single-label query in `connlib`. Instead, we directly see
`app.example.com` when we type `host app` or `dig +search app` and have
`example.com` as our search domain.

MacOS has a similar system but with a different fallack. There, the
operating system will first try all configured search domains on the
system (typically just the ones set prior to Firezone starting), and
send queries for FQDN to all resolvers. If none of the resolvers
(including Firezone's stub resolver) return results, it sends the
single-label query directly to the primary resolver. To handle this
case, Firezone needs to know about the search-domain and expand it
itself when it receives the single-label query. In the future, we may
want to look into how we can configure MacOS such that it performs this
expansion for us.

On Windows and Android, queries for a single-label domain will be
directly sent to Firezone's stub resolver where we then hit the same
codepath as explained above.

Specifically, the way this codepath works is that if we receive a
single-label query AND we have a search-domain set, we expand it and
match that particular query against our list of resources. In every
other case, we continue on with the single-label domain.

Related: #8365
Fixes: #8377

2025-03-08 21:59:58 +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(connlib): expand single-label queries using search-domain (#8378 )

2025-03-08 21:59:58 +00:00

Cargo.toml

refactor(gui-client): de-duplicate logging of IPC message errors (#8157 )

2025-02-17 14:21:52 +00:00

README.md

style: Enforce code style across all supported languages using Prettier (#7322 )

2024-11-13 00:19:15 +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=$(uuidgen). The client requires this variable at startup.

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.