diff --git a/rust/gui-client/docs/intended_behavior.md b/rust/gui-client/docs/intended_behavior.md index b9375bb94..1109656d4 100644 --- a/rust/gui-client/docs/intended_behavior.md +++ b/rust/gui-client/docs/intended_behavior.md @@ -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 diff --git a/rust/gui-client/src-tauri/src/client.rs b/rust/gui-client/src-tauri/src/client.rs index 29b56411c..1414f4e01 100644 --- a/rust/gui-client/src-tauri/src/client.rs +++ b/rust/gui-client/src-tauri/src/client.rs @@ -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(), }; diff --git a/rust/headless-client/src/lib.rs b/rust/headless-client/src/lib.rs index 7264f27c5..ea64a0b84 100644 --- a/rust/headless-client/src/lib.rs +++ b/rust/headless-client/src/lib.rs @@ -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, + /// 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(), )?; diff --git a/scripts/firezone-client-gui-install.sh b/scripts/firezone-client-gui-install.sh index 9f1282513..bd73445ee 100755 --- a/scripts/firezone-client-gui-install.sh +++ b/scripts/firezone-client-gui-install.sh @@ -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 diff --git a/website/next.config.mjs b/website/next.config.mjs index 5d468aa82..6fc3ec7ab 100644 --- a/website/next.config.mjs +++ b/website/next.config.mjs @@ -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} */ diff --git a/website/pnpm-lock.yaml b/website/pnpm-lock.yaml index f65977f01..ca1d96343 100644 --- a/website/pnpm-lock.yaml +++ b/website/pnpm-lock.yaml @@ -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: diff --git a/website/redirects.js b/website/redirects.js index 0258c5267..9a1f5ee5e 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -3,7 +3,7 @@ module.exports = [ /* * - * Windows Client + * Windows GUI Client * */ // latest @@ -23,7 +23,7 @@ module.exports = [ }, /* * - * Linux Client + * Linux Clients * */ // latest diff --git a/website/src/app/kb/user-guides/android-client/page.tsx b/website/src/app/kb/user-guides/android-client/page.tsx index b3fc52be1..cd744804a 100644 --- a/website/src/app/kb/user-guides/android-client/page.tsx +++ b/website/src/app/kb/user-guides/android-client/page.tsx @@ -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", }; diff --git a/website/src/app/kb/user-guides/ios-client/page.tsx b/website/src/app/kb/user-guides/ios-client/page.tsx index b2671eef7..a7458b811 100644 --- a/website/src/app/kb/user-guides/ios-client/page.tsx +++ b/website/src/app/kb/user-guides/ios-client/page.tsx @@ -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", }; diff --git a/website/src/app/kb/user-guides/linux-client/page.tsx b/website/src/app/kb/user-guides/linux-client/page.tsx index 46e39c111..22b256efb 100644 --- a/website/src/app/kb/user-guides/linux-client/page.tsx +++ b/website/src/app/kb/user-guides/linux-client/page.tsx @@ -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() { diff --git a/website/src/app/kb/user-guides/linux-client/readme.mdx b/website/src/app/kb/user-guides/linux-client/readme.mdx index 42580d519..54d51b4db 100644 --- a/website/src/app/kb/user-guides/linux-client/readme.mdx +++ b/website/src/app/kb/user-guides/linux-client/readme.mdx @@ -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. + + 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). + ## 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= ./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= ./firezone-client-headless-linux_1.0.0_x86_64 +``` + +`sudo` is required to control the system's DNS. + 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= -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 - A filesystem path where the token can be found [env: FIREZONE_TOKEN_PATH=] [default: /etc/dev.firezone.client/token] - -i, --firezone-id - Identifier used by the portal to identify and display the device [env: FIREZONE_ID=] - -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=] - -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` | `` | 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` | `` | 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 + A filesystem path where the token can be found [env: FIREZONE_TOKEN_PATH=] [default: /etc/dev.firezone.client/token] + --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=] + -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=] + -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. + diff --git a/website/src/app/kb/user-guides/linux-gui-client/page.tsx b/website/src/app/kb/user-guides/linux-gui-client/page.tsx new file mode 100644 index 000000000..b9c987960 --- /dev/null +++ b/website/src/app/kb/user-guides/linux-gui-client/page.tsx @@ -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 ( + <> + + + + ); +} diff --git a/website/src/app/kb/user-guides/linux-gui-client/readme.mdx b/website/src/app/kb/user-guides/linux-gui-client/readme.mdx new file mode 100644 index 000000000..9ff7e5dca --- /dev/null +++ b/website/src/app/kb/user-guides/linux-gui-client/readme.mdx @@ -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. + + + 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. + + +## 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__.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__.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) + + diff --git a/website/src/app/kb/user-guides/macos-client/page.tsx b/website/src/app/kb/user-guides/macos-client/page.tsx index b2671eef7..4c83fc192 100644 --- a/website/src/app/kb/user-guides/macos-client/page.tsx +++ b/website/src/app/kb/user-guides/macos-client/page.tsx @@ -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", }; diff --git a/website/src/app/kb/user-guides/readme.mdx b/website/src/app/kb/user-guides/readme.mdx index 203a650fe..24e59a7ed 100644 --- a/website/src/app/kb/user-guides/readme.mdx +++ b/website/src/app/kb/user-guides/readme.mdx @@ -11,31 +11,19 @@ Visit the appropriate page below for download instructions and more for your platform.
-
- -

macOS

- -
-
- -

Windows

- -
-
- -

- Android &
ChromeOS -

- -
-
- -

iOS

- -
-
- -

Linux

- -
+ +

macOS

+ + +

Windows

+ + +

Android & ChromeOS

+ + +

iOS

+ + +

Linux

+
diff --git a/website/src/app/kb/user-guides/windows-client/page.tsx b/website/src/app/kb/user-guides/windows-client/page.tsx index 50df674c1..bd976581a 100644 --- a/website/src/app/kb/user-guides/windows-client/page.tsx +++ b/website/src/app/kb/user-guides/windows-client/page.tsx @@ -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() { diff --git a/website/src/app/kb/user-guides/windows-client/readme.mdx b/website/src/app/kb/user-guides/windows-client/readme.mdx index c326ef42e..61a3eb2bf 100644 --- a/website/src/app/kb/user-guides/windows-client/readme.mdx +++ b/website/src/app/kb/user-guides/windows-client/readme.mdx @@ -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) diff --git a/website/src/components/Footer/index.tsx b/website/src/components/Footer/index.tsx index c6046834b..178f84b5e 100644 --- a/website/src/components/Footer/index.tsx +++ b/website/src/components/Footer/index.tsx @@ -211,7 +211,7 @@ export default function Footer() {
- +
diff --git a/website/src/components/KbSidebar/index.tsx b/website/src/components/KbSidebar/index.tsx index 5e15b64df..2d8485448 100644 --- a/website/src/components/KbSidebar/index.tsx +++ b/website/src/components/KbSidebar/index.tsx @@ -174,7 +174,12 @@ export default function KbSidebar() {
  • - Linux + Linux headless + +
    • +
  • + + Linux GUI