diff --git a/elixir/apps/web/lib/web/live/sites/new_token.ex b/elixir/apps/web/lib/web/live/sites/new_token.ex index 2f51b8eca..fa74cc354 100644 --- a/elixir/apps/web/lib/web/live/sites/new_token.ex +++ b/elixir/apps/web/lib/web/live/sites/new_token.ex @@ -78,6 +78,13 @@ defmodule Web.Sites.NewToken do class="w-full text-xs whitespace-pre-line" phx-no-format ><%= systemd_command(@env) %> + +

+ Important: + You'll need to make sure that the iptables + and ip6tables + commands are available on your system. +

<:tab id="docker-instructions" diff --git a/rust/linux-client/src/main.rs b/rust/linux-client/src/main.rs index 6ba41b328..6f58c4613 100644 --- a/rust/linux-client/src/main.rs +++ b/rust/linux-client/src/main.rs @@ -144,7 +144,7 @@ struct Cli { #[command(flatten)] common: CommonArgs, - /// Identifier generated by the portal to identify and display the device. + /// Identifier used by the portal to identify and display the device. #[arg(short = 'i', long, env = "FIREZONE_ID")] pub firezone_id: String, diff --git a/website/src/app/kb/administer/logs/readme.mdx b/website/src/app/kb/administer/logs/readme.mdx index 635c2039d..9d334361d 100644 --- a/website/src/app/kb/administer/logs/readme.mdx +++ b/website/src/app/kb/administer/logs/readme.mdx @@ -15,7 +15,7 @@ Below is a table listing the various log directories used by each component. | 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 | -| Windows Client | `%APPDATA%\Firezone\logs` | +| Windows Client | `%APPDATA%\Local\dev.firezone.client\data\logs` | | Gateway | Logs are written to STDOUT by default | ## Exporting logs diff --git a/website/src/app/kb/deploy/gateways/readme.mdx b/website/src/app/kb/deploy/gateways/readme.mdx index ecd9d555d..47b1e1334 100644 --- a/website/src/app/kb/deploy/gateways/readme.mdx +++ b/website/src/app/kb/deploy/gateways/readme.mdx @@ -15,6 +15,7 @@ responsible for securely routing traffic between Clients and Resources. ## Prerequisites +- `iptables` and/or `ip6tables` - Any Linux distribution with kernel 3.10 or later - Docker Engine (for docker-based installs) - Systemd (for systemd-based installs) diff --git a/website/src/app/kb/deploy/resources/readme.mdx b/website/src/app/kb/deploy/resources/readme.mdx index 9eeda090f..23ffca5ee 100644 --- a/website/src/app/kb/deploy/resources/readme.mdx +++ b/website/src/app/kb/deploy/resources/readme.mdx @@ -23,26 +23,26 @@ From there, you can select the type of Resource you want to create: - **DNS**: A domain name pattern to match. - By default, the pattern will only match exactly the name you enter. - To recursively match all subdomains, use a wildcard, such as - `*.example.com`. This will match `sub2.example.com`, - `sub1.sub2.example.com`, + `*.example.com`. This will match `example.com`, `sub2.example.com`, and + `sub1.sub2.example.com`. - To non-recursively match all subdomains, use a question mark, such as - `?.example.com`. This will match `sub1.example.com` and `sub2.example.com` - but _not_ `sub1.sub2.example.com`. + `?.example.com`. This will match `example.com`, `sub1.example.com`, and + `sub2.example.com` _but not_ `sub1.sub2.example.com`. - **IP**: A single IPv4 or IPv6 address - **CIDR**: A range of IPv4 or IPv6 addresses in CIDR notation, such as `10.1.2.0/24` or `2001:db8::/48` -Firezone does not currently filter traffic based on any layer 4 details such as -transport protocol (UDP / TCP) or port number. If you're interested in a feature -like this, -[please leave a comment on our public roadmap](https://github.com/firezone/firezone/issues/2030). - **Note:** To preserve audit trails, once a Resource is created, its address cannot be changed. Double-check to ensure the address entered is correct before creating the Resource. +Firezone does not currently filter traffic based on any layer 4 details such as +transport protocol (UDP / TCP) or port number. If you're interested in a feature +like this, +[leave a comment on our public roadmap](https://github.com/firezone/firezone/issues/2030). + Next: Create Groups 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 554c7176d..4b929e40e 100644 --- a/website/src/app/kb/user-guides/linux-client/readme.mdx +++ b/website/src/app/kb/user-guides/linux-client/readme.mdx @@ -1,7 +1,9 @@ +import Alert from "@/components/DocsAlert"; + # Linux Client -Firezone supports Linux with a native client for ARM v7, ARM64, and Intel x64 -architectures. +Firezone supports Linux with a native, headless client for ARMv7l, ARM64, and +x86-64 architectures. The Linux Client is a lightweight, standalone binary that runs in the background using a service account token. @@ -9,7 +11,7 @@ using a service account token. ## Prerequisites - Any Linux-based OS with kernel 3.10 or higher -- ARM64, ARMv7, or Intel x64 CPU +- ARM64, ARMv7l, or x86-64 CPU - Administrator access to your Firezone account in order to create a Service Account and generate a token @@ -19,9 +21,9 @@ 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 Client for `x86_64`](https://github.com/firezone/firezone/releases/latest/download/linux-client-x64) -- [Download the Linux Client for `armv7l`](https://github.com/firezone/firezone/releases/latest/download/linux-client-arm) -- [Download the Linux Client for `arm64`](https://github.com/firezone/firezone/releases/latest/download/linux-client-arm64) +- [Download the Linux Client for `x86-64`](https://github.com/firezone/firezone/releases/latest/download/linux-client-x64) +- [Download the Linux Client for `ARMv7l`](https://github.com/firezone/firezone/releases/latest/download/linux-client-arm) +- [Download the Linux Client for `ARM64`](https://github.com/firezone/firezone/releases/latest/download/linux-client-arm64) ## Running the Linux Client @@ -36,6 +38,19 @@ command: sudo ./linux-client-x64 ``` +Set some environment variables to configure it: + +```bash +FIREZONE_NAME="Development Webserver" +FIREZONE_ID="some unique identifier" +DNS_CONTROL="systemd-resolved" # or "etc-resolv-conf" +LOG_DIR="./" +sudo -E ./linux-client-x64 +``` + +See [below](#environment-variable-reference) for a full list of environment +variables. + A sample output of the help command is shown below: ```text @@ -54,3 +69,68 @@ Options: -h, --help Print help -V, --version Print version ``` + +## Split DNS + +The Linux Client supports Split DNS, which you can enable by setting the +`FIREZONE_DNS_CONTROL` environment variable to `systemd-resolved` or +`etc-resolv-conf`. If you don't set this variable, Split DNS will be disabled. + +When Split DNS is enabled, the Linux Client will override the system's DNS +resolver with its internal proxy. To do this, the Linux client needs to know how +DNS resolution is currently being handled on your system. + +### systemd-resolved + +On most modern Linux distributions, DNS resolution is handled by +`systemd-resolved`. If this is the case for you, set `FIREZONE_DNS_CONTROL` to +`systemd-resolved`. If you're not sure, you can check by running the following +command: + +```bash +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`: + +```bash +stat /etc/resolv.conf +sudo ln -sf /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf +``` + +When NetworkManager detects that symlink exists, it will automatically use +`systemd-resolved` for DNS resolution. + +### /etc/resolv.conf + +If you're not using `systemd-resolved`, Firezone supports using the +`/etc/resolv.conf` file to configure Split DNS as a fallback. To do this, set +`FIREZONE_DNS_CONTROL` to `etc-resolv-conf`, and the Linux Client will override +the `/etc/resolv.conf` file with the Firezone internal proxy. + + + The Linux Client **will not revert** `/etc/resolv.conf` when it exits, so this + is best for disposable "cattle" systems like Docker containers or VMs that can + be rebuilt from scripts. + + +[Read more](/kb/deploy/dns) about how DNS works in Firezone. + +## 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` | | 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/). |