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

refactor(docs): Docs polish iteration, add DoH known issue (#4579)

Browse Source 
Fixes #4310

---------

Signed-off-by: Jamil <jamilbk@users.noreply.github.com>
Co-authored-by: Brian Manifold <bmanifold@users.noreply.github.com>
This commit is contained in:
Jamil
2024-04-10 18:31:26 -07:00
committed by GitHub
parent 8f3c8160db
commit 027db64322
30 changed files with 299 additions and 179 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
elixir/apps/web/lib/web/mailer/auth_email/new_user.html.heex
View File

@@ -89,8 +89,13 @@
To start accessing your resources, simply install one of the Firezone clients:
<ul>
<li>
<a href="https://www.firezone.dev/kb/user-guides/apple-client?utm_source=email">
Apple Client (macOS/iOS)
<a href="https://www.firezone.dev/kb/user-guides/macos-client?utm_source=email">
macOS Client
</a>
</li>
<li>
<a href="https://www.firezone.dev/kb/user-guides/ios-client?utm_source=email">
iOS Client
</a>
</li>
<li>

3
elixir/apps/web/lib/web/mailer/auth_email/new_user.text.heex
View File

@@ -6,7 +6,8 @@ Welcome to Firezone!
To get started accessing your resources, you will need to install one of the Firezone clients:
https://www.firezone.dev/kb/user-guides/apple-client
https://www.firezone.dev/kb/user-guides/macos-client
https://www.firezone.dev/kb/user-guides/ios-client
https://www.firezone.dev/kb/user-guides/windows-client
https://www.firezone.dev/kb/user-guides/android-client
https://www.firezone.dev/kb/user-guides/linux-client

BIN
website/public/images/kb/administer/troubleshooting/chrome_doh_disable.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 163 KiB

BIN
website/public/images/kb/administer/troubleshooting/ff_doh_disable.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 197 KiB

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

@@ -1,30 +1,34 @@
# Diagnostic logs
# Viewing logs
Firezone maintains diagnostic log files in various locations depending on the
component and operating system. Logs are scrubbed for sensitive and
personally-identifiable information before being written to disk.
Diagnostic logs are used primarily by the Firezone team for troubleshooting
connectivity and other issues.
connectivity and other issues, but they may also be useful for diagnosing issues
by advanced users and admins.
Below is a table listing the various log directories used by each component.
## Log directory locations
| Component | Log directory |
| ----------------------- | --------------------------------------------------------------------------------------- |
| macOS Client | `~/Library/Group Containers/47R2M6779T.group.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 |
| Windows Client | `%APPDATA%\Local\dev.firezone.client\data\logs` |
| Gateway | Logs are written to STDOUT by default |
| Component | Log directory |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| macOS Client | `~/Library/Group Containers/47R2M6779T.group.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` |
## Exporting logs
Log files can be conveniently exported from the macOS, iOS, Android/ChromeOS,
and Windows Clients from the in-app Settings screen.
and Windows Clients from the "Diagnostic Logs" tab of the Settings screen. This
will bundle the logs from the log directory listed above into an archive file
that can be easily shared.
## Clearing logs
Simply delete the files in the log directories listed above. For macOS, iOS,
Android/ChromeOS, and Windows Clients, log directies can be cleared in the
"Advanced" portion of the in-app Settings screen.
Simply delete the files in the log directories listed above.
For macOS, iOS, Android/ChromeOS, and Windows Clients, log directories can be
cleared in the "Diagnostic Logs" tab in the Settings screen.

6
website/src/app/kb/administer/troubleshooting/_page.tsx Normal file
View File

@@ -0,0 +1,6 @@
"use client";
import Content from "./readme.mdx";
export default function _Page() {
return <Content />;
}

4
website/src/app/kb/administer/troubleshooting/page.tsx
View File

@@ -1,4 +1,4 @@
import Content from "./readme.mdx";
import _Page from "./_page";
import { Metadata } from "next";
export const metadata: Metadata = {
@@ -7,5 +7,5 @@ export const metadata: Metadata = {
};
export default function Page() {
return <Content />;
return <_Page />;
}

37
website/src/app/kb/administer/troubleshooting/readme.mdx
View File

@@ -1,5 +1,6 @@
import SupportOptions from "@/components/SupportOptions";
import { TabsGroup, TabsItem } from "@/components/DocsTabs";
import Image from "next/image";
# Troubleshooting Guide
@@ -44,4 +45,40 @@ sudo journalctl -u firezone-gateway.service
</TabsItem>
</TabsGroup>
## Some browsers break DNS routing
Some web browsers enable DNS-over-HTTPS by default, which can interfere with
Firezone's DNS-based routing system. If you're experiencing issues connecting to
DNS Resources in your browser, or notice that DNS resources aren't being routed
through a Firezone Gateway when they should be, try disabling DNS-over-HTTPS
using the appropriate method below.
### Firefox
1. Go to `about:preferences#privacy` in the address bar.
1. Scroll down to the "DNS over HTTPS" section.
1. Ensure that "Off" is selected.
<Image
src="/images/kb/administer/troubleshooting/ff_doh_disable.png"
alt="Firefox DNS-over-HTTPS settings"
className="mx-auto shadow rounded"
width={500}
height={500}
/>
### Chrome
1. Go to `chrome://settings/security` in the address bar.
1. Scroll down to the "Advanced" section.
1. Ensure that "Use secure DNS" is disabled.
<Image
src="/images/kb/administer/troubleshooting/chrome_doh_disable.png"
alt="Firefox DNS-over-HTTPS settings"
className="mx-auto shadow rounded"
width={500}
height={500}
/>
<SupportOptions />

82
website/src/app/kb/administer/upgrading/readme.mdx
View File

@@ -1,65 +1,47 @@
import { HiCheck } from "react-icons/hi2";
import Link from "next/link";
import { TabsItem, TabsGroup } from "@/components/DocsTabs";
import Image from "next/image";
import Alert from "@/components/DocsAlert";
# Upgrading Firezone
# Upgrading Gateways
Upgrading Firezone consists of upgrading the Clients and Gateways. Read more
below to understand how our versioning system works, how you can auto-update
these components, and suggestions for an upgrade strategy in high-availability
deployments.
Firezone Gateways are designed to be easily upgraded with little or no planned
downtime for your organization. This guide will walk you through the steps to
upgrade your Gateway for both Docker and systemd deployments.
## How versioning works in Firezone
<Alert color="info">
This guide covers Gateway upgrades only. For details on upgrading Clients,
refer to the appropriate [user guide](/kb/user-guides) for your platform.
</Alert>
Firezone uses a semantic version scheme in the following format:
`MAJOR`.`MINOR`.`PATCH`
Firezone is changing rapidly, so we currently recommend staying as up-to-date as
possible to make sure you have the latest bug fixes and performance improvements
in place.
All components currently have a major version of `1` -- this is not expected to
change for some time.
## Client application auto-updates
In general we recommend keeping Clients and Gateways as up-to-date as possible.
See below for auto-update details for each platform.
<TabsGroup>
<TabsItem title="macOS" active>
Enable auto-updates in Settings.app.
</TabsItem>
<TabsItem title="iOS">Enable auto-updates in Settings.app.</TabsItem>
<TabsItem title="Android">Enable app auto-updates in Settings.</TabsItem>
<TabsItem title="ChromeOS">Enable app auto-updates in Settings.</TabsItem>
<TabsItem title="Windows">
A UI alert is shown upon launch if the Windows Client has an update
available.
</TabsItem>
<TabsItem title="Linux">
Auto-updates depend on your package manager configuration and deployment
method.
</TabsItem>
</TabsGroup>
## Upgrading Gateways
## Upgrade process
Upgrading a Gateway generally consists of simply replacing the binary or Docker
image and then restarting. See below for specific steps depending on how you've
deployed your Gateway:
image with the newer version and then restarting. See below for specific steps
depending on how you've deployed your Gateway:
<TabsGroup>
<TabsItem title="Docker" active>
Run the following upgrade script which pulls the latest image, stops the running
Gateway, and then restarts it using the newer image with the same configuration.
Copy-paste the following command to upgrade your Docker-based Gateway:
```bash
curl -s https://raw.githubusercontent.com/firezone/firezone/main/scripts/gateway-docker-upgrade.sh | bash
curl -fsSL \
https://raw.githubusercontent.com/firezone/firezone/main/scripts/gateway-docker-upgrade.sh \
| bash
```
{(<div className="flex justify-end">
<Link
className="text-sm"
href="https://github.com/firezone/firezone/blob/main/scripts/gateway-docker-upgrade.sh"
>
View script source
</Link>
</div>)}
### Verification
After running the upgrade, you can verify the Gateway is running the latest
@@ -101,10 +83,8 @@ sudo systemctl restart firezone-gateway
Gateways deployed within the same Site will automatically
[failover](/kb/deploy/gateways#failover) for each other. By upgrading Gateways
one-by-one, Clients connected to the Gateway being upgraded will automatically
reconnect to an available Gateway.
one-by-one in a rolling update strategy, Clients connected to the Gateway being
upgraded will automatically reconnect to an available Gateway.
Upgrades should be performed during a scheduled maintenance window to ensure
minimal disruption. Other than a possible short-term connection interruption to
in-use Resources, users won't otherwise be impacted by upgrading Gateways within
the same Site.
Users may notice very brief interruptions to Resources for a few seconds as
their Client reconnects to a healthy Gateway.

12
website/src/app/kb/deploy/clients/readme.mdx
View File

@@ -28,12 +28,12 @@ below. If you find an exception, please
[open a GitHub issue](https://www.github.com/firezone/firezone/issues/new/choose)
so we can prioritize appropriately.
| Platform | Distribution Method |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Android / ChromeOS | The Android / ChromeOS client is available exclusively from the Google Play Store. |
| Linux | The Linux client is available as a standalone statically-linked binary from our [releases page](https://www.github.com/firezone/firezone/releases). |
| macOS / iOS | The macOS and iOS clients are available exclusively from the Apple App Store. |
| Windows | The Windows client is available as a standalone MSI installer from our [releases page](https://www.github.com/firezone/firezone/releases). |
| Platform | Distribution Method |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Android / ChromeOS | The Android / ChromeOS client is available exclusively from the [Google Play Store](https://play.google.com/store/apps/details?id=dev.firezone.android). |
| Linux | The Linux client is available as a self-contained, statically-linked binary from our [releases page](https://www.github.com/firezone/firezone/releases). |
| macOS / iOS | The macOS and iOS clients are available exclusively from the [Apple App Store](https://apps.apple.com/us/app/firezone/id6443661826). |
| Windows | The Windows client is available as a standalone MSI installer from our [releases page](https://www.github.com/firezone/firezone/releases). |
## Headless mode operation

38
website/src/app/kb/deploy/dns/readme.mdx
View File

@@ -18,11 +18,6 @@ Read more below to understand how it works and how to configure it.
Each Firezone Client embeds a lightweight DNS proxy used to route queries to an
appropriate Gateway for resolution.
The proxy "listens on" IP addresses in the following ranges:
- IPv4: `100.100.111.0/24`
- IPv6: `fd00:2021:1111:8000::100:100:111:0/120`
When a user signs in, the Client configures the host operating system to use
this proxy as the default resolver for all queries on the system.
@@ -30,23 +25,30 @@ This is why you'll commonly see `100.100.111.1` or
`fd00:2021:1111:8000::100:100:111:0` as the DNS server responding to DNS queries
when the Firezone Client is signed in.
### Routing DNS queries
### How queries are resolved
When the proxy sees a query, it checks to see if it matches a Resource the user
has access to. If it does, the proxy then finds an appropriate Gateway
associated with the Resource, forwards the query to be resolved on the Gateway,
then returns the result back to the Client to be returned to the application
making the query.
When the proxy sees a DNS query for a Resource, it asks the portal for a healthy
Gateway to handle the query. The Gateway resolves the query using its system
resolver and sends the result back to the proxy, which generates a mapped IP to
the Resource's actual IP address. The final mapped IP is then returned to the
application making the query.
<Alert color="info">
DNS queries forwarded to Gateways benefit from the same NAT holepunching
mechanism as any other traffic. No firewall configuration is required to
achieve Split DNS with Firezone.
</Alert>
For example, if `github.com` was added as a Resource, an `nslookup` might return
`100.96.0.1` as its IPv4 address:
```
> nslookup github.com
Server: 100.100.111.1
Address: 100.100.111.1#53
Non-authoritative answer:
Name: github.com
Address: 100.96.0.1
```
If the query doesn't match a Resource, the proxy forwards the query to one of
the [upstream resolvers](#configuring-client-dns-upstream-resolvers) explained
further below.
the [upstream resolvers](#configuring-client-dns-upstream-resolvers) if
configured.
## Configuring Client DNS upstream resolvers

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

@@ -15,20 +15,21 @@ 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)
- `x86_64`, `aarch64`, or `armv7l` CPU architecture
- `iptables` and `ip6tables` commands available on your system
- [Docker Engine](https://docs.docker.com/engine/) or
[systemd](https://systemd.io/) installed for your distribution
### Firewall considerations
### Firewall ports
Gateways implement the industry-standard
[STUN](https://datatracker.ietf.org/doc/html/rfc8489) and
[TURN](https://www.rfc-editor.org/rfc/rfc8155.html) protocols to securely
perform NAT holepunching. No ingress firewall ports are required for Gateways to
function.
[TURN](https://www.rfc-editor.org/rfc/rfc8155.html) protocols to perform secure
NAT holepunching. **No inbound firewall ports need to be opened for Gateways to
function**.
If the network in which your Gateway is deployed performs egress filtering,
If the network in which your Gateway is deployed applies egress filtering,
you'll need to make sure the following outbound traffic is allowed:
| Host | (IP Address) | Port(s) | Protocol(s) | Purpose |
@@ -42,16 +43,15 @@ you'll need to make sure the following outbound traffic is allowed:
### Where to deploy Gateways
Ideally, Gateways should be deployed as close to the Resources they're serving
-- in some cases, even on the same physical host. This ensures the lowest
possible latency and highest possible throughput for Client connections, and
allows you to more easily deploy additional Gateways for a particular Resource
that needs to handle more Client connections.
-- in some cases, even on the same host. This ensures the lowest possible
latency and highest possible throughput for Client connections, and allows you
to more easily deploy additional Gateways for other Resources that need to
handle more Client connections.
The downside of deploying Gateways close to Resources is that it increases the
number of overall Gateways you need to deploy, possibly making it more difficult
to manage and monitor them. Firezone's control plane is designed to make this as
easy as possible, but it's still something to keep in mind when planning your
deployment.
overall number of Gateways and Sites you need to manage. Firezone's control
plane is designed to make this as easy as possible, but it's still something to
keep in mind when planning your deployment.
<Alert color="warning">
When deploying Gateways, remember that all Gateways and Resources in a Site
@@ -85,54 +85,54 @@ deployment.
{/* Firezone's [automatic load balancing](#load-balancing) to distribute Client */}
{/* connections across them. */}
## Deploy a single Gateway
### Deploy a single Gateway
Deploying a single Gateway can be accomplished in the admin portal.
Go to `Sites` -> `<name of Site>` -> `Deploy a Gateway` and follow the prompts
to deploy for your preferred environment. This will deploy a single Gateway.
See the [upgrading guide](/kb/administer/upgrading) for information on keeping
your Gateway up-to-date.
## Deploy multiple Gateways
### Deploy multiple Gateways
To achieve [high availability](#high-availability), deploy more Gateways within
the same site.
the same Site.
You can deploy multiple Gateways from the admin portal, or automate the process
by reusing the `FIREZONE_TOKEN` environment variable shown when deploying a
Gateway from the admin portal.
You can deploy multiple Gateways within a Site manually from the admin portal,
or automate the process by reusing the `FIREZONE_TOKEN` environment variable
shown when deploying a Gateway from the admin portal.
When deploying a Gateway from the admin portal, a `FIREZONE_TOKEN` environment
variable is shown. This variable can be reused to deploy multiple Gateways
within the same Site.
This means you can automate deployment of the Gateway using your automation
method of choice, adding as many Gateways as necessary for failover and load
balancing.
variable is shown. This is a multi-owner token that can be reused to deploy
multiple Gateways within the same Site.
<Alert color="warning">
**Note:** Be sure to set a unique `FIREZONE_ID` for each Gateway you deploy.
This can be any non-empty string and is used to identify the Gateway in the
portal for audit trail and logging purposes.
This can be any non-empty string and is used to identify Gateways in the
portal. This is generated automatically for you when deploying Gateways from
the portal.
</Alert>
### Deploy using Terraform
See our
[Terraform examples](https://github.com/firezone/firezone/tree/main/terraform/examples)
for deploying and scaling Gateways on Google Cloud Platform.
for deploying and scaling Gateways using Terraform on various cloud providers.
### Keeping Gateways up to date
It's a good idea to keep your Gateways up to date with the latest version
available. See [upgrading Gateways](/kb/administer/upgrading) for ways to
automate this.
## High availability
Firezone was designed from the ground up to support high availability
requirements. This is achieved through a combination of **automatic failover**
and **load balancing**, both of which are automatically enabled on all plans.
and **load balancing**, both of which are available on all plans.
### Automatic failover
Two or more Gateways can be deployed within a Site to achieve automatic failover
Deploy two or more Gateways within the same Site to achieve automatic failover
for Client connections to Resources in that Site.
Here's how it works:
@@ -144,7 +144,7 @@ Here's how it works:
- Clients identify unhealthy gateways using keepalive timers. If the timer
expires, the Client will disconnect from the unhealthy Gateway and request a
new, healthy one from the portal.
- The Client keepalive timer expires after **20 seconds**. This is the maximum
- The Client keepalive timer expires after **10 seconds**. This is the maximum
time it takes for existing Client connections to be rerouted to a healthy
Gateway in the event of a Gateway failure.

5
website/src/app/kb/deploy/groups/readme.mdx
View File

@@ -10,9 +10,10 @@ import NextStep from "@/components/NextStep";
</PlanBadge>
Groups form the basis of the Firezone access control model. They are used to
organize users and apply [Policies](/kb/deploy/policies) to them.
organize Users and Service Accounts into a single context you can apply
[Policies](/kb/deploy/policies) to.
Groups can be created by going to `Groups` -> `Add Group` and then entering an
Groups can be created by going to `Groups -> Add Group` and then entering an
appropriate name for the group.
<Alert color="info">

6
website/src/app/kb/deploy/policies/readme.mdx
View File

@@ -11,13 +11,13 @@ import NextStep from "@/components/NextStep";
Policies are what grant users access to Resources.
To define a Policy, go to `Policies` -> `Add Policy`.
To define a Policy, go to `Policies -> Add Policy`.
Policies define a single Group access to a single Resource.
Policies define a single Group's access to a single Resource.
<Alert color="warning">
**Note:** To preserve audit trails, Policy access cannot be changed once a
Policy is created. Double-check to ensure the group and resource selected are
Policy is created. Double-check to ensure the Group and Resource selected are
correct before creating the Policy.
</Alert>

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

@@ -12,7 +12,7 @@ import PlanBadge from "@/components/PlanBadge";
Resources define subnets, IP addresses, or DNS names you wish to manage access
for.
To create a Resource, go to `Sites` -> `<Site>` -> `Add a Resource`.
To create a Resource, go to `Sites -> <site name> -> Add a Resource`.
<Alert color="info">
Remember, Resources **must** be reachable by all Gateways in the same Site.
@@ -27,7 +27,7 @@ From there, you can select the type of Resource you want to create:
`sub1.sub2.example.com`.
- To non-recursively match all subdomains, use a question mark, such as
`?.example.com`. This will match `example.com`, `sub1.example.com`, and
`sub2.example.com` _but not_ `sub1.sub2.example.com`.
`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`

4
website/src/app/kb/deploy/sites/readme.mdx
View File

@@ -26,8 +26,8 @@ managing access to a cluster of servers.
## Creating a Site
To create a Site, click the "Sites" tab in the left-hand navigation and then
click the "Add Site" button. You will be prompted to enter a name for the Site.
To create a Site, click the `Sites` tab in the left-hand navigation and then
click the `Add Site` button. You will be prompted to enter a name for the Site.
<Alert color="info">
Don't worry too much about the name of the Site now. You can always change it

4
website/src/app/kb/deploy/users/readme.mdx
View File

@@ -9,8 +9,8 @@ import PlanBadge from "@/components/PlanBadge";
</PlanBadge>
Users can be created by going to `Actors` -> `Add Actor` and then selecting
`User` as the actor type.
Users can be created by going to `Actors -> Add Actor` and then selecting `User`
as the actor type.
<Alert color="info">
Automatic user sync is available for Google Workspace, Microsoft Entra ID, and

7
website/src/app/kb/user-guides/android-client/readme.mdx
View File

@@ -14,3 +14,10 @@ Google Play Store.
[Download the Firezone app](https://play.google.com/store/apps/details?id=dev.firezone.android)
from the Google Play Store.
## Upgrading
Updates for the Android client are handled through the Google Play Store.
Consult the
[Play Store documentation](https://support.google.com/googleplay/answer/113412?hl=en)
for more information on how to update apps on your device.

19
website/src/app/kb/user-guides/apple-client/readme.mdx
View File

@@ -1,19 +0,0 @@
# Apple Client (macOS / iOS)
Firezone supports macOS and iOS with native clients available in the macOS App
Store and iOS App Stores respectively. The iOS app also works for iPad.
## Prerequisites
- macOS 12 or higher, iOS 15 or higher, or iPadOS 15 or higher
- Intel and Apple silicon Macs are supported
## Installation
- **macOS**: Our macOS client is currently pending final review with Apple. We
will update this page with the App Store link once it is available. In the
meantime, use [this link](https://testflight.apple.com/join/27oucOp0) to
install the latest Test Flight version.
- **iOS**:
[Download the client](https://apps.apple.com/us/app/firezone/id6443661826)
from the Apple App Store.

0
website/src/app/kb/user-guides/apple-client/page.tsx → website/src/app/kb/user-guides/ios-client/page.tsx
View File

21
website/src/app/kb/user-guides/ios-client/readme.mdx Normal file
View File

@@ -0,0 +1,21 @@
import { TabsItem, TabsGroup } from "@/components/DocsTabs";
# iOS Client
Firezone supports iOS with a native clients available in the iOS App Store. The
iOS app also works for iPad.
## Prerequisites
- iOS 15 or higher
## Installation
[Download the client](https://apps.apple.com/us/app/firezone/id6443661826) from
the Apple App Store.
### Upgrading
Updates for the Apple clients are handled through the Apple App Store. Consult
[Apple's documentation](https://support.apple.com/guide/iphone/update-apps-iph98709f167/17.0/ios/17.0)
for more information on how to update apps on your device.

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

@@ -70,7 +70,7 @@ Options:
-V, --version Print version
```
## Split DNS
### 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.
@@ -81,7 +81,7 @@ environment variable to `systemd-resolved` or `etc-resolv-conf`.
Read more below to figure out which DNS control method is appropriate for your
system.
### systemd-resolved
#### 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
@@ -92,7 +92,7 @@ command:
systemctl status systemd-resolved
```
### NetworkManager
#### 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
@@ -110,7 +110,7 @@ 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 and no other configuration is necessary.
### /etc/resolv.conf
#### /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
@@ -127,7 +127,7 @@ sudo mv /etc/resolv.conf.before-firezone /etc/resolv.conf
[Read more](/kb/deploy/dns) about how DNS works in Firezone.
## Environment variable reference
### Environment variable reference
Here's an exhaustive list of environment variables you can use for the Linux
client.
@@ -140,3 +140,10 @@ client.
| `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/). |
### Upgrading
1. Stop the running Client.
1. Download a newer binary from one of the [links above](#installation).
1. Replace the existing binary with the new one.
1. Start the Client with the same environment variables as before.

11
website/src/app/kb/user-guides/macos-client/page.tsx Normal file
View File

@@ -0,0 +1,11 @@
import Content from "./readme.mdx";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Apple Clients • Firezone Docs",
description: "Firezone Documentation",
};
export default function Page() {
return <Content />;
}

31
website/src/app/kb/user-guides/macos-client/readme.mdx Normal file
View File

@@ -0,0 +1,31 @@
import { TabsItem, TabsGroup } from "@/components/DocsTabs";
# macOS Client
Firezone supports macOS with a native client available in the macOS App Store.
## Prerequisites
- macOS 12 or higher
- Intel or Apple silicon Mac
## Installation
Our macOS client is currently pending final review with Apple. We will update
this page with the App Store link once it is available. In the meantime, use
[this link](https://testflight.apple.com/join/27oucOp0) to install the latest
Test Flight version.
### Upgrading
Updates for the Apple clients are handled through the Apple App Store. Consult
[Apple's documentation](https://support.apple.com/guide/app-store/update-apps-fir9b01adda3/3.0/mac/14.0)
for more information on how to update apps on your device.
## 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.

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

@@ -16,8 +16,11 @@ platform.
<AndroidIcon size={10} href="/kb/user-guides/android-client">
<p>Android client</p>
</AndroidIcon>
<AppleIcon size={10} href="/kb/user-guides/apple-client">
<p>macOS & iOS clients</p>
<AppleIcon size={10} href="/kb/user-guides/macos-client">
<p>macOS client</p>
</AppleIcon>
<AppleIcon size={10} href="/kb/user-guides/ios-client">
<p>iOS client</p>
</AppleIcon>
<WindowsIcon size={10} href="/kb/user-guides/windows-client">
<p>Windows client</p>

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

@@ -17,10 +17,23 @@ links:
## Usage
The Windows Client must be run as an administrator to function correctly.
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.**
**Be sure to click "Allow" when prompted by the User Account Control dialog.**
If that dialog does not appear, you may need to manually run Firezone as an
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."
## 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.
## 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.

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

@@ -209,7 +209,7 @@ export default function Footer() {
</Link>
</div>
<div className="flex p-2 items-center justify-center space-x-5">
<AppleIcon size={5} href="/kb/user-guides/apple-client" />
<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" />
<AndroidIcon size={5} href="/kb/user-guides/android-client" />

2
website/src/components/KbSidebar/Item.tsx
View File

@@ -25,7 +25,7 @@ export default function Item({
(active(href) ? "bg-neutral-200 " : "") +
"pb-0.5 flex " +
((!topLevel && "border-l") || "") +
" border-0.5 border-neutral-500 items-center text-left text-base font-normal text-neutral-900 hover:bg-neutral-100"
" border-0.5 border-neutral-500 items-center text-left text-base font-normal hover:bg-neutral-100"
}
>
{!topLevel && <HiMinus className="w-2 h-2" />}

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

@@ -114,7 +114,10 @@ export default function KbSidebar() {
label="Administer"
>
<li>
<Item href="/kb/administer/upgrading" label="Upgrading" />
<Item
href="/kb/administer/upgrading"
label="Upgrading Gateways"
/>
</li>
<li>
<Item
@@ -143,10 +146,13 @@ export default function KbSidebar() {
</li>
<li>
<Item
href="/kb/user-guides/apple-client"
label="macOS / iOS client"
href="/kb/user-guides/macos-client"
label="macOS client"
/>
</li>
<li>
<Item href="/kb/user-guides/ios-client" label="iOS client" />
</li>
<li>
<Item
href="/kb/user-guides/windows-client"

6
website/src/components/SupportOptions/index.tsx
View File

@@ -21,7 +21,11 @@ export default function SupportOptions() {
<a href="https://join.slack.com/t/firezone-users/shared_invite/zt-111043zus-j1lP_jP5ohv52FhAayzT6w">
Public Slack group
</a>
: join discussions, meet other users, and meet the contributors
: Join discussions, meet other users, and meet the contributors
</li>
<li>
<a href="mailto:support@firezone.dev">Email us</a>: We read every
message.
</li>
</ul>
<div className="flex">