import Alert from "@/components/DocsAlert"; import SupportOptions from "@/components/SupportOptions"; import { TabsItem, TabsGroup } from "@/components/Tabs";

Windows Headless Client

Headless Clients are designed to authenticate with long-lived service account tokens to enable system-to-system connectivity where a user isn't present to authenticate with your identity provider interactively.

Prerequisites

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

Installation

Download the Windows headless Client from our changelog page, or use the direct link below:

• Download the Windows Headless Client for x86_64

The client can then be run from any elevated command prompt. No installation is necessary.

From a terminal, run the following command to install the headless client.

winget install Firezone.Client.Headless

Usage

Running the Client

Headless Clients require a service account token to authenticate to Firezone. You can generate a token using the instructions in the service account documentation.

Once you have a token, you can run the client from an elevated powershell prompt with a few environment variables like so:

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

By default, the client only logs to stdout on level error and above. Set RUST_LOG="info" to see more logs, and 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.

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.

Environment variable reference

Help output

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

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

Commands:
  help        Print this message or the help of the given subcommand(s)

Options:
      --dns-control <DNS_CONTROL>
          [env: FIREZONE_DNS_CONTROL=]
          [default: nrpt]

          Possible values:
          - disabled: Explicitly disable DNS control
          - nrpt:     NRPT, the only DNS control method we use on Windows

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

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

          [env: FIREZONE_NO_TELEMETRY=]

      --activate-internet-resource
          Activate the Internet Resource for this Client

          [env: FIREZONE_ACTIVATE_INTERNET_RESOURCE=]

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

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 error).

Uninstalling

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

Troubleshooting

Check if Firezone is controlling DNS

In the Start Menu, search for "Windows Powershell". Open it and run this command:

Get-DnsClientNrptPolicy

Firezone Split DNS example:

Namespace                        : .
QueryPolicy                      :
SecureNameQueryFallback          :
DirectAccessIPsecCARestriction   :
DirectAccessProxyName            :
DirectAccessDnsServers           :
DirectAccessEnabled              :
DirectAccessProxyType            : NoProxy
DirectAccessQueryIPsecEncryption :
DirectAccessQueryIPsecRequired   : False
NameServers                      : {100.100.111.1, fd00:2021:1111:8000:100:100:111:0}
DnsSecIPsecCARestriction         :
DnsSecQueryIPsecEncryption       :
DnsSecQueryIPsecRequired         : False
DnsSecValidationRequired         : False
NameEncoding                     : Utf8WithoutMapping

If Firezone's Split DNS is not active, the output will be empty.

Revert Firezone DNS control

If Firezone crashes and does not revert control of the system's DNS, you can revert it manually with this command:

Get-DnsClientNrptRule | where Comment -eq firezone-fd0020211111 | foreach { Remove-DnsClientNrptRule -Name $_.Name -Force }

Known issues

• If a search domain is applied, DNS suffix search list of other adapters are ignored. #8430.
• The Windows client is not yet available for Arm64 devices #2992