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.
If you're looking for a Windows desktop Client that authenticates with your identity provider instead, see the Windows GUI Client.
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:
The client can then be run from any elevated command prompt. No installation is necessary.
Usage
Running the Client
Note: The Windows Headless Client must be run with administrator privileges.
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
| Variable Name | Default Value | Description |
|---|---|---|
FIREZONE_TOKEN | Service account token generated by the portal to authenticate this Client. | |
FIREZONE_NAME | <system hostname> | Friendly name for this client to display in the UI. |
FIREZONE_ID | Identifier used by the portal to unqiuely identify this client. | |
FIREZONE_DNS_CONTROL | (blank) | The DNS control method to use. The default is nrpt, the only supported option on Windows. Set this to disabled to disable DNS control to route IP or CIDR resources only. |
LOG_DIR | File logging directory. Should be a path that's writeable by the current user. If unset, logs will be written to stdout only. | |
RUST_LOG | error | Log level for the client. Set to debug for verbose logging. Read more about configuring Rust log levels here. |
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=]
--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
- Download a newer binary from one of the links above.
- Stop the running Client.
- Replace the existing binary with the new one.
- 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
- Stop the running Client
- 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
- The Windows client is not yet available for Arm64 devices #2992
Need additional help?
See all support options or try asking on one of our community-powered support channels:
- Discussion forums: Ask questions, report bugs, and suggest features.
- Discord server: Join discussions, meet other users, and chat with the Firezone team
- Email us: We read every message.