From 96f61e4bdbaf5de37fac9b5f19bc91ad4dc9eb3e Mon Sep 17 00:00:00 2001 From: Jamil Date: Sat, 8 Feb 2025 17:50:39 -0800 Subject: [PATCH] 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. --- website/redirects.js | 12 + website/src/app/kb/administer/logs/readme.mdx | 17 +- .../kb/client-apps/android-client/readme.mdx | 4 +- .../app/kb/client-apps/ios-client/readme.mdx | 7 +- .../kb/client-apps/linux-client/readme.mdx | 2 +- .../kb/client-apps/windows-client/readme.mdx | 14 +- .../windows-headless-client/page.tsx | 11 + .../windows-headless-client/readme.mdx | 224 ++++++++++++++++++ website/src/components/Changelog/Entries.tsx | 22 +- website/src/components/Changelog/GUI.tsx | 2 +- website/src/components/Changelog/Headless.tsx | 46 ++-- website/src/components/Changelog/index.tsx | 15 +- website/src/components/KbSidebar/index.tsx | 9 +- website/src/middleware.ts | 6 + 14 files changed, 336 insertions(+), 55 deletions(-) create mode 100644 website/src/app/kb/client-apps/windows-headless-client/page.tsx create mode 100644 website/src/app/kb/client-apps/windows-headless-client/readme.mdx diff --git a/website/redirects.js b/website/redirects.js index 7cdea845e..1f31e6846 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -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 diff --git a/website/src/app/kb/administer/logs/readme.mdx b/website/src/app/kb/administer/logs/readme.mdx index 892253137..9c03c5168 100644 --- a/website/src/app/kb/administer/logs/readme.mdx +++ b/website/src/app/kb/administer/logs/readme.mdx @@ -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 diff --git a/website/src/app/kb/client-apps/android-client/readme.mdx b/website/src/app/kb/client-apps/android-client/readme.mdx index 70cc5a5eb..082131568 100644 --- a/website/src/app/kb/client-apps/android-client/readme.mdx +++ b/website/src/app/kb/client-apps/android-client/readme.mdx @@ -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. diff --git a/website/src/app/kb/client-apps/ios-client/readme.mdx b/website/src/app/kb/client-apps/ios-client/readme.mdx index 77d46ebba..04b1cf939 100644 --- a/website/src/app/kb/client-apps/ios-client/readme.mdx +++ b/website/src/app/kb/client-apps/ios-client/readme.mdx @@ -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. diff --git a/website/src/app/kb/client-apps/linux-client/readme.mdx b/website/src/app/kb/client-apps/linux-client/readme.mdx index aaa0694bf..8ca12d42e 100644 --- a/website/src/app/kb/client-apps/linux-client/readme.mdx +++ b/website/src/app/kb/client-apps/linux-client/readme.mdx @@ -267,6 +267,6 @@ sudo mv /etc/resolv.conf.before-firezone /etc/resolv.conf ## Known issues -None at this time +None at this time. diff --git a/website/src/app/kb/client-apps/windows-client/readme.mdx b/website/src/app/kb/client-apps/windows-client/readme.mdx index e0797437e..dc3112df7 100644 --- a/website/src/app/kb/client-apps/windows-client/readme.mdx +++ b/website/src/app/kb/client-apps/windows-client/readme.mdx @@ -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. + + 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. + + ## 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) diff --git a/website/src/app/kb/client-apps/windows-headless-client/page.tsx b/website/src/app/kb/client-apps/windows-headless-client/page.tsx new file mode 100644 index 000000000..99f896d25 --- /dev/null +++ b/website/src/app/kb/client-apps/windows-headless-client/page.tsx @@ -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 ; +} diff --git a/website/src/app/kb/client-apps/windows-headless-client/readme.mdx b/website/src/app/kb/client-apps/windows-headless-client/readme.mdx new file mode 100644 index 000000000..54a83f7e6 --- /dev/null +++ b/website/src/app/kb/client-apps/windows-headless-client/readme.mdx @@ -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. + + + 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). + + +## 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 + + + 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](/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__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` | `` | 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 + [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 + File logging directory. Should be a path that's writeable by the current user + + [env: LOG_DIR=] + + -m, --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 + Friendly name for this client to display in the UI + + [env: FIREZONE_NAME=] + + -i, --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 + 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) + + diff --git a/website/src/components/Changelog/Entries.tsx b/website/src/components/Changelog/Entries.tsx index 3bf5eaecb..6de1fb293 100644 --- a/website/src/components/Changelog/Entries.tsx +++ b/website/src/components/Changelog/Entries.tsx @@ -37,23 +37,25 @@ function Latest({

Version: {version}

-

+

Released:{" "}

-

+

    {downloadLinks.map((link) => ( - - {link.title} - +
  • + + {link.title} + +
    • ))} -

    +
{children} diff --git a/website/src/components/Changelog/GUI.tsx b/website/src/components/Changelog/GUI.tsx index b8bf90c26..a124e67e8 100644 --- a/website/src/components/Changelog/GUI.tsx +++ b/website/src/components/Changelog/GUI.tsx @@ -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", diff --git a/website/src/components/Changelog/Headless.tsx b/website/src/components/Changelog/Headless.tsx index 1ff93e931..4dcd63f1c 100644 --- a/website/src/components/Changelog/Headless.tsx +++ b/website/src/components/Changelog/Headless.tsx @@ -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 ( - + {/* 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. */} - + + + Publishes the headless client for Windows. + + Fixes an issue where large DNS responses were incorrectly discarded. diff --git a/website/src/components/Changelog/index.tsx b/website/src/components/Changelog/index.tsx index e2d619041..404c517f2 100644 --- a/website/src/components/Changelog/index.tsx +++ b/website/src/components/Changelog/index.tsx @@ -29,20 +29,23 @@ export default function Changelog() { - - - - + - + + + + + + + - + {sha && ( diff --git a/website/src/components/KbSidebar/index.tsx b/website/src/components/KbSidebar/index.tsx index e1b465466..2adc59003 100644 --- a/website/src/components/KbSidebar/index.tsx +++ b/website/src/components/KbSidebar/index.tsx @@ -96,18 +96,21 @@ export default function KbSidebar() { Overview macOS - iOS Windows + + Linux + + iOS Android & ChromeOS Linux Headless - - Linux GUI + + Windows Headless diff --git a/website/src/middleware.ts b/website/src/middleware.ts index de949dfa2..5c8e0946a 100644 --- a/website/src/middleware.ts +++ b/website/src/middleware.ts @@ -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",