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

fix(docs): Add DNS docs for Linux (#3810)

Browse Source 
Signed-off-by: Jamil <jamilbk@users.noreply.github.com>
Signed-off-by: Reactor Scram <ReactorScram@users.noreply.github.com>
Co-authored-by: Reactor Scram <ReactorScram@users.noreply.github.com>
This commit is contained in:
Jamil
2024-02-29 13:12:24 -08:00
committed by GitHub
parent 3c04025be1
commit 6d32e30133
6 changed files with 105 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
elixir/apps/web/lib/web/live/sites/new_token.ex
View File

@@ -78,6 +78,13 @@ defmodule Web.Sites.NewToken do
class="w-full text-xs whitespace-pre-line"
phx-no-format
><%= systemd_command(@env) %></.code_block>
<p class="p-4">
<strong>Important:</strong>
You'll need to make sure that the <code>iptables</code>
and <code>ip6tables</code>
commands are available on your system.
</p>
</:tab>
<:tab
id="docker-instructions"

2
rust/linux-client/src/main.rs
View File

@@ -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,

2
website/src/app/kb/administer/logs/readme.mdx
View File

@@ -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

1
website/src/app/kb/deploy/gateways/readme.mdx
View File

@@ -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)

18
website/src/app/kb/deploy/resources/readme.mdx
View File

@@ -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).
<Alert color="warning">
**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.
</Alert>
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).
<NextStep href="/kb/deploy/groups">Next: Create Groups</NextStep>
<SupportOptions />

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

@@ -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 <TOKEN>
```
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 <TOKEN>
```
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.
<Alert color="warning">
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.
</Alert>
[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` | `<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/). |