docs: Add headless Windows client (#8052)

This adds the following for the headless Windows client:

- website download redirects to use for permalinks
- Windows headless client user guide

It also cleans up old references and a few minor related things I found
while working on this.
This commit is contained in:
Jamil
2025-02-08 17:50:39 -08:00
committed by GitHub
parent 3d9c731ff4
commit 96f61e4bdb
14 changed files with 336 additions and 55 deletions

View File

@@ -37,6 +37,18 @@ module.exports = [
"https://www.github.com/firezone/firezone/releases/download/gui-client-1.4.3/firezone-client-gui-windows_1.4.3_x86_64.msi",
permanent: false,
},
/*
*
* Windows Headless Client
*
*/
{
source: "/dl/firezone-client-headless-windows/latest/x86_64",
destination:
// mark:current-headless-version
"https://www.github.com/firezone/firezone/releases/download/headless-client-1.4.1/firezone-client-headless-windows_1.4.1_x86_64.exe",
permanent: false,
},
/*
*
* Linux Clients

View File

@@ -12,14 +12,15 @@ by advanced users and admins.
## Log directory locations
| Component | Log directory |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| macOS Client | `~/Library/Group Containers/47R2M6779T.dev.firezone.firezone/Library/Caches/logs` and `/private/var/root/Library/Group Containers/47R2M6779T.dev.firezone.firezone/Library/Caches/logs` |
| iOS Client | N/A |
| Android/ChromeOS Client | `/data/data/dev.firezone.android/caches/logs` |
| Linux Client | Set by the user via the `LOG_DIR` environment variable, otherwise STDOUT |
| Windows Client | `%APPDATA%\Local\dev.firezone.client\data\logs` |
| Gateway | Logs are written to STDOUT by default and viewable either by `docker logs firezone-gateway` or `journalctl -u firezone-gateway` |
| Component | Log directory |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| macOS Client | `~/Library/Group Containers/47R2M6779T.dev.firezone.firezone/Library/Caches/logs` for the GUI process, and `/private/var/root/Library/Group Containers/47R2M6779T.dev.firezone.firezone/Library/Caches/logs` for the tunnel process |
| Windows GUI Client | `%LOCALAPPDATA%\dev.firezone.client\data\logs` for the GUI process, and `%PROGRAMDATA%\dev.firezone.client\data\logs` for the IPC service |
| Android/ChromeOS Client | `/data/data/dev.firezone.android/caches/logs` |
| iOS Client | N/A |
| Linux Headless Client | Set by the user via the `LOG_DIR` environment variable, otherwise `stderr` |
| Windows Headless Client | Set by the user via the `LOG_DIR` environment variable, otherwise `stderr` |
| Gateway | Logs are written to STDOUT by default and viewable either by `docker logs firezone-gateway` or `journalctl -u firezone-gateway` |
## Exporting Client logs

View File

@@ -93,8 +93,6 @@ We will add troubleshooting steps here in the future.
## Known issues
- ChromeOS devices using the Android 9 compatibility layer don't work with
Firezone. Android 11 and newer do work.
[#3620](https://github.com/firezone/firezone/issues/3620)
None at this time.
<SupportOptions />

View File

@@ -2,12 +2,12 @@ import SupportOptions from "@/components/SupportOptions";
# iOS Client
Firezone supports iOS with a native clients available in the iOS App Store. The
Firezone supports iOS with a native client available in the iOS App Store. The
iOS app also works for iPad.
## Prerequisites
- **iOS 15** or higher
- Any iOS device running **iOS 15** or higher
## Installation
@@ -98,7 +98,6 @@ We will add troubleshooting steps here in the future.
## Known issues
- If another VPN app is running on the system, Firezone may not work.
[#4733](https://github.com/firezone/firezone/issues/4733)
None at this time.
<SupportOptions />

View File

@@ -267,6 +267,6 @@ sudo mv /etc/resolv.conf.before-firezone /etc/resolv.conf
## Known issues
None at this time
None at this time.
<SupportOptions />

View File

@@ -1,13 +1,21 @@
import SupportOptions from "@/components/SupportOptions";
import Alert from "@/components/DocsAlert";
# Windows Client
# Windows GUI Client
The Windows GUI Client is designed for Windows computers where a user is present
to authenticate with your identity provider interactively.
<Alert color="info">
If you're looking for a headless client suitable for server or workstation use
cases where a user is not physically present, see the [Windows Headless
Client](/kb/client-apps/windows-headless-client) user guide instead, which
uses a long-lived Service Account token for authentication.
</Alert>
## Prerequisites
- **Windows 10** or higher
- **Windows 10** or higher, or **Windows Server 2016** or higher
- **x86-64** CPU
- [**WebView2**](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)
(The installer will install this automatically if needed)
@@ -206,5 +214,7 @@ the tunnel, and a GUI which allows the user to control Firezone.
- Firezone does not register itself with Windows as a VPN
[#2875](https://github.com/firezone/firezone/issues/2875)
- The Windows client is not yet available for Arm64 devices
[#2992](https://github.com/firezone/firezone/issues/2992)
<SupportOptions />

View File

@@ -0,0 +1,11 @@
import Content from "./readme.mdx";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Windows Headless Client • Firezone Docs",
description: "How to install and use the Firezone Windows headless client.",
};
export default function Page() {
return <Content />;
}

View File

@@ -0,0 +1,224 @@
import Alert from "@/components/DocsAlert";
import SupportOptions from "@/components/SupportOptions";
# Windows Headless Client
Headless Clients are designed to authenticate with long-lived
[service account](/kb/authenticate/service-accounts) tokens to enable
system-to-system connectivity where a user isn't present to authenticate with
your identity provider interactively.
<Alert color="info">
If you're looking for a Windows desktop Client that authenticates with your
identity provider instead, see the [Windows GUI
Client](/kb/client-apps/windows-client).
</Alert>
## Prerequisites
- **Windows 10** or higher, or **Windows Server 2016** or higher
- **x86-64** CPU
## Installation
Download the Windows headless Client from our [changelog page](/changelog), or
use the direct link below:
- [Download the Windows Headless Client for `x86_64`](/dl/firezone-client-headless-windows/latest/x86_64)
The client can then be run from any elevated command prompt. No installation is
necessary.
## Usage
### Running the Client
<Alert color="warning">
<strong>Note:</strong> The Windows Headless Client must be run with
administrator privileges.
</Alert>
Headless Clients require a service account token to authenticate to Firezone.
You can generate a token using the instructions in the
[service account](/kb/authenticate/service-accounts) documentation.
Once you have a token, you can run the client from an elevated powershell prompt
with a few environment variables like so:
```pwsh
> $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](#environment-variable-reference).
Most environment variables can also be set in the command line. For a full list,
see [help output](#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](/kb/deploy/dns) 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](https://docs.rs/env_logger/latest/env_logger/). |
### Help output
```text
> .\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:
standalone
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=]
--check
Check the configuration and return 0 before connecting to the API
Returns 1 if the configuration is wrong. Mostly non-destructive but may write a device ID to disk if one is not found.
--exit
Connect to the Firezone network and initialize, then exit
Use this to check how fast you can connect.
--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
1. Download a newer binary from one of the [links above](#installation).
1. Stop the running Client.
1. Replace the existing binary with the new one.
1. 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
1. 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:
```pwsh
Get-DnsClientNrptPolicy
```
Firezone Split DNS example:
```text
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:
```pwsh
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](https://github.com/firezone/firezone/issues/2992)
<SupportOptions />

View File

@@ -37,23 +37,25 @@ function Latest({
<p>
Version: <span className="font-semibold">{version}</span>
</p>
<p>
<p className="mb-4 md:mb-6 xl:mb-8">
Released:{" "}
<span className="font-semibold">
<time dateTime={date.toDateString()}>{utcDateString}</time>
</span>
</p>
<p className="mb-4 md:mb-6 xl:mb-8">
<ul className="mb-4 md:mb-6 xl:mb-8">
{downloadLinks.map((link) => (
<Link
key={link.href}
href={{ pathname: link.href.replace(":version", version) }}
className="hover:no-underline underline text-accent-500 mr-2"
>
{link.title}
</Link>
<li key={link.href}>
<Link
key={link.href}
href={{ pathname: link.href.replace(":version", version) }}
className="hover:no-underline underline text-accent-500 mr-2"
>
{link.title}
</Link>
</li>
))}
</p>
</ul>
{children}
</div>
</>

View File

@@ -6,7 +6,7 @@ import Unreleased from "./Unreleased";
export default function GUI({ title }: { title: string }) {
const downloadLinks =
title === "Windows"
title === "Windows GUI"
? [
{
title: "Download for x86_64",

View File

@@ -4,26 +4,38 @@ import Entries from "./Entries";
import Link from "next/link";
import Unreleased from "./Unreleased";
export default function Headless() {
const downloadLinks = [
{
href: "/dl/firezone-client-headless-linux/:version/x86_64",
title: "Download for x86_64",
},
{
href: "/dl/firezone-client-headless-linux/:version/aarch64",
title: "Download for aarch64",
},
{
href: "/dl/firezone-client-headless-linux/:version/armv7",
title: "Download for armv7",
},
];
export default function Headless({ title }: { title: string }) {
const downloadLinks =
title === "Windows Headless"
? [
{
href: "/dl/firezone-client-headless-windows/:version/x86_64",
title: "Download for x86_64",
},
]
: [
{
href: "/dl/firezone-client-headless-linux/:version/x86_64",
title: "Download for x86_64",
},
{
href: "/dl/firezone-client-headless-linux/:version/aarch64",
title: "Download for aarch64",
},
{
href: "/dl/firezone-client-headless-linux/:version/armv7",
title: "Download for armv7",
},
];
return (
<Entries downloadLinks={downloadLinks} title="Linux headless">
<Entries downloadLinks={downloadLinks} title={title}>
{/* When you cut a release, remove any solved issues from the "known issues" lists over in `client-apps`. This must not be done when the issue's PR merges. */}
<Unreleased></Unreleased>
<Unreleased>
<ChangeItem pull="8041">
Publishes the headless client for Windows.
</ChangeItem>
</Unreleased>
<Entry version="1.4.1" date={new Date("2025-01-28")}>
<ChangeItem pull="7551">
Fixes an issue where large DNS responses were incorrectly discarded.

View File

@@ -29,20 +29,23 @@ export default function Changelog() {
<TabsItem title="Gateway" icon={HiServerStack}>
<Gateway />
</TabsItem>
<TabsItem title="Linux GUI" icon={FaLinux}>
<GUI title="Linux GUI" />
</TabsItem>
<TabsItem title="Apple" icon={FaApple}>
<TabsItem title="macOS / iOS" icon={FaApple}>
<Apple />
</TabsItem>
<TabsItem title="Windows" icon={FaWindows}>
<TabsItem title="Windows GUI" icon={FaWindows}>
<GUI title="Windows" />
</TabsItem>
<TabsItem title="Windows Headless" icon={FaWindows}>
<Headless title="Windows Headless" />
</TabsItem>
<TabsItem title="Android" icon={FaAndroid}>
<Android />
</TabsItem>
<TabsItem title="Linux GUI" icon={FaLinux}>
<GUI title="Linux GUI" />
</TabsItem>
<TabsItem title="Linux Headless" icon={FaLinux}>
<Headless />
<Headless title="Linux Headless" />
</TabsItem>
</TabsGroup>
{sha && (

View File

@@ -96,18 +96,21 @@ export default function KbSidebar() {
<SidebarCollapse prefix="/kb/client-apps" label="Client apps">
<SidebarItem href="/kb/client-apps">Overview</SidebarItem>
<SidebarItem href="/kb/client-apps/macos-client">macOS</SidebarItem>
<SidebarItem href="/kb/client-apps/ios-client">iOS</SidebarItem>
<SidebarItem href="/kb/client-apps/windows-client">
Windows
</SidebarItem>
<SidebarItem href="/kb/client-apps/linux-gui-client">
Linux
</SidebarItem>
<SidebarItem href="/kb/client-apps/ios-client">iOS</SidebarItem>
<SidebarItem href="/kb/client-apps/android-client">
Android & ChromeOS
</SidebarItem>
<SidebarItem href="/kb/client-apps/linux-client">
Linux Headless
</SidebarItem>
<SidebarItem href="/kb/client-apps/linux-gui-client">
Linux GUI
<SidebarItem href="/kb/client-apps/windows-headless-client">
Windows Headless
</SidebarItem>
</SidebarCollapse>
<SidebarCollapse prefix="/kb/use-cases" label="Use cases">

View File

@@ -18,6 +18,11 @@ const versionedRedirects = [
destination:
"https://www.github.com/firezone/firezone/releases/download/gui-client-:version/firezone-client-gui-windows_:version_x86_64.msi",
},
{
source: /^\/dl\/firezone-client-headless-windows\/(\d+\.\d+\.\d+)\/x86_64$/,
destination:
"https://www.github.com/firezone/firezone/releases/download/headless-client-:version/firezone-client-headless-windows_:version_x86_64.exe",
},
{
source: /^\/dl\/firezone-client-gui-linux\/(\d+\.\d+\.\d+)\/x86_64$/,
destination:
@@ -65,6 +70,7 @@ export const config = {
"/dl/firezone-client-macos/(\\d+).(\\d+).(\\d+)",
"/dl/firezone-client-android/(\\d+).(\\d+).(\\d+)",
"/dl/firezone-client-gui-windows/(\\d+).(\\d+).(\\d+)/x86_64",
"/dl/firezone-client-headless-windows/(\\d+).(\\d+).(\\d+)/x86_64",
"/dl/firezone-client-gui-linux/(\\d+).(\\d+).(\\d+)/x86_64",
"/dl/firezone-client-gui-linux/(\\d+).(\\d+).(\\d+)/aarch64",
"/dl/firezone-client-headless-linux/(\\d+).(\\d+).(\\d+)/x86_64",