github-personal/firezone
1
0
Fork 0
mirror of https://github.com/outbackdingo/firezone.git synced 2026-01-27 10:18:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(client): update Linux and Windows Client docs (#5007)

Browse Source 
Closes #4995
Closes #4925
Closes #4997
Closes #5047 
Supersedes #4965 and #5004.

NOT changing:

- Page description for other Clients. That is still "Firezone
Documentation"

Need these Clients:

- Windows GUI
- Linux headless 
- Linux GUI

to have these things documented: (with exact terms)

- Prerequisites
- Installation
- Usage
  - Signing in
  - Accessing a Resource
  - Signing out
  - Quitting
- Upgrading
- Diagnostic logs
- Uninstalling
- Troubleshooting
  - DNS not reverted after exit
  - DNS Resource not accessible
- Known issues

```[tasklist]
### Before merging
- [x] Test Windows GUI instructions
- [x] Add troubleshooting for #5027
- [x] Fill in troubleshooting sections
- [x] Test Linux GUI instructions
- [x] Linux headless - Make sure SIGTERM or Ctrl+C or whatever reverts resolv.conf
- [x] Test Linux Headless instructions
- [x] Page descriptions should be "How to install and use the Firezone $OS $UI client."
- [x] ~~Linux headless - Confirm behaviors and default values of all env vars~~ (skipping - The ones that are used are exercised)
- [x] Grep for TODOs
- [x] Change "un-install" to "uninstall"
- [x] Capitalize "Client" where needed
- [x] Change "IPC service" to "Tunnel service" or something
- [x] Change "SplitDNS" to "Split DNS"
- [ ] Wait for next Client release to be cut
```

---------

Signed-off-by: Jamil <jamilbk@users.noreply.github.com>
Signed-off-by: Reactor Scram <ReactorScram@users.noreply.github.com>
Co-authored-by: Jamil Bou Kheir <jamilbk@users.noreply.github.com>
This commit is contained in:
Reactor Scram
2024-05-22 15:22:46 -05:00
committed by GitHub
parent 61534f92b0
commit 2416d4f45c
19 changed files with 557 additions and 133 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
rust/gui-client/docs/intended_behavior.md
View File

@@ -4,6 +4,8 @@ A less exhaustive version of [Manual Testing](manual_testing.md)
## Smoke test checklist (Ubuntu)
Keep this synchronized with the Linux GUI docs in `/website/src/app/kb/user-guides/linux-gui-client`
Best performed on a clean VM
1. Run `scripts/firezone-client-gui-install.sh`
@@ -41,6 +43,8 @@ Best performed on a clean VM
## Smoke test checklist (Windows)
Keep this synchronized with the Windows GUI docs in `/website/src/app/kb/user-guides/windows-client`
x86_64 only, see issue #2992. Best performed on a clean VM.
1. Run the MSI installer and ensure "Launch Firezone" is checked at the end

2
rust/gui-client/src-tauri/src/client.rs
View File

@@ -127,7 +127,7 @@ fn show_error_dialog(error: &gui::Error) -> Result<()> {
gui::Error::DeepLink(deep_link::Error::CantListen) => "Firezone is already running. If it's not responding, force-stop it.".to_string(),
gui::Error::DeepLink(deep_link::Error::Other(error)) => error.to_string(),
gui::Error::Logging(_) => "Logging error".to_string(),
gui::Error::UserNotInFirezoneGroup => format!("You are not a member of the group `{FIREZONE_GROUP}`. Try `sudo adduser $USER {FIREZONE_GROUP}` and then reboot"),
gui::Error::UserNotInFirezoneGroup => format!("You are not a member of the group `{FIREZONE_GROUP}`. Try `sudo usermod -aG {FIREZONE_GROUP} $USER` and then reboot"),
gui::Error::Other(error) => error.to_string(),
};

6
rust/headless-client/src/lib.rs
View File

@@ -95,6 +95,10 @@ struct Cli {
#[arg(default_value_t = default_token_path().display().to_string(), env = "FIREZONE_TOKEN_PATH", long)]
token_path: String,
/// Friendly name for this client to display in the UI.
#[arg(long, env = "FIREZONE_NAME")]
firezone_name: Option<String>,
/// Identifier used by the portal to identify and display the device.
// AKA `device_id` in the Windows and Linux GUI clients
@@ -192,7 +196,7 @@ pub fn run_only_headless_client() -> Result<()> {
cli.api_url,
&token,
firezone_id,
None,
cli.firezone_name,
public_key.to_bytes(),
)?;

3
scripts/firezone-client-gui-install.sh
View File

@@ -1,4 +1,5 @@
#!/usr/bin/env bash
# Keep this synchronized with the Linux GUI docs in `/website/src/app/kb/user-guides/linux-gui-client`
# Usage: ./firezone-client-gui-install.sh ./firezone-client-gui_VERSION_ARCH.deb
#
# The `./` is necessary
@@ -14,7 +15,7 @@ echo "Installing Firezone..."
sudo apt-get install --yes "$DEB_PATH"
echo "Adding your user to the $GROUP_NAME group..."
sudo usermod -a -G "$GROUP_NAME" "$USER"
sudo usermod -aG "$GROUP_NAME" "$USER"
# Check if the user is already in the group
if ! groups | grep "$GROUP_NAME" &>/dev/null; then

2
website/next.config.mjs
View File

@@ -20,6 +20,7 @@ import langJson from "highlight.js/lib/languages/json";
import langBash from "highlight.js/lib/languages/bash";
import langRust from "highlight.js/lib/languages/rust";
import langRuby from "highlight.js/lib/languages/ruby";
import langPowerShell from "highlight.js/lib/languages/powershell";
const highlightLanguages = {
elixir: langElixir,
@@ -28,6 +29,7 @@ const highlightLanguages = {
bash: langBash,
rust: langRust,
ruby: langRuby,
powershell: langPowerShell,
};
/** @type {import('next').NextConfig} */

8
website/pnpm-lock.yaml generated
View File

@@ -55,7 +55,7 @@ importers:
version: 0.9.0(react-dom@18.2.0(react@18.2.0))(react@18.2.0)(tailwindcss@3.4.3)
framer-motion:
specifier: ^11.2.4
version: 11.2.4(react-dom@18.2.0(react@18.2.0))(react@18.2.0)
version: 11.2.6(react-dom@18.2.0(react@18.2.0))(react@18.2.0)
highlight.js:
specifier: ^11.9.0
version: 11.9.0
@@ -840,8 +840,8 @@ packages:
fraction.js@4.3.7:
resolution: {integrity: sha512-ZsDfxO51wGAXREY55a7la9LScWpwv9RxIrYABrlvOFBlH/ShPnrtsXeuUIfXKKOVicNxQ+o8JTbJvjS4M89yew==}
framer-motion@11.2.4:
resolution: {integrity: sha512-D+EXd0lspaZijv3BJhAcSsyGz+gnvoEdnf+QWkPZdhoFzbeX/2skrH9XSVFb0osgUnCajW8x1frjhLuKwa/Reg==}
framer-motion@11.2.6:
resolution: {integrity: sha512-XUrjjBt57e5YoHQtjwc3eNchFBuHvIgN/cS8SC4oIaAn2J/0+bLanUxXizidJKZVeHJam/JrmMnPRjYMglVn5g==}
peerDependencies:
'@emotion/is-prop-valid': '*'
react: ^18.0.0
@@ -2593,7 +2593,7 @@ snapshots:
fraction.js@4.3.7: {}
framer-motion@11.2.4(react-dom@18.2.0(react@18.2.0))(react@18.2.0):
framer-motion@11.2.6(react-dom@18.2.0(react@18.2.0))(react@18.2.0):
dependencies:
tslib: 2.6.2
optionalDependencies:

4
website/redirects.js
View File

@@ -3,7 +3,7 @@
module.exports = [
/*
*
* Windows Client
* Windows GUI Client
*
*/
// latest
@@ -23,7 +23,7 @@ module.exports = [
},
/*
*
* Linux Client
* Linux Clients
*
*/
// latest

2
website/src/app/kb/user-guides/android-client/page.tsx
View File

@@ -3,7 +3,7 @@ import { Metadata } from "next";
import LastUpdated from "@/components/LastUpdated";
export const metadata: Metadata = {
title: "Android Client • Firezone Docs",
title: "Android & ChromeOS Client • Firezone Docs",
description: "Firezone Documentation",
};

2
website/src/app/kb/user-guides/ios-client/page.tsx
View File

@@ -3,7 +3,7 @@ import { Metadata } from "next";
import LastUpdated from "@/components/LastUpdated";
export const metadata: Metadata = {
title: "Apple Clients • Firezone Docs",
title: "iOS Client • Firezone Docs",
description: "Firezone Documentation",
};

4
website/src/app/kb/user-guides/linux-client/page.tsx
View File

@@ -3,8 +3,8 @@ import { Metadata } from "next";
import LastUpdated from "@/components/LastUpdated";
export const metadata: Metadata = {
title: "Linux Client • Firezone Docs",
description: "Firezone Documentation",
title: "Linux Headless Client • Firezone Docs",
description: "How to install and use the Firezone Linux headless client.",
};
export default function Page() {

251
website/src/app/kb/user-guides/linux-client/readme.mdx
View File

@@ -1,88 +1,82 @@
import Alert from "@/components/DocsAlert";
import SupportOptions from "@/components/SupportOptions";
# Linux Client
# Linux Headless Client
Firezone supports Linux with a native, headless client for ARMv7l, ARM64, and
x86-64 architectures.
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.
The Linux Client is a lightweight, standalone binary that runs in the background
using a service account token.
<Alert color="info">
If you're looking for a desktop Client that authenticates with your identity
provider instead, see the [Linux GUI
Client](/kb/user-guides/linux-gui-client).
</Alert>
## Prerequisites
- Any Linux-based OS with kernel 3.10 or higher
- ARM64, ARMv7l, or x86-64 CPU
- Administrator access to your Firezone account in order to create a Service
Account and generate a token
- ARM64, ARMv7l, or x86_64 CPU
- Administrator access to your Firezone account in order to create a service
account and generate a token
- Root access or `sudo` for Split DNS
## Installation
The Linux Client is currently in beta and can be downloaded from our
[main repository's releases page](https://github.com/firezone/firezone/releases).
Alternatively, download the latest Client binary using one of the links below:
Download the Linux headless Client from our
[releases page](https://github.com/firezone/firezone/releases), or use one of
the direct links below:
- [Download the Linux Client for `x86-64`](/dl/firezone-client-headless-linux/latest/x86_64)
- [Download the Linux Client for `x86_64`](/dl/firezone-client-headless-linux/latest/x86_64)
- [Download the Linux Client for `ARMv7l`](/dl/firezone-client-headless-linux/latest/armv7)
- [Download the Linux Client for `ARM64`](/dl/firezone-client-headless-linux/latest/aarch64)
## Usage
The Linux Client requires a Service Account token to authenticate to Firezone.
If you don't already have a token generated, follow the instructions in the
[Service Account](/kb/authenticate/service-accounts) documentation.
Once you have a token, you can start the Linux Client using the following
command:
Mark the binary as executable:
```bash
sudo FIREZONE_TOKEN=<TOKEN> ./headless-client-x64
chmod +x firezone-client-headless-linux_1.0.0_x86_64
```
## Usage
### Signing in
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 start the Client using the following command:
```bash
sudo FIREZONE_TOKEN=<TOKEN> ./firezone-client-headless-linux_1.0.0_x86_64
```
<Alert color="info">`sudo` is required to control the system's DNS.</Alert>
Set some environment variables to configure it:
```bash
export FIREZONE_NAME="Development Webserver"
export FIREZONE_ID="some unique identifier"
export FIREZONE_NAME="Development API test client"
export FIREZONE_ID=$(uuidgen)
export FIREZONE_TOKEN=<TOKEN>
export DNS_CONTROL="systemd-resolved" # or "etc-resolv-conf"
export FIREZONE_DNS_CONTROL="systemd-resolved" # or "etc-resolv-conf"
export LOG_DIR="./"
sudo -E ./headless-client-x64
sudo -E ./firezone-client-headless-linux_1.0.0_x86_64
```
See [below](#environment-variable-reference) for a full list of environment
variables.
A sample output of the help command is shown below:
### Accessing a Resource
```text
> sudo ./headless-client-x64 -h
Usage: headless-client [OPTIONS] [COMMAND]
Commands:
standalone Act as a CLI-only Client
help Print this message or the help of the given subcommand(s)
Options:
--token-path <TOKEN_PATH>
A filesystem path where the token can be found [env: FIREZONE_TOKEN_PATH=] [default: /etc/dev.firezone.client/token]
-i, --firezone-id <FIREZONE_ID>
Identifier used by the portal to identify and display the device [env: FIREZONE_ID=]
-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=]
-h, --help
Print help
-V, --version
Print version
```
When Firezone is signed in, HTTP clients, SQL clients, and other programs will
automatically use it to securely connect to Resources.
### Split DNS
By default, Split DNS is **disabled** for the Linux Client. This means that
access to DNS-based Resources won't be routed through Firezone.
By default, Split DNS is **disabled** for the Linux headless Client. This means
that access to DNS-based Resources won't be routed through Firezone.
To enable Split DNS for the Linux Client, set the `FIREZONE_DNS_CONTROL`
environment variable to `systemd-resolved` or `etc-resolv-conf`.
@@ -101,21 +95,24 @@ command:
systemctl status systemd-resolved
```
#### NetworkManager
In most cases, if you're using NetworkManager your system is likely already
using `systemd-resolved`, and you should set `FIREZONE_DNS_CONTROL` to
`systemd-resolved`. You'll need to ensure that `/etc/resolv.conf` is a symlink
to `/run/systemd/resolve/stub-resolv.conf`:
You'll need to ensure that `/etc/resolv.conf` is a symlink to
`/run/systemd/resolve/stub-resolv.conf`:
```bash
# Check if /etc/resolv.conf is already a symlink to /run/systemd/resolve/stub-resolv.conf
stat /etc/resolv.conf
# If it's not, create the symlink
sudo ln -sf /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf
sudo ln -sf /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf.new
sudo mv /etc/resolve.conf.new /etc/resolv.conf
```
#### NetworkManager
In most cases, if you're using NetworkManager your system is likely already
using `systemd-resolved`, and you should set `FIREZONE_DNS_CONTROL` to
`systemd-resolved`.
When NetworkManager detects that symlink exists, it will automatically use
`systemd-resolved` for DNS resolution and no other configuration is necessary.
@@ -138,23 +135,137 @@ sudo mv /etc/resolv.conf.before-firezone /etc/resolv.conf
### Environment variable reference
Here's an exhaustive list of environment variables you can use for the Linux
client.
| 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 identify this client for metadata and display purposes. |
| `FIREZONE_DNS_CONTROL` | (blank) | The DNS control method to use. Set this to `systemd-resolved` to use systemd-resolved for Split DNS, or `etc-resolv-conf` to use the `/etc/resolv.conf` file. If left blank, Split DNS will be **disabled**. |
| `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/). |
| 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 identify this client for metadata and display purposes. |
| `FIREZONE_DNS_CONTROL` | | The DNS control method to use. Set to `systemd-resolved` to use systemd-resolved for Split DNS, or `etc-resolv-conf` to use the `/etc/resolv.conf` file. If left blank, Split DNS will be **disabled**. |
| `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
### Upgrading
```text
> sudo ./firezone-client-headless-linux_1.0.0_x86_64 -h
Usage: firezone-headless-client [OPTIONS] [COMMAND]
Commands:
standalone
help Print this message or the help of the given subcommand(s)
Options:
--check
Check the configuration and return 0 before connecting to the API
--token-path <TOKEN_PATH>
A filesystem path where the token can be found [env: FIREZONE_TOKEN_PATH=] [default: /etc/dev.firezone.client/token]
--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=]
-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=]
-h, --help
Print help (see more with '--help')
-V, --version
Print version
```
## Upgrading
1. Stop the running Client.
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
Firezone writes log files to disk. These logs stay on your computer and are not
transmitted anywhere. If you encounter a bug, sending us the files may help us
fix the bug.
## Uninstalling
1. Stop the running Client
1. Delete the binary
## Troubleshooting
### Check if Firezone is controlling DNS with systemd-resolved DNS
```bash
resolvectl dns
```
Firezone Split DNS:
```text
Global:
Link 2 (enp0s6): 10.0.2.3 fec0::3
Link 3 (tun-firezone): 100.100.111.1 fd00:2021:1111:8000:100:100:111:0
```
Normal system DNS:
```text
Global:
Link 2 (enp0s6): 10.0.2.3 fec0::3
```
### Check if Firezone is controlling DNS with `/etc/resolv.conf`
Firezone Split DNS:
```text
# BEGIN Firezone DNS configuration
# If you modify this file, delete the above magic header line so that Firezone will
# obey your new default DNS config.
# If you see this text and Firezone is not running, then the last run of Firezone crashed.
# The original `resolv.conf` is backed up at /etc/resolv.conf.before-firezone
nameserver 100.100.111.1
search .
options edns0
options trust-ad
```
Normal system DNS:
```text
nameserver 192.168.1.1
```
### Check if Firezone is being used
Check if `curl` reports a remote IP in Firezone's range when you connect to a
resource:
```text
> curl --silent --output /dev/null --write-out %{remote_ip}\\n https://example.com
100.96.0.2
```
Firezone resources use the ranges `100.96.0.0/11` and
`fd00:2021:1111:8000::/107`.
### Revert `/etc/resolv.conf` DNS control
The `systemd-resolved` method reverts by itself when Firezone closes. However,
the `etc-resolv-conf` method can fail to revert if Firezone crashes.
Starting and stopping Firezone gracefully will cause it to try reverting
`/etc/resolv.conf`.
You can manually revert with:
```bash
sudo mv /etc/resolv.conf.before-firezone /etc/resolv.conf
```
## Known issues
None at time of writing.
<SupportOptions />

17
website/src/app/kb/user-guides/linux-gui-client/page.tsx Normal file
View File

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

174
website/src/app/kb/user-guides/linux-gui-client/readme.mdx Normal file
View File

@@ -0,0 +1,174 @@
import SupportOptions from "@/components/SupportOptions";
import Alert from "@/components/DocsAlert";
# Linux GUI Client
The Linux GUI Client is designed for Linux desktop environments 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 container-based
installs, see the [Linux headless Client](/kb/user-guides/linux-client) user
guide instead.
</Alert>
## Prerequisites
- Ubuntu **20.04** or **22.04**. Other distributions may work, but are not
officially supported.
- **x86-64** CPU architecture
- **systemd-resolved**. Ubuntu already uses this by default.
## Installation
Download the `.deb` package from our
[releases page](https://github.com/firezone/firezone/releases), or from the
direct link below:
- [Download the Linux GUI `.deb` for `x86-64`](/dl/firezone-client-gui-linux/latest/x86_64)
Run these commands:
```bash
# Install the package
# The leading `./` is needed so `apt-get` can tell this is a local file
sudo apt-get install ./firezone-client-gui-linux_<VERSION>_<ARCH>.deb
# Add yourself to the `firezone-client` group so you can use the tunnel service
sudo usermod -aG firezone-client "$USER"
# Reboot to finish adding yourself to the group
reboot
```
## Usage
### Signing in
1. Start the GUI by running `firezone-client-gui` from your desktop
environment's application menu or from an interactive shell.
1. At the Welcome screen, click `Sign in`. This will open the Firezone sign-in
page in your default web browser.
1. Sign in using your account slug and identity provider
1. On the first run, check `Always allow` to allow your web browser to sign in
to Firezone, then click `Open` or `Open link`
1. Unlock your desktop's keyring, or create one if needed. Most desktops,
including GNOME, encrypt the keyring with your login password, so your
Firezone token is encrypted at rest.
1. When you see the `Firezone connected` notification, the tunnel is ready.
The Welcome screen only appears during your first sign-in. After that, you can
click on the Firezone icon in the system tray to open the tray menu and sign in.
### Accessing a Resource
When Firezone is signed in, web browsers and other programs will automatically
use it to securely connect to Resources.
To copy-paste the address of a Resource you have access to:
1. Click on the Firezone tray icon to open the menu.
1. Open a Resource's submenu and click on its address to copy it.
### Quitting
When you quit the Firezone GUI, your token is still stored on the disk, so it
will sign in automatically next time you open the GUI.
### Signing out
1. Click on the Firezone tray icon to open the menu.
1. Click `Sign out`.
The tunnel is now stopped until you sign in again.
## Upgrading
1. Quit `firezone-client-gui` if it's running.
1. Install the new package:
`sudo apt-get install ./firezone-client-gui-linux_<VERSION>_<ARCH>.deb`
1. Restart `firezone-client-gui`.
## Diagnostic logs
Firezone writes log files to disk. These logs stay on your computer and are not
transmitted anywhere. If you encounter a bug, sending us a zip archive of your
logs may help us fix the bug.
To export your logs as a zip archive, or clear your log directory:
1. Click on the Firezone tray icon to open the menu.
1. Click `Settings`.
1. Click `Diagnostic Logs`.
## Uninstalling
1. Quit `firezone-client-gui` if it's running.
1. Remove the package: `sudo apt-get remove firezone-client-gui`
## Troubleshooting
### Check if `systemd-resolved` is enabled
```bash
systemctl status systemd-resolved
stat /etc/resolv.conf
```
`systemctl` should show that `systemd-resolved` is `enabled` and
`active (running)`.
`stat` should show that `resolv.conf` is a symlink to `stub-resolv.conf`:
`File: /etc/resolv.conf -> ../run/systemd/resolve/stub-resolv.conf`
If `systemd-resolved` is not running, or the symlink is not set up, Firezone may
not be able to start, or may not be able to access DNS resources.
### Check if Firezone is controlling DNS
```bash
resolvectl dns
```
Firezone Split DNS:
```text
Global:
Link 2 (enp0s6): 10.0.2.3 fec0::3
Link 3 (tun-firezone): 100.100.111.1 fd00:2021:1111:8000:100:100:111:0
```
Normal system DNS:
```text
Global:
Link 2 (enp0s6): 10.0.2.3 fec0::3
```
### Revert Firezone DNS control
The Firezone GUI Client for Linux uses `systemd-resolved` to control DNS, which
will automatically revert DNS to the system defaults when you quit the Firezone
GUI, which destroys the `tun-firezone` virtual network interface.
If the network interface stays up and DNS does not revert, you can try
restarting the tunnel service. Quit the Firezone GUI, then run:
```bash
sudo systemctl restart firezone-client-ipc
```
## Known issues
- Web browsers that use DNS-over-HTTPS by default may not work with Firezone.
See
[this guide](/kb/administer/troubleshooting#some-browsers-break-dns-routing)
to disable DNS-over-HTTPS if you're experiencing issues connecting to DNS
Resources within your browser.
- After clearing diagnostic logs, no more logs are written until the GUI and
tunnel service each restart.
[#4764](https://github.com/firezone/firezone/issues/4764)
- The GUI Client does not run on Ubuntu 24.04 yet
[#4883](https://github.com/firezone/firezone/issues/4883)
<SupportOptions />

2
website/src/app/kb/user-guides/macos-client/page.tsx
View File

@@ -3,7 +3,7 @@ import { Metadata } from "next";
import LastUpdated from "@/components/LastUpdated";
export const metadata: Metadata = {
title: "Apple Clients • Firezone Docs",
title: "macOS Client • Firezone Docs",
description: "Firezone Documentation",
};

42
website/src/app/kb/user-guides/readme.mdx
View File

@@ -11,31 +11,19 @@ Visit the appropriate page below for download instructions and more for your
platform.
<div class="mt-20 flex justify-between text-center space-x-5">
<div class="w-32">
<AppleIcon size={10} href="/kb/user-guides/macos-client">
<p>macOS</p>
</AppleIcon>
</div>
<div class="w-32">
<WindowsIcon size={10} href="/kb/user-guides/windows-client">
<p>Windows</p>
</WindowsIcon>
</div>
<div class="w-32">
<AndroidIcon size={10} href="/kb/user-guides/android-client">
<p>
Android &<br /> ChromeOS
</p>
</AndroidIcon>
</div>
<div class="w-32">
<AppleIcon size={10} href="/kb/user-guides/ios-client">
<p>iOS</p>
</AppleIcon>
</div>
<div class="w-32">
<LinuxIcon size={10} href="/kb/user-guides/linux-client">
<p>Linux</p>
</LinuxIcon>
</div>
<AppleIcon size={10} href="/kb/user-guides/macos-client">
<p>macOS</p>
</AppleIcon>
<WindowsIcon size={10} href="/kb/user-guides/windows-client">
<p>Windows</p>
</WindowsIcon>
<AndroidIcon size={10} href="/kb/user-guides/android-client">
<p>Android & ChromeOS</p>
</AndroidIcon>
<AppleIcon size={10} href="/kb/user-guides/ios-client">
<p>iOS</p>
</AppleIcon>
<LinuxIcon size={10} href="/kb/user-guides/linux-gui-client">
<p>Linux</p>
</LinuxIcon>
</div>

2
website/src/app/kb/user-guides/windows-client/page.tsx
View File

@@ -4,7 +4,7 @@ import LastUpdated from "@/components/LastUpdated";
export const metadata: Metadata = {
title: "Windows Client • Firezone Docs",
description: "Firezone Documentation",
description: "How to install and use the Firezone Windows client.",
};
export default function Page() {

156
website/src/app/kb/user-guides/windows-client/readme.mdx
View File

@@ -2,42 +2,160 @@ import SupportOptions from "@/components/SupportOptions";
# Windows Client
Firezone supports Microsoft Windows with a native client for the x86-64
architecture.
The Windows GUI Client is designed for Windows computers where a user is present
to authenticate with your identity provider interactively.
## Prerequisites
- Windows 10 or higher
- x86-64 CPU
- Windows **10** or higher
- **x86-64** CPU
- [**WebView2**](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)
(The installer will install this automatically if needed)
## Installation
The Windows Client is currently in beta and can be downloaded from the following
link:
Download the `.msi` installer from
[our releases page](https://github.com/firezone/firezone/releases) or from the
direct link below:
- [Download the MSI installer package](/dl/firezone-client-gui-windows/latest/x86_64)
- [Download the Windows `.msi` installer for `x86-64`](/dl/firezone-client-gui-windows/latest/x86_64)
After downloading, run the `.msi` to install the Firezone GUI Client.
## Usage
The Windows Client must be run as an administrator to function correctly. **Be
sure to click "Allow" when prompted by the User Account Control dialog.**
### Signing in
If that dialog does not appear, you may need to explicitly run Firezone as an
administrator. To do so, right-click the Firezone icon and select "Run as
administrator."
1. Run Firezone
1. At the Welcome screen, click `Sign in`. This will open the Firezone sign-in
page in your default web browser.
1. Sign in using your account slug and identity provider.
1. If your browser asks whether it should open Firezone links, check
`Always allow` and open the link.
1. When you see the "Firezone connected" notification, the tunnel is ready.
The Welcome screen only appears for your first sign-in. After that, you can use
the tray menu to sign in.
### Accessing a Resource
When Firezone is signed in, web browsers and other programs will automatically
use it to securely connect to Resources.
To copy-paste the address of a Resource you have access to:
1. Right-click on the Firezone tray icon to open the menu.
1. Open a Resource's submenu and click on its address to copy it.
Then you can paste the address into your browser's URL bar and press Enter.
### Signing out
1. Right-click on the Firezone tray icon to open the menu.
1. Click `Sign out`.
when you're signed out, Resources will be inaccessible and your system will use
its normal DNS and Internet behavior.
### Quitting
1. Right-click on the Firezone tray icon to open the menu.
1. Click `Disconnect and Quit` or `Quit`.
The tunnel is now stopped. If you were signed in, the tunnel will restart
automatically next time you open Firezone.
The tunnel is now stopped until you sign in again.
## Upgrading
The Windows Client will automatically check for updates on launch and prompt you
to upgrade when a new version is available. Simply download the latest MSI
installer package above and install it over the existing version.
to upgrade when a new version is available. Simply download the latest `.msi`
installer package above, quit the GUI, and install the new MSI over the existing
version.
## Diagnostic logs
Firezone writes log files to disk. These logs stay on your computer and are not
transmitted anywhere. If you encounter a bug, sending us a zip archive of your
logs may help us fix the bug.
To export your logs as a zip archive, or clear your log directory:
1. Right-click on the Firezone tray icon to open the menu.
1. Click "Settings".
1. Click "Diagnostic Logs".
## Uninstalling
1. Quit Firezone.
1. Open the Start Menu. Search for `Add or remove programs` and open it.
1. In the `Add or remove programs` dialog, search for `Firezone`.
1. Click on Firezone and click `Uninstall`.
## 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 }
```
1. Right-click on the Start Menu
1. Click "Terminal (Admin)" to open a Powershell terminal with admin privileges
1. When UAC asks "Do you want to allow this app to make changes to your device?"
click `Yes`
1. Enter the above command and
[Check if Firezone is controlling DNS](#check-if-firezone-is-controlling-dns)
## Known issues
Web browsers that enable DNS-over-HTTPS by default may interfere with DNS
resolution. See
[this guide](/kb/administer/troubleshooting#some-browsers-break-dns-routing) to
disable DNS-over-HTTPS if you're experiencing issues connecting to DNS Resources
within your browser.
- Web browsers that use DNS-over-HTTPS by default may not work with Firezone.
See
[this guide](/kb/administer/troubleshooting#some-browsers-break-dns-routing)
to disable DNS-over-HTTPS if you're experiencing issues connecting to DNS
Resources within your browser.
- Firezone does not register itself with Windows as a VPN
[#2875](https://github.com/firezone/firezone/issues/2875)
- After clearing diagnostic logs, no more logs are written until the GUI and
tunnel service each restart.
[#4764](https://github.com/firezone/firezone/issues/4764)
- In rare cases, Firezone gets stuck signing in
[#4765](https://github.com/firezone/firezone/issues/4765)
<SupportOptions />

2
website/src/components/Footer/index.tsx
View File

@@ -211,7 +211,7 @@ export default function Footer() {
<div className="flex p-2 items-center justify-center space-x-5">
<AppleIcon size={5} href="/kb/user-guides/macos-client" />
<WindowsIcon size={5} href="/kb/user-guides/windows-client" />
<LinuxIcon size={5} href="/kb/user-guides/linux-client" />
<LinuxIcon size={5} href="/kb/user-guides/linux-gui-client" />
<AndroidIcon size={5} href="/kb/user-guides/android-client" />
</div>
<div className="flex p-2 items-center justify-center sm:justify-end space-x-5">

7
website/src/components/KbSidebar/index.tsx
View File

@@ -174,7 +174,12 @@ export default function KbSidebar() {
</li>
<li>
<Item nested href="/kb/user-guides/linux-client">
Linux
Linux headless
</Item>
</li>
<li>
<Item nested href="/kb/user-guides/linux-gui-client">
Linux GUI
</Item>
</li>
</Collapse>