Windows Headless Client

The Windows Headless Client is a console-only build of the Firezone Client. It supports two authentication modes:

• Service account tokens -- long-lived, multi-owner tokens generated in the admin portal. Best for system-to-system connectivity where no user is present to authenticate. See Service Accounts.
• User tokens via browser-based sign-in -- short-lived tokens obtained by signing the running user into the portal in a browser. Useful when you want a human user to authenticate the Client on a Windows server they manage without using the GUI Client. See Browser-based authentication.

Prerequisites

• Windows 10 or higher, or Windows Server 2016 or higher
• x86-64 CPU

Download

winget install Firezone.Client.Headless

Usage

Running the Client

The Client must be authenticated before it can connect. Pick one of the two flows below depending on whether you want to authenticate as a service account or as a user.

With a service account token

Service account tokens are long-lived and ideal for unattended systems. Generate one using the instructions in the service account documentation, then run the Client from an elevated PowerShell prompt with a few environment variables:

> $env:FIREZONE_TOKEN="YOUR_TOKEN_HERE"
> .\firezone-client-headless-windows_<VERSION>_x86_64.exe

By default, the client logs to stdout at level info. Set $env:RUST_LOG="debug" for more verbose output, and $env:LOG_DIR to write logs to disk. For a full list of environment variables, see below.

Most environment variables can also be set in the command line. For a full list, see help output.

Browser-based authentication

If you want to authenticate the Client as a normal user with your identity provider, use the sign-in subcommand. The Client prints a URL for you to open in any browser; after signing in, the portal displays a token that you paste back into the terminal. The token is then stored on disk at C:\ProgramData\dev.firezone.client\token.txt (configurable with --token-path or FIREZONE_TOKEN_PATH) and reused on subsequent runs.

> .\firezone-client-headless-windows_<VERSION>_x86_64.exe sign-in `
    --account-slug <YOUR_ACCOUNT_SLUG>

The --account-slug flag is optional; if omitted, the URL takes you to the generic sign-in page where you can pick your account.

Once a token is saved you can start the Client without setting FIREZONE_TOKEN:

> .\firezone-client-headless-windows_<VERSION>_x86_64.exe

To remove a saved token, run sign-out:

> .\firezone-client-headless-windows_<VERSION>_x86_64.exe sign-out

Disabling split DNS

By default, Split DNS is enabled for the Windows Headless Client. In most cases, this is what you want.

If you're experiencing DNS issues or incompatibilities with other DNS software on your system, and you don't need to access DNS Resources, you can disable Split DNS.

To do this, set the FIREZONE_DNS_CONTROL environment variable to disabled.

Read more about how DNS works in Firezone.

Help output

> .\firezone-client-headless-windows_1.5.8_x86_64.exe --help
Command-line args for the headless Client

Usage: firezone-client-headless-windows_1.5.8_x86_64.exe [OPTIONS] [COMMAND]

Commands:
  sign-in   Sign in via browser-based authentication
  sign-out  Sign out by removing the stored token
  help      Print this message or the help of the given subcommand(s)

Options:
      --dns-control <DNS_CONTROL>
          Possible values:
          - disabled: Explicitly disable DNS control
          - nrpt:     NRPT, the only DNS control method we use on Windows

          [env: FIREZONE_DNS_CONTROL=]
          [default: nrpt]

  -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=]

      --firezone-name <FIREZONE_NAME>
          Friendly name for this client to display in the UI

          [env: FIREZONE_NAME=]

  -i, --firezone-id <FIREZONE_ID>
          Identifier used by the portal to identify and display the device

          [env: FIREZONE_ID=]

      --activate-internet-resource
          Activate the Internet Resource.

          To actually use the Internet Resource, the user must also have a policy granting access to the Internet Resource.

          [env: FIREZONE_ACTIVATE_INTERNET_RESOURCE=]

      --no-telemetry
          Disable sentry.io crash-reporting agent

          [env: FIREZONE_NO_TELEMETRY=]

      --token-path <TOKEN_PATH>
          A filesystem path where the token can be found

          [env: FIREZONE_TOKEN_PATH=]
          [default: C:\ProgramData\dev.firezone.client\token.txt]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

The sign-in subcommand accepts --auth-base-url (FIREZONE_AUTH_BASE_URL, default https://app.firezone.dev) and --account-slug (FIREZONE_ACCOUNT_SLUG). The sign-out subcommand accepts -f, --force to skip the confirmation prompt.

Environment variable reference

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

By default, the Windows headless Client does not write logs to disk. You can enable file logging by setting the LOG_DIR environment variable to a path that the user running the Client can write to.

This will write logs at the level specified by the RUST_LOG environment variable (by default info).

Uninstalling

1. Stop the running Client
2. Delete the binary file from your system

Troubleshooting

For DNS checks, reverting DNS control after a crash, and known issues, see the Troubleshooting guide.

Need help? See all support options.