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

chore(website): Remove old docs (#8895)

Browse Source 
These confuse users and are horribly outdated.

Fixes #8528
This commit is contained in:
Jamil
2025-04-23 08:24:09 -07:00
committed by GitHub
parent 0a2a393d4c
commit f181a3245b
144 changed files with 5 additions and 7338 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
website/redirects.js
View File

@@ -150,4 +150,9 @@ module.exports = [
destination: "/kb/client-apps/linux-headless-client",
permanent: true,
},
{
source: "/docs/:path*",
destination: "/kb",
permanent: true,
},
];

6
website/src/app/docs/_page.tsx
View File

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

6
website/src/app/docs/administer/backup/_page.tsx
View File

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

11
website/src/app/docs/administer/backup/page.tsx
View File

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

107
website/src/app/docs/administer/backup/readme.mdx
View File

@@ -1,107 +0,0 @@
import { TabsGroup, TabsItem } from "@/components/Tabs";
import Alert from "@/components/DocsAlert";
import SupportOptions from "@/components/SupportOptions";
# Backup and Restore
Firezone can be safely backed up and restored in a couple of minutes under most
circumstances.
<Alert color="info">
This guide is written for Firezone deployments using **Docker Engine** on
**Linux** only.
</Alert>
Unless your hosting provider supports taking live VM snapshots, you'll need to
stop Firezone before backing it up. This ensures the Postgres data directory is
in a consistent state when the backup is performed. Backing up a running
Firezone instance will **most likely** result in data loss when restored; you
have been warned.
After stopping Firezone, backing up Firezone is mostly a matter of copying the
relevant [files and directories](/docs/reference/file-and-directory-locations)
to a location of your choosing.
See the steps below for specific examples for Docker and Omnibus.
<TabsGroup>
<TabsItem title="Docker" active>
### Backup
For Docker-based deployments, this will consist of backing up the
`$HOME/.firezone` directory along with the Postgres data directory, typically
located at `/var/lib/docker/volumes/firezone_postgres-data` on Linux if you're
using the default Docker compose template.
1. Stop Firezone (warning: this **will** disconnect any users connected to the
VPN):
```bash
docker compose -f $HOME/.firezone/docker-compose.yml down
```
2. Copy relevant files and folders. If your made any customizations to
`/etc/docker/daemon.json` (for example, for IPv6 support), be sure to include
that in the backup as well.
```bash
tar -zcvfp $HOME/firezone-back-$(date +'%F-%H-%M').tgz $HOME/.firezone /var/lib/docker/volumes/firezone_postgres-data
```
A backup file named `firezone-back-TIMESTAMP.tgz` will then be stored in
`$HOME/`.
### Restore
1. Copy the files back to their original location:
```bash
tar -zxvfp /path/to/firezone-back.tgz -C / --numeric-owner
```
2. Optionally, enable Docker to boot on startup:
```bash
systemctl enable docker
```
</TabsItem>
<TabsItem title="Omnibus">
### Backup
1. Stop Firezone (warning: this **will** disconnect any users connected to the
VPN):
```bash
firezone-ctl stop
```
2. Copy relevant files and folders:
```bash
tar -zcvfp $HOME/firezone-back-$(date +'%F-%H-%M').tgz /var/opt/firezone /opt/firezone /usr/bin/firezone-ctl /etc/systemd/system/firezone-runsvdir-start.service /etc/firezone
```
A backup file named `firezone-back-TIMESTAMP.tgz` will then be stored in
`$HOME/`.
### Restore
1. Copy the files back to their original location:
```bash
tar -zxvfp /path/to/firezone-back.tgz -C / --numeric-owner
```
2. Reconfigure Firezone to ensure configuration is applied to the host system:
```bash
firezone-ctl reconfigure
```
</TabsItem>
</TabsGroup>
<SupportOptions />

12
website/src/app/docs/administer/debug-logs/page.tsx
View File

@@ -1,12 +0,0 @@
import Content from "./readme.mdx";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Debug Logs • Firezone Docs",
description:
"Docker deployments of Firezone generate and store debug logs to a JSON file on the host machine.",
};
export default function Page() {
return <Content />;
}

48
website/src/app/docs/administer/debug-logs/readme.mdx
View File

@@ -1,48 +0,0 @@
import Alert from "@/components/DocsAlert";
# Debug Logs
<Alert color="info">
This article is written for Docker based deployments of Firezone.
</Alert>
Docker deployments of Firezone consist of 3 running containers:
| Container | Function | Example logs |
| --------- | ------------- | --------------------------------------------- |
| firezone | Web portal | HTTP requests received and responses provided |
| postgres | Database | |
| caddy | Reverse proxy | |
Each container generates and stores logs to a JSON file on the host machine.
These files can be found at
`var/lib/docker/containers/{CONTAINER_ID}/{CONTAINER_ID}-json.log`.
Run the `docker compose logs` command to view the log output from all running
containers. Note, `docker compose` commands need to be run in the Firezone root
directory. This is `$HOME/.firezone` by default.
See additional options of the `docker compose logs` command
[here](https://docs.docker.com/engine/reference/commandline/compose_logs).
## Managing and configuring Docker logs
By default, Firezone uses the `json-file` logging driver without
[additional configuration](https://docs.docker.com/config/containers/logging/json-file).
This means logs from each container are individually stored in a file format
designed to be exclusively accessed by the Docker daemon. Log rotation is not
enabled, so logs on the host can build up and consume excess storage space.
For production deployments of Firezone you may want to configure how logs are
collected and stored. Docker provides
[multiple mechanisms](https://docs.docker.com/config/containers/logging/configure)
to collect information from running containers and services.
Examples of popular plugins, configurations, and use cases are:
- Export container logs to your SIEM or observability platform (i.e.
[Splunk](https://docs.docker.com/config/containers/logging/splunk) or
[Google Cloud Logging](https://docs.docker.com/config/containers/logging/gcplogs))
- Enable log rotation and max file size.
- [Customize log driver output](https://docs.docker.com/config/containers/logging/log_tags)
with tags.

12
website/src/app/docs/administer/migrate/page.tsx
View File

@@ -1,12 +0,0 @@
import Content from "./readme.mdx";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Migrate to Docker • Firezone Docs",
description:
"Migrating to Docker is a simple process that can be done in a few steps.",
};
export default function Page() {
return <Content />;
}

72
website/src/app/docs/administer/migrate/readme.mdx
View File

@@ -1,72 +0,0 @@
import SupportOptions from "@/components/SupportOptions";
# Migrate from Omnibus to Docker
Chef Infra Client, the configuration system Chef Omnibus relies on, has been
[scheduled for End-of-Life in 2024](https://docs.chef.io/versions). Firezone 0.7
will be the last version to offer Omnibus-based deployments. Users are
encouraged to migrate to a Docker-based deployment of Firezone using this guide.
Existing Omnibus-based deployments of Firezone will continue to function as-is,
but no officially supported RedHat or Debian packages will be published for
Firezone 0.8 and above.
See this
[GitHub issue tracking discussion ](https://github.com/firezone/firezone/issues/1304)
for more details.
Follow this guide to migrate from an Omnibus-based deployment to a Docker-based
deployment. In most cases this can be done with minimal downtime and without
requiring you to regenerate WireGuard configurations for each device.
Heavily customized deployments (such as those using an external database or
custom reverse proxy) will likely need extra troubleshooting and manual steps
taken to perform a successful migration.
Take a look at the
[migration script source ](https://github.com/firezone/firezone/blob/legacy/scripts/docker_migrate.sh)
to get a detailed idea of the steps involved.
Estimated time to complete: **2 hours**.
## Steps to migrate
1. **Back up** your server. This ensures you have a working state to roll back
to in case anything goes terribly wrong. At a _bare minimum_ you'll want to
back up the
[file and directories Firezone uses ](/docs/reference/file-and-directory-locations),
but we recommend taking a full snapshot of your VPS if possible.
1. Ensure you're running the latest version of Firezone. See our
[upgrade guide ](/docs/administer/upgrade) if not.
1. Install the latest version of
[**Docker** ](https://docs.docker.com/engine/install) and
[Docker Compose ](https://docs.docker.com/compose/install/linux/#install-compose)
for your OS. **Docker Compose version 2 or higher is required**. We recommend
using Docker Server for Linux. Docker Desktop will work too, but is not
preferred for production use cases at this time because it rewrites packets
under some conditions and may cause unexpected issues with Firezone.
1. Download and run the migration script:
```bash
bash <(curl -fsSL https://github.com/firezone/firezone/raw/legacy/scripts/docker_migrate.sh)
```
This will ask you a few questions, then attempt to migrate your installation to
Docker. If all goes well, your Firezone instance should be running with Docker,
data intact.
## Rolling back
If anything goes wrong, you can abort the migration by simply bringing the
Docker services down and the Omnibus ones back up:
```bash
docker-compose down
sudo firezone-ctl start
```
If you've found a bug, please
[open a GitHub issue](https://github.com/firezone/firezone/issues) with the
error output and any steps needed to reproduce.
<SupportOptions />

11
website/src/app/docs/administer/page.tsx
View File

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

11
website/src/app/docs/administer/readme.mdx
View File

@@ -1,11 +0,0 @@
# Administer Firezone
Guides for day-to-day management tasks of your Firezone instance.
1. [Backup](/docs/administer/backup)
1. [Debug Logs](/docs/administer/debug-logs)
1. [Migrate](/docs/administer/migrate)
1. [Regenerate Keys](/docs/administer/regen-keys)
1. [Troubleshoot](/docs/administer/troubleshoot)
1. [Uninstall](/docs/administer/uninstall)
1. [Upgrade](/docs/administer/upgrade)

11
website/src/app/docs/administer/regen-keys/page.tsx
View File

@@ -1,11 +0,0 @@
import Content from "./readme.mdx";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Regenerate Secret Keys • Firezone Docs",
description: "Instructions for renegerating application secret keys.",
};
export default function Page() {
return <Content />;
}

83
website/src/app/docs/administer/regen-keys/readme.mdx
View File

@@ -1,83 +0,0 @@
import { TabsGroup, TabsItem } from "@/components/Tabs";
import Alert from "@/components/DocsAlert";
# Regenerate Secret Keys
When you install Firezone, secrets are generated for encrypting database fields,
securing WireGuard tunnels, securing cookie sessions, and more.
If you're looking to regenerate one or more of these secrets, it's possible to
do so using the same bootstrap scripts that were used when installing Firezone.
## Regenerate secrets
<Alert color="danger">
Replacing the `DATABASE_ENCRYPTION_KEY` will render all encrypted data in the
database useless. This **will** break your Firezone install unless you are
starting with an empty database. You have been warned.
</Alert>
<Alert color="warning">
Replacing `GUARDIAN_SECRET_KEY`, `SECRET_KEY_BASE`, `LIVE_VIEW_SIGNING_SALT`,
`COOKIE_SIGNING_SALT`, and `COOKIE_ENCRYPTION_SALT` will reset all browser
sessions and REST API tokens.
</Alert>
Use the procedure below to regenerate secrets:
<TabsGroup>
<TabsItem title="Docker" active>
Navigate to the Firezone installation directory, then:
```bash
mv .env .env.bak
docker run firezone/firezone bin/gen-env > .env
```
Now, move desired env vars from `.env.bak` back to `.env`, keeping the new
secrets intact.
</TabsItem>
<TabsItem title="Omnibus">
```bash
mv /etc/firezone/secrets.json /etc/firezone/secrets.bak.json
sudo firezone-ctl reconfigure
```
</TabsItem>
</TabsGroup>
## Regenerate WireGuard private key
<Alert color="warning">
Replacing the WireGuard private key will render all existing device configs
invalid. Only do so if you're prepared to also regenerate device configs after
regenerating the WireGuard private key.
</Alert>
To regenerate WireGuard private key, simply move or rename the private key file.
Firezone will generate a new one on next start.
<TabsGroup>
<TabsItem title="Docker" active>
```bash
cd $HOME/.firezone
docker-compose stop firezone
sudo mv firezone/private_key firezone/private_key.bak
docker-compose start firezone
```
</TabsItem>
<TabsItem title="Omnibus">
```bash
sudo firezone-ctl stop phoenix
sudo mv /var/opt/firezone/cache/wg_private_key /var/opt/firezone/cache/wg_private_key.bak
sudo firezone-ctl start phoenix
```
</TabsItem>
</TabsGroup>

12
website/src/app/docs/administer/troubleshoot/page.tsx
View File

@@ -1,12 +0,0 @@
import Content from "./readme.mdx";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Troubleshoot • Firezone Docs",
description:
"Troubleshoot common connectivity and configuration issues with Firezone's WireGuard®-based secure access platform.",
};
export default function Page() {
return <Content />;
}

210
website/src/app/docs/administer/troubleshoot/readme.mdx
View File

@@ -1,210 +0,0 @@
import { TabsGroup, TabsItem } from "@/components/Tabs";
import SupportOptions from "@/components/SupportOptions";
# Troubleshooting Guide
This guide documents common configuration and connectivity issues. For any
problems that arise, a good first bet is to check the Firezone logs.
<TabsGroup>
<TabsItem title="Docker" active>
Each container stores logs as a JSON file on the host machine. These can be
shown with the `docker logs {CONTAINER}` command. Log files are found at
`var/lib/docker/containers/{CONTAINER_ID}/{CONTAINER_ID}-json.log` by default.
See [debug logs](/docs/administer/debug-logs) for additional details.
</TabsItem>
<TabsItem title="Omnibus">
Firezone logs are stored in `/var/log/firezone` and can be viewed with
`sudo firezone-ctl tail`.
</TabsItem>
</TabsGroup>
## Application crash loop preventing config changes
In cases where the application is crash looping because of corrupt,
inaccessible, or invalid OIDC or SAML configuration in the DB, you can try
clearing the affected fields.
For example, to clear OIDC configs:
<TabsGroup>
<TabsItem title="Docker" active>
```bash
psql -d firezone -h 127.0.0.1 -U postgres -c "UPDATE configurations SET openid_connect_providers = '[]'"
```
Similarly, to clear SAML configs:
```bash
psql -d firezone -h 127.0.0.1 -U postgres -c "UPDATE configurations SET saml_identity_providers = '[]'"
```
</TabsItem>
<TabsItem title="Omnibus">
```bash
/opt/firezone/embedded/bin/psql -d $DATABASE_NAME -h $DATABASE_HOST -U $DATABASE_USER -c "UPDATE configurations SET openid_connect_providers = '[]'"
```
Similarly, to clear SAML configs:
```bash
/opt/firezone/embedded/bin/psql -d $DATABASE_NAME -h $DATABASE_HOST -U $DATABASE_USER -c "UPDATE configurations SET saml_identity_providers = '[]'"
```
</TabsItem>
</TabsGroup>
## Debugging WebSocket connectivity issues
The Web UI requires a secure websocket connection to function. If a secure
websocket connection can't be established, you'll see a red dot indicator in the
upper-right portion of the Firezone web UI and a corresponding message when you
hover over it:
```text
Secure websocket not connected! ...
```
If you're accessing Firezone using the same URL defined in your `EXTERNAL_URL`
variable from above, the issue is likely to be in your reverse proxy
configuration. Ensure your reverse proxy has WebSocket support enabled for
Firezone. If you're using the default Caddy reverse proxy, WebSocket is enabled
and configured automatically.
In most cases, you'll find clues in one or more of the following locations:
<TabsGroup>
<TabsItem title="Docker" active>
- `firezone` service logs: `docker compose logs firezone`
- `caddy` service logs: `docker compose logs caddy`
</TabsItem>
<TabsItem title="Omnibus">
- Your browser's developer tool logs, specifically the `Network` tab.
- `sudo firezone-ctl tail nginx`
- `sudo firezone-ctl tail phoenix`
If the websocket connection is successful, you should see output in the
`phoenix` service logs similar the following:
```text
2022-09-23_15:05:47.29158 15:05:47.291 [info] CONNECTED TO Phoenix.LiveView.Socket in 24µs
2022-09-23_15:05:47.29160 Transport: :websocket
2022-09-23_15:05:47.29160 Serializer: Phoenix.Socket.V2.JSONSerializer
2022-09-23_15:05:47.29161 Parameters: %{"_csrf_token" => "XFEFCHQ2fRQABQwtKQdCJDlFAzEcCCJvn7LqDsMXE4eGZtsBzuwVRCJ6", "_mounts" => "0", "_track_static" => %{"0" => "https://demo.firez.one/dist/admin-02fabe0f543c64122dbf5bc5b3451e51.css?vsn=d", "1" => "https://demo.firez.one/dist/admin-04e75c78295062c2c07af61be50248b0.js?vsn=d"}, "vsn" => "2.0.0"}
2022-09-23_15:05:47.33655 15:05:47.336 [info] CONNECTED TO FzHttpWeb.UserSocket in 430µs
2022-09-23_15:05:47.33657 Transport: :websocket
2022-09-23_15:05:47.33658 Serializer: Phoenix.Socket.V2.JSONSerializer
2022-09-23_15:05:47.33658 Parameters: %{"token" => "SFMyNTY.g2gDYQFuBgB6HeJqgwFiAAFRgA.qKoC2bi9DubPkE0tfaRSPERWUFyQQPQV5n4nFKVppxc", "vsn" => "2.0.0"}
2022-09-23_15:05:47.35063 15:05:47.350 [info] JOINED notification:session in 636µs
2022-09-23_15:05:47.35065 Parameters: %{"token" => "SFMyNTY.g2gDYQFuBgB6HeJqgwFiAAFRgA.zSG7pefm-Vgf_zvduxa5E9VK4s8PKqzc0xBDGNx5FQE", "user_agent" => "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:106.0) Gecko/20100101 Firefox/106.0"}
```
</TabsItem>
</TabsGroup>
## Debugging WireGuard connectivity issues
Most connectivity issues with Firezone are caused by other `iptables` or
`nftables` rules which interfere with Firezone's operation. If you have rules
active, you'll need to ensure these don't conflict with the Firezone rules.
### Internet connectivity drops when tunnel is active
If your Internet connectivity drops whenever you activate your WireGuard tunnel,
you should make sure that the `FORWARD` chain allows packets from your WireGuard
clients to the destinations you want to allow through Firezone.
If you're using `ufw`, this can be done by making sure the default routing
policy is `allow`:
```text
ubuntu@fz:~$ sudo ufw default allow routed
Default routed policy changed to 'allow'
(be sure to update your rules accordingly)
```
A `ufw` status for a typical Firezone server might look like this:
```text
ubuntu@fz:~$ sudo ufw status verbose
Status: active
Logging: on (low)
Default: deny (incoming), allow (outgoing), allow (routed)
New profiles: skip
To Action From
-- ------ ----
22/tcp ALLOW IN Anywhere
80/tcp ALLOW IN Anywhere
443/tcp ALLOW IN Anywhere
51820/udp ALLOW IN Anywhere
22/tcp (v6) ALLOW IN Anywhere (v6)
80/tcp (v6) ALLOW IN Anywhere (v6)
443/tcp (v6) ALLOW IN Anywhere (v6)
51820/udp (v6) ALLOW IN Anywhere (v6)
```
## Admin login isn't working
If the password for the account with email `DEFAULT_ADMIN_EMAIL` isn't working,
you can reset it using the process below.
<TabsGroup>
<TabsItem title="Docker" active>
First change directory to your Firezone installation directory
(`$HOME/.firezone` by default), then run the `bin/create-or-reset-admin` script
to reset the admin user's password. The password for the user specified by
`DEFAULT_ADMIN_EMAIL` in `$HOME/.firezone/.env` will be reset to the
`DEFAULT_ADMIN_PASSWORD` variable.
```bash
cd $HOME/.firezone
docker compose exec firezone bin/create-or-reset-admin
```
**Note**: If local authentication is disabled, resetting the admin user's
password will not re-enable it.
</TabsItem>
<TabsItem title="Omnibus">
Run the following command to reset the password on the default admin user.
```bash
sudo firezone-ctl create-or-reset-admin
```
</TabsItem>
</TabsGroup>
## Re-enable local authentication via CLI
If you've configured an [OIDC](/docs/authenticate/oidc) or
[SAML](/docs/authenticate/saml) provider, you can consider disabling local
authentication for additional security.
If, however, issues arise with your identity provider integration, it's possible
you could be locked out of the admin portal. To re-enable local authentication
so you can log in and resolve the issue, you can temporarily re-enable local
authentication via the [REST API](/docs/reference/rest-api/configurations).
If that's not an option, you can re-enable local authentication by running the
following commands on the host of your Firezone instance:
```bash
cd $HOME/.firezone
docker compose exec postgres psql -U postgres -h 127.0.0.1 -d firezone -c "UPDATE configurations SET local_auth_enabled = 't'"
```
<SupportOptions />

11
website/src/app/docs/administer/uninstall/page.tsx
View File

@@ -1,11 +0,0 @@
import Content from "./readme.mdx";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Uninstall • Firezone Docs",
description: "Firezone can be uninstalled in a few simple steps.",
};
export default function Page() {
return <Content />;
}

37
website/src/app/docs/administer/uninstall/readme.mdx
View File

@@ -1,37 +0,0 @@
import { TabsGroup, TabsItem } from "@/components/Tabs";
import Alert from "@/components/DocsAlert";
# Uninstall Firezone
Firezone can be uninstalled using the steps below.
<Alert color="danger">
This will irreversibly destroy ALL Firezone data and can't be undone.
</Alert>
<TabsGroup>
<TabsItem title="Docker" active>
For docker-based deployments, simply bring the firezone services down, then
delete the working directory where you installed the Firezone docker files
(`$HOME/.firezone` by default):
```bash
# default install dir
installDir=$HOME/.firezone
docker compose -f $installDir/docker-compose.yml down -v
rm -rf $installDir
```
</TabsItem>
<TabsItem title="Omnibus">
To completely remove Omnibus-based deployments of Firezone run the
[uninstall.sh script](https://github.com/firezone/firezone/blob/legacy/scripts/omnibus-uninstall.sh):
```bash
sudo /bin/bash -c "$(curl -fsSL https://github.com/firezone/firezone/raw/legacy/scripts/omnibus-uninstall.sh)"
```
</TabsItem>
</TabsGroup>

7
website/src/app/docs/administer/upgrade/_page.tsx
View File

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

11
website/src/app/docs/administer/upgrade/page.tsx
View File

@@ -1,11 +0,0 @@
import _Page from "./_page";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Upgrade • Firezone Docs",
description: "Firezone can be upgraded with little or no downtime.",
};
export default function Page() {
return <_Page />;
}

293
website/src/app/docs/administer/upgrade/readme.mdx
View File

@@ -1,293 +0,0 @@
import { TabsGroup, TabsItem } from "@/components/Tabs";
import Alert from "@/components/DocsAlert";
import Image from "next/image";
# Upgrade Firezone
Upgrading Firezone will pause all VPN sessions and temporarily bring down the
web UI.
<Alert color="info">
Automatic rollbacks are still under development. We recommend backing up
relevant [files and folders](/docs/reference/file-and-directory-locations)
before upgrading in case anything goes wrong.
</Alert>
Follow the steps below to upgrade Firezone:
<TabsGroup>
<TabsItem title="Docker" active>
1. Change to your Firezone installation directory, by default `$HOME/.firezone`:
```bash
cd $HOME/.firezone
```
1. If your `.env` file has a `VERSION` variable, update it to the desired
version. By default `latest` is assumed if not set. This variable is read in
newer versions of the docker-compose.yml template to populate the `image:`
key for the `firezone` service.
1. Update service images:
```bash
docker compose pull
```
1. Re-up the services (**warning: this will restart updated services**):
```bash
docker compose up -d
```
</TabsItem>
<TabsItem title="Omnibus">
1. If not setup already, install our package repository based on your distro's
package format:
- [deb packages](https://cloudsmith.io/~firezone/repos/firezone/setup/#formats-deb)
- [rpm packages](https://cloudsmith.io/~firezone/repos/firezone/setup/#formats-rpm)
1. Upgrade the `firezone` package using your distro's package manager.
1. Run `firezone-ctl reconfigure` to pick up the new changes.
1. Run `firezone-ctl restart` to restart services.
</TabsItem>
</TabsGroup>
If you hit any issues, please let us know by
[filing an issue](https://github.com/firezone/firezone/issues/new/choose).
## Upgrading to 0.7.x
Firezone 0.7.0 introduces a new [REST API](/docs/reference/rest-api) that allows
administrators to automate much of the day to day configuration of Firezone.
The REST API `/v0/configuration` endpoint supersedes some of the previous
environment variables used for WireGuard server configuration.
If you're running Firezone &lt; 0.6, we recommend updating to the latest 0.6.x
release **before** upgrading to 0.7. This will ensure any environment variables
are properly parsed and migrated into the DB as runtime `configurations`.
**Note**: Omnibus deployments are deprecated in 0.7.x and will be removed in
Firezone 0.8 and above. We recommend
[migrating your installation](/docs/administer/migrate) to Docker if you haven't
done so already.
## Upgrading to >= 0.6.12
### WIREGUARD\_\* env vars
Firezone 0.6.12 moves the `WIREGUARD_ALLOWED_IPS`,
`WIREGUARD_PERSISTENT_KEEPALIVE`, and `WIREGUARD_DNS` environment variables to
the database to be configured in the UI at `/settings/client_defaults`. If the
corresponding value at `/settings/client_defaults` was empty, the environment
variable's value was used to populate the field.
This is a small step in our quest to move more runtime configuration from
environment variables to the DB.
### `AUTH_OIDC_JSON` config
Similar to the `WIREGUARD_*` env vars above, the `AUTH_OIDC_JSON` env var has
similarly been moved to the database and can be configured at `/settings/site`.
In Firezone 0.7 this is now configurable via the
[REST API](/docs/reference/rest-api/configurations) as well.
### Fix IPv6
0.6.12 fixes IPv6 routing within Docker networks. To enable, add IPv6 addresses
to your `$HOME/.firezone/docker-compose.yml` by setting the following fields:
```yaml
services:
firezone:
networks:
firezone-network:
ipv6_address: fcff:3990:3990::99
# ...
networks:
firezone-network:
ipam:
config:
- subnet: fcff:3990:3990::/64
- gateway: fcff:3990:3990::1
```
You also need to update the Docker daemon to enable IPv6. See our
[IPv6 guide](/docs/deploy/docker/#step-4-enable-ipv6-optional) for more info.
## Upgrading from 0.5.x to 0.6.x
Firezone 0.6 introduces **Docker support**, SAML 2.0 authentication, more
granular user provisioning options, and a slew of minor improvements and
bugfixes.
### Migrate to Docker
Docker is now the preferred way to deploy and manage Firezone. See the
[migration guide](/docs/administer/migrate) to migrate today. In most cases this
can be done in a few minutes using our automatic migration script.
### Update Configuration
Some configuration variables have recently moved to the DB in order to be
configurable at runtime. Check the [configure guide](/docs/deploy/configure) for
more information.
## Upgrading from < 0.5.0 to >= 0.5.0
0.5.0 introduces a few breaking changes and configuration updates that will need
to be addressed. Read more below.
### Bundled Nginx non_ssl_port (HTTP) requests removed
0.5.0 and above removes the `force_ssl` and `non_ssl_port` settings for Nginx.
SSL is required for Firezone to function; if you're using (or would like to use)
your own reverse proxy, we recommend disabling the bundle Nginx service by
setting `default['firezone']['nginx']['enabled'] = false` and pointing your
reverse proxy directly to the Phoenix app on port 13000 (by default).
Read more about setting up a custom reverse proxy
[here](/docs/deploy/advanced/reverse-proxy).
### ACME protocol support
0.5.0 introduces ACME protocol support for automatically renewing SSL
certificates with the bundled Nginx service. To enable,
- Make sure `default['firezone']['external_url']` contains a valid FQDN that
resolves to your server's public IP address.
- Ensure port `80/tcp` is reachable
- Enable ACME protocol support with
`default['firezone']['ssl']['acme']['enabled'] = true` in your config file.
### Overlapping egress rule destinations
Firezone 0.5.0 removes the ability to add rules with overlapping destinations.
When upgrading to 0.5.0, our migration script will automatically detect these
cases and **keep only the rules whose destination encompasses the other rule**.
If this is OK, **there is nothing you need to do**.
Otherwise, we recommend modifying your ruleset to eliminate these cases before
upgrading.
### Preconfigured Okta and Google SSO
Firezone 0.5.0 removes support for the old-style Okta and Google SSO
configuration in favor of the new, more flexible OIDC-based configuration. If
you have any configuration under the
`default['firezone']['authentication']['okta']` or
`default['firezone']['authentication']['google']` keys, **you need to migrate
these to our OIDC-based configuration using the guide below.**
#### Existing Google OAuth configuration
Remove these lines containing the old Google OAuth configs from your
configuration file located at `/etc/firezone/firezone.rb`
```ruby
default['firezone']['authentication']['google']['enabled']
default['firezone']['authentication']['google']['client_id']
default['firezone']['authentication']['google']['client_secret']
default['firezone']['authentication']['google']['redirect_uri']
```
Then, follow the instructions [here](/docs/authenticate/oidc/google) to
configure Google as an OIDC provider.
#### Existing Okta OAuth configuration
Remove these lines containing the old Okta OAuth configs from your configuration
file located at `/etc/firezone/firezone.rb`
```ruby
default['firezone']['authentication']['okta']['enabled']
default['firezone']['authentication']['okta']['client_id']
default['firezone']['authentication']['okta']['client_secret']
default['firezone']['authentication']['okta']['site']
```
Then, follow the instructions [here](/docs/authenticate/oidc/okta) to configure
Okta as an OIDC provider.
## Upgrading from 0.3.x to >= 0.3.16
Follow the instructions below based on your current version and setup:
### I have an existing OIDC integration
Upgrading to >= 0.3.16 requires the `offline_access` scope for some OIDC
providers to obtain a refresh token. This ensures Firezone syncs with the
identity provider and VPN access is terminated once the user is removed.
Previous versions of Firezone do not have this capability. Users who are removed
from your identity provider will still have active VPN sessions in some cases.
For OIDC providers that support the `offline_access` scope, you will need to add
`offline_access` to the `scope` parameter of your OIDC config. The Firezone
configuration file can be found at `/etc/firezone/firezone.rb` and requires
running `firezone-ctl reconfigure` to pick up the changes.
If Firezone is able to successfully retrieve the refresh token, you will see the
**OIDC Connections** heading in the user details page of the web UI for users
authenticated through your OIDC provider.
<Image
className="mx-auto"
alt="oidc connections"
width={960}
height={540}
src="/images/oidc-connections.png"
/>
If this does not work, you will need to delete your existing OAuth app and
repeat the OIDC setup steps to
[create a new app integration](/docs/authenticate/oidc) .
### I have an existing OAuth integration
Prior to 0.3.11, Firezone used pre-configured OAuth2 providers. Follow the
instructions [here](/docs/authenticate/oidc) to migrate to OIDC.
### I have not integrated an identity provider
No action needed. You can follow the instructions
[here](/docs/authenticate/oidc) to enable SSO through an OIDC provider.
## Upgrading from 0.3.1 to >= 0.3.2
The configuration option `default['firezone']['fqdn']` has been removed in favor
of `default['firezone']['external_url']`. Please set this to the
publicly-accessible URL of your Firezone web portal. If left unspecified it will
default to `https://` + the FQDN of your server.
Reminder, the configuration file can be found at `/etc/firezone/firezone.rb`.
For an exhaustive list of configuration variables and their descriptions, see
the [configuration file reference](/docs/reference/configuration-file).
## Upgrading from 0.2.x to 0.3.x
Starting with version 0.3.0, Firezone no longer stores device private keys on
the Firezone server. Any existing devices should continue to function as-is, but
you will not be able to re-download or view these configurations in the Firezone
Web UI.
## Upgrading from 0.1.x to 0.2.x
Firezone 0.2.x contains some configuration file changes that will need to be
handled manually if you're upgrading from 0.1.x. Run the commands below as root
to perform the needed changes to your `/etc/firezone/firezone.rb` file.
```bash
cp /etc/firezone/firezone.rb /etc/firezone/firezone.rb.bak
sed -i "s/\['enable'\]/\['enabled'\]/" /etc/firezone/firezone.rb
echo "default['firezone']['connectivity_checks']['enabled'] = true" >> /etc/firezone/firezone.rb
echo "default['firezone']['connectivity_checks']['interval'] = 3_600" >> /etc/firezone/firezone.rb
firezone-ctl reconfigure
firezone-ctl restart
```

7
website/src/app/docs/authenticate/_page.tsx
View File

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

11
website/src/app/docs/authenticate/local-auth/page.tsx
View File

@@ -1,11 +0,0 @@
import Content from "./readme.mdx";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Local Authentication • Firezone Docs",
description: "Firezone can be upgraded with little or no downtime.",
};
export default function Page() {
return <Content />;
}

30
website/src/app/docs/authenticate/local-auth/readme.mdx
View File

@@ -1,30 +0,0 @@
import Alert from "@/components/DocsAlert";
# Local Authentication
By default, Firezone will use local email / password for authenticating users to
the Firezone portal. Administrators can add users and assign their passwords on
the `/users` page. See [Add users](/docs/user-guides/add-users) for more
details.
<Alert color="warning">
Although local authentication is quick and easy to get started with, you can
limit attack surface by [disabling local
authentication](#disabling-local-authentication) altogether. See our
[OIDC](/docs/authenticate/oidc) or [SAML](/docs/authenticate/saml) guides for
details. For production deployments it's usually a good idea to **disable
local authentication** and enforce MFA through your identity provider.
</Alert>
If you choose to keep Local authentication enabled, we recommend
[enabling TOTP-based MFA ](/docs/authenticate/multi-factor) for any accounts
that use the local authentication method.
## Disabling local authentication
Local authentication can be enabled or disabled from the `/settings/security`
page or via the [REST API](/docs/reference/rest-api/configurations). If you've
disabled local authentication and can no longer authenticate to the portal to
re-enable it, see our
[troubleshooting guide ](/docs/administer/troubleshoot#re-enable-local-authentication-via-cli)
for re-enabling local authentication from the CLI.

12
website/src/app/docs/authenticate/multi-factor/page.tsx
View File

@@ -1,12 +0,0 @@
import Content from "./readme.mdx";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Multi-factor Authentication • Firezone Docs",
description:
"Enforce multi-factor authentication with Firezone's WireGuard®-based secure access platform.",
};
export default function Page() {
return <Content />;
}

33
website/src/app/docs/authenticate/multi-factor/readme.mdx
View File

@@ -1,33 +0,0 @@
# Multi-Factor Authentication
You have two options for activating MFA with Firezone:
1. Enable a TOTP-based second factor for the local email/password authentication
method.
1. Configure Firezone to SSO via one of our
[supported identity providers ](/docs/authenticate/#integrate-an-sso-provider)
and enable MFA through the identity provider.
## MFA with Firezone
Firezone currently supports using a time-based one time password (TOTP) as an
additional factor. This is supported with the local authentication method only;
for SSO authentication we recommend enabling your provider's MFA functionality
[as described below](#mfa-with-identity-provider).
Admins can visit `/settings/account/register_mfa` in the admin portal to
generate a QR code to be scanned by your authenticator app.
Unprivileged users can visit `/user_account/register_mfa` after logging into the
user portal.
## MFA with your identity provider
Most identity providers support additional authentication factors in addition to
email/password. Consult your provider's documentation to enforce an additional
factor. We have included links to a few common providers below:
- [Okta](https://help.okta.com/en-us/Content/Topics/Security/mfa/mfa-home.htm)
- [Azure AD](https://docs.microsoft.com/en-us/azure/active-directory/authentication/concept-mfa-howitworks)
- [Google](https://support.google.com/a/answer/175197)
- [Onelogin](https://www.onelogin.com/getting-started/free-trial-plan/add-mfa)

7
website/src/app/docs/authenticate/oidc/auth0/_page.tsx
View File

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

12
website/src/app/docs/authenticate/oidc/auth0/page.tsx
View File

@@ -1,12 +0,0 @@
import _Page from "./_page";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Auth0 OIDC • Firezone Docs",
description:
"Enforce 2FA/MFA for users of Firezone's WireGuard®-based secure access platform. This guide walks through integrating Auth0 for single sign-on using OpenID Connect (OIDC).",
};
export default function Page() {
return <_Page />;
}

88
website/src/app/docs/authenticate/oidc/auth0/readme.mdx
View File

@@ -1,88 +0,0 @@
import Image from "next/image";
# Enable SSO with Auth0 (OIDC)
Firezone supports Single Sign-On (SSO) using Auth0 through the generic OIDC
connector. This guide will walk you through how to obtain the following config
settings required for the integration:
1. **Config ID**: The provider's config ID. (e.g. `auth0`)
1. **Label**: The button label text that shows up on your Firezone login screen.
(e.g. `Auth0`)
1. **Scope**:
[OIDC scopes](https://openid.net/specs/openid-connect-basic-1_0.html#Scopes)
to obtain from your OIDC provider. This should be set to
`openid email profile` to provide Firezone with the user's email in the
returned claims.
1. **Response type**: Set to `code`.
1. **Client ID**: The client ID of the application.
1. **Client secret**: The client secret of the application.
1. **Discovery Document URI**: The
[OpenID Connect provider configuration URI](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig)
which returns a JSON document used to construct subsequent requests to this
OIDC provider.
## Step 1: Obtain OIDC configuration parameters
In the Auth0 dashboard, create an application. Select **Regular Web
Application** as the application type.
<Image
className="mx-auto"
alt="auth0 configuration"
src="/images/auth0-configuration.png"
width={960}
height={540}
/>
Next, visit the settings tab on the application details page. Take note and
modify the following parameters:
1. **Name**: `Firezone`
1. **Domain**: The domain will be used to construct the url to retrieve the OIDC
discovery document -
`https://<AUTH0_DOMAIN>/.well-known/openid-configuration`
1. **Icon**: [Firezone icon](/images/save-link-as-icon.png) (save link as).
1. Set **Allowed Callback URLs** to
`EXTERNAL_URL + /auth/oidc/<Config ID>/callback/` (e.g.
`https://firezone.example.com/auth/oidc/auth0/callback/`).
<Image
className="mx-auto"
alt="auth0 settings 1"
src="/images/auth0-settings-1.png"
width={960}
height={540}
/>
<Image
className="mx-auto"
alt="auth0 settings 2"
src="/images/auth0-settings-2.png"
width={960}
height={540}
/>
<Image
className="mx-auto"
alt="auth0 settings 3"
src="/images/auth0-settings-3.png"
width={960}
height={540}
/>
## Step 2: Integrate with Firezone
Navigate to the `/settings/security` page in the admin portal, click "Add OpenID
Connect Provider" and enter the details you obtained in the steps above.
Enable or disable the **Auto create users** option to automatically create an
unprivileged user when signing in via this authentication mechanism.
And that's it! The configuration should be updated immediately. You should now
see a `Sign in with Auth0` button on the sign in page.
## Step 3 (optional): Restrict access to specific users
Auth0 supports setting access policies to control which users can access the
Firezone application. See Auth0's
[Documentation](https://auth0.com/docs/manage-users/user-accounts/manage-user-access-to-applications)
for details.

7
website/src/app/docs/authenticate/oidc/azuread/_page.tsx
View File

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

12
website/src/app/docs/authenticate/oidc/azuread/page.tsx
View File

@@ -1,12 +0,0 @@
import _Page from "./_page";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Azure AD OIDC • Firezone Docs",
description:
"Enforce 2FA/MFA for users of Firezone's WireGuard®-based secure access platform. This guide walks through integrating Azure AD for single sign-on using OpenID Connect (OIDC).",
};
export default function Page() {
return <_Page />;
}

111
website/src/app/docs/authenticate/oidc/azuread/readme.mdx
View File

@@ -1,111 +0,0 @@
import Image from "next/image";
# Enable SSO with Azure Active Directory (OIDC)
Firezone supports Single Sign-On (SSO) using Azure Active Directory through the
generic generic OIDC connector. This guide will walk you through how to obtain
the following config settings required for the integration:
1. **Config ID**: The provider's config ID. (e.g. `azure`)
1. **Label**: The button label text that shows up on your Firezone login screen.
(e.g. `Azure`)
1. **Scope**:
[OIDC scopes](https://openid.net/specs/openid-connect-basic-1_0.html#Scopes)
to obtain from your OIDC provider. This should be set to
`openid email profile offline_access` to provide Firezone with the user's
email in the returned claims.
1. **Response type**: Set to `code`.
1. **Client ID**: The client ID of the application.
1. **Client secret**: The client secret of the application.
1. **Discovery Document URI**: The
[OpenID Connect provider configuration URI](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig)
which returns a JSON document used to construct subsequent requests to this
OIDC provider.
<Image
className="mx-auto"
alt="azure sso login"
src="/images/azure-sso-login.gif"
width={960}
height={540}
/>
## Step 1: Obtain configuration parameters
_This guide is adapted from the
[Azure Active Directory documentation](https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/auth-oidc)._
Navigate to the Azure Active Directory page on the Azure portal. Select the App
registrations link under the Manage menu, click `New Registration`, and register
after entering the following:
1. **Name**: `Firezone`
1. **Supported account types**: `(Default Directory only - Single tenant)`
1. **Redirect URI**: This should be your Firezone
`EXTERNAL_URL + /auth/oidc/<Config ID>/callback/` (e.g.
`https://firezone.example.com/auth/oidc/azure/callback/`). **Make sure you
include the trailing slash both when saving the provider in Firezone and in
Azure AD (`redirect_uri` field on the screenshot below).**
<Image
className="mx-auto"
alt="azure app registration"
src="/images/azure-app-registration.png"
width={960}
height={540}
/>
After registering, open the details view of the application and copy the
`Application (client) ID`. **This will be the `client_id` value**. Next, open
the endpoints menu to retrieve the `OpenID Connect metadata document`. **This
will be the `discovery_document_uri` value**.
<Image
className="mx-auto"
alt="azure client id"
src="/images/azure-client-id.png"
width={960}
height={540}
/>
Next, select the Certificates & secrets link under the Manage menu and create a
new client secret. Copy the client secret - **this will be the `client_secret`
value**.
<Image
className="mx-auto"
alt="azure client secret"
src="/images/azure-client-secret.png"
width={960}
height={540}
/>
Lastly, select the API permissions link under the Manage menu, click
`Add a permission`, and select `Microsoft Graph`. Add `email`, `openid`,
`offline_access` and `profile` to the required permissions.
<Image
className="mx-auto"
alt="azure permissions"
src="/images/azure-permissions.png"
width={960}
height={540}
/>
## Step 2: Integrate with Firezone
Navigate to the `/settings/security` page in the admin portal, click "Add OpenID
Connect Provider" and enter the details you obtained in the steps above.
Enable or disable the **Auto create users** option to automatically create an
unprivileged user when signing in via this authentication mechanism.
And that's it! The configuration should be updated immediately. You should now
see a `Sign in with Azure` button on the sign in page.
## Step 3 (optional): Restrict access to specific users
Azure AD allows admins to restrict OAuth application access to a subset of users
within your organization. See Microsoft's
[documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-restrict-your-app-to-a-set-of-users)
for more information on how to do this.

7
website/src/app/docs/authenticate/oidc/google/_page.tsx
View File

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

12
website/src/app/docs/authenticate/oidc/google/page.tsx
View File

@@ -1,12 +0,0 @@
import _Page from "./_page";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Google Workspace OIDC • Firezone Docs",
description:
"Enforce 2FA/MFA for users of Firezone's WireGuard®-based secure access platform. This guide walks through integrating Google Workspace for single sign-on using OpenID Connect (OIDC).",
};
export default function Page() {
return <_Page />;
}

120
website/src/app/docs/authenticate/oidc/google/readme.mdx
View File

@@ -1,120 +0,0 @@
import Image from "next/image";
# Enable SSO with Google Workspace (OIDC)
Firezone supports Single Sign-On (SSO) using Google Workspace and Cloud Identity
through the generic OIDC connector. This guide will walk you through how to
obtain the following config settings required for the integration:
1. **Config ID**: The provider's config ID. (e.g. `google`)
1. **Label**: The button label text that shows up on your Firezone login screen.
(e.g. `Google`)
1. **Scope**:
[OIDC scopes](https://openid.net/specs/openid-connect-basic-1_0.html#Scopes)
to obtain from your OIDC provider. This should be set to
`openid email profile` to provide Firezone with the user's email in the
returned claims.
1. **Response type**: Set to `code`.
1. **Client ID**: The client ID of the application.
1. **Client secret**: The client secret of the application.
1. **Discovery Document URI**: The
[OpenID Connect provider configuration URI](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig)
which returns a JSON document used to construct subsequent requests to this
OIDC provider.
<Image
className="mx-auto"
alt="firezone google sso login"
src="/images/firezone-google-sso-login.gif"
width={960}
height={540}
/>
## Step 1: Configure OAuth consent screen
If this is the first time you are creating a new OAuth client ID, you will be
asked to configure a consent screen.
**IMPORTANT**: Select `Internal` for user type. This ensures only accounts
belonging to users in your Google Workspace Organization can create device
configs. DO NOT select `External` unless you want to enable anyone with a valid
Google Account to create device configs.
<Image
className="mx-auto"
alt="oauth consent internal"
src="/images/oauth-consent-internal.png"
width={960}
height={540}
/>
On the App information screen:
1. **App name**: `Firezone`
1. **App logo**: [save link as](/images/save-logo.png).
1. **Application home page**: the URL of your Firezone instance.
1. **Authorized domains**: the top level domain of your Firezone instance.
<Image
className="mx-auto"
alt="oauth consent app info"
src="/images/oauth-consent-app-info.png"
width={960}
height={540}
/>
On the next step add the following scopes:
<Image
className="mx-auto"
alt="oauth consent scopes"
src="/images/oauth-consent-scopes.png"
width={960}
height={540}
/>
## Step 2: Create OAuth client
_This section is based off Google's own documentation on
[setting up OAuth 2.0](https://support.google.com/cloud/answer/6158849)._
Visit the Google Cloud Console
[Credentials page](https://console.cloud.google.com/apis/credentials) page,
click `+ Create Credentials` and select `OAuth client ID`.
<Image
className="mx-auto"
alt="create oauth client id"
src="/images/create-oauth-client-id.png"
width={960}
height={540}
/>
On the OAuth client ID creation screen:
1. Set `Application Type` to `Web application`
1. Add your Firezone `EXTERNAL_URL + /auth/oidc/<Config ID>/callback/` (e.g.
`https://firezone.example.com/auth/oidc/google/callback/`) as an entry to
Authorized redirect URIs.
<Image
className="mx-auto"
alt="create oauth client id"
src="/images/create-oauth-client-id-2.png"
width={960}
height={540}
/>
After creating the OAuth client ID, you will be given a Client ID and Client
Secret. These will be used together with the redirect URI in the next step.
## Step 3: Integrate with Firezone
Navigate to the `/settings/security` page in the admin portal, click "Add OpenID
Connect Provider" and enter the details you obtained in the steps above.
Enable or disable the **Auto create users** option to automatically create an
unprivileged user when signing in via this authentication mechanism.
And that's it! The configuration should be updated immediately. You should now
see a `Sign in with Google` button on the sign in page.

7
website/src/app/docs/authenticate/oidc/keycloak/_page.tsx
View File

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

12
website/src/app/docs/authenticate/oidc/keycloak/page.tsx
View File

@@ -1,12 +0,0 @@
import _Page from "./_page";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Keycloak OIDC • Firezone Docs",
description:
"Enforce 2FA/MFA for users of Firezone's WireGuard®-based secure access platform. This guide walks through integrating Keycloak for single sign-on using OpenID Connect (OIDC).",
};
export default function Page() {
return <_Page />;
}

113
website/src/app/docs/authenticate/oidc/keycloak/readme.mdx
View File

@@ -1,113 +0,0 @@
import Image from "next/image";
# Enable SSO with Keycloak (OIDC)
Firezone supports Single Sign-On (SSO) using Keycloak through the generic OIDC
provider. This guide will walk you through how to obtain the following config
settings required for the integration:
1. **Config ID**: The provider's config ID. (e.g. `keycloak`)
1. **Label**: The button label text that shows up on your Firezone login screen.
(e.g. `Keycloak`)
1. **Scope**:
[OIDC scopes](https://openid.net/specs/openid-connect-basic-1_0.html#Scopes)
to obtain from your OIDC provider. This should be set to
`openid email profile offline_access` to provide Firezone with the user's
email in the returned claims.
1. **Response type**: Set to `code`.
1. **Client ID**: The client ID of the application.
1. **Client secret**: The client secret of the application.
1. **Discovery Document URI**: The
[OpenID Connect provider configuration URI](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig)
which returns a JSON document used to construct subsequent requests to this
OIDC provider.
## Step 1: Obtain configuration parameters
In the Keycloak Admin Console, make sure the realm you want to use with Firezone
is selected.
<Image
className="mx-auto"
alt="keycloak realm"
src="/images/keycloak-realm.png"
width={960}
height={540}
/>
### Create Firezone OAuth client
Create a new Client for Firezone by navigating to **Clients > Create Client**
and configure the following:
1. **Client type**: `OpenID Connect`
1. **Client ID**: `firezone`
1. **Name**: `Firezone`
1. Click **Next**.
<Image
className="mx-auto"
alt="create firezone client"
src="/images/create-firezone-client.png"
width={960}
height={540}
/>
1. Toggle **Client authentication** to `On` to generate the client secret.
1. Click **Save**.
<Image
className="mx-auto"
alt="save firezone client"
src="/images/save-firezone-client.png"
width={960}
height={540}
/>
Click **Access settings** to jump to that section and configure the valid
redirect URI:
1. **Valid Redirect URIs**: This should be your Firezone
`EXTERNAL_URL + /auth/oidc/<Config ID>/callback/` (e.g.
`https://firezone.example.com/auth/oidc/keycloak/callback/`).
1. Click **Add valid redirect URIs**
<Image
className="mx-auto"
alt="firezone access settings"
src="/images/firezone-access-settings.png"
width={960}
height={540}
/>
Click the **Credentials** tab and copy the client secret.
<Image
className="mx-auto"
alt="firezone client secret"
src="/images/firezone-client-secret.png"
width={960}
height={540}
/>
Navigate to the **Realm Settings** page to get the **Discovery Document URI** by
copying the **OpenID Endpoint Configuration** link at the bottom of the page.
<Image
className="mx-auto"
alt="keycloak realm settings"
src="/images/keycloak-realm-settings.png"
width={960}
height={540}
/>
## Step 2: Integrate with Firezone
Navigate to the `/settings/security` page in the admin portal, click "Add OpenID
Connect Provider" and enter the details you obtained in the steps above.
Enable or disable the **Auto create users** option to automatically create an
unprivileged user when signing in via this authentication mechanism.
And that's it! The configuration should be updated immediately. You should now
see a `Sign in with Keycloak` button on the sign in page.

7
website/src/app/docs/authenticate/oidc/okta/_page.tsx
View File

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

12
website/src/app/docs/authenticate/oidc/okta/page.tsx
View File

@@ -1,12 +0,0 @@
import _Page from "./_page";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Okta OIDC • Firezone Docs",
description:
"Enforce 2FA/MFA for users of Firezone's WireGuard®-based secure access platform. This guide walks through integrating Okta for single sign-on using OpenID Connect (OIDC).",
};
export default function Page() {
return <_Page />;
}

110
website/src/app/docs/authenticate/oidc/okta/readme.mdx
View File

@@ -1,110 +0,0 @@
import Image from "next/image";
# Enable SSO with Okta (OIDC)
Firezone supports Single Sign-On (SSO) using Okta through the generic OIDC
connector. This guide will walk you through how to obtain the following config
settings required for the integration:
1. **Config ID**: The provider's config ID. (e.g. `okta`)
1. **Label**: The button label text that shows up on your Firezone login screen.
(e.g. `Okta`)
1. **Scope**:
[OIDC scopes](https://openid.net/specs/openid-connect-basic-1_0.html#Scopes)
to obtain from your OIDC provider. This should be set to
`openid email profile offline_access` to provide Firezone with the user's
email in the returned claims.
1. **Response type**: Set to `code`.
1. **Client ID**: The client ID of the application.
1. **Client secret**: The client secret of the application.
1. **Discovery Document URI**: The
[OpenID Connect provider configuration URI](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig)
which returns a JSON document used to construct subsequent requests to this
OIDC provider.
<Image
className="mx-auto"
alt="firezone okta sso login"
src="/images/firezone-okta-sso-login-2.gif"
width={960}
height={540}
/>
## Step 1: Create Okta app integration
_This section of the guide is based on
[Okta's documentation](https://help.okta.com/en/prod/Content/Topics/Apps/Apps_App_Integration_Wizard_OIDC.htm)._
In the Admin Console, go to **Applications > Applications** and click **Create
App Integration**. Set **Sign-in method** to **OICD - OpenID Connect** and
**Application type** to **Web application**.
<Image
className="mx-auto"
alt="okta create options"
src="/images/okta-create-options.png"
width={960}
height={540}
/>
On the following screen, configure the following settings:
1. **App Name**: `Firezone`
1. **App logo**: [save link as](/images/save-logo.png).
1. **Proof Key for Code Exchange (PKCE)**: Check
`Require PKCE as additional verification` if you're running Firezone 0.6.8 or
higher. [PKCE](https://oauth.net/2/pkce) is recommended for increased
security whenever possible.
1. **Grant Type**: Check the **Refresh Token** box. This ensures Firezone syncs
with the identity provider and VPN access is terminated once the user is
removed.
1. **Sign-in redirect URIs**: Add your Firezone
`EXTERNAL_URL + /auth/oidc/<Config ID>/callback/` (e.g.
`https://firezone.example.com/auth/oidc/okta/callback/`) as an entry to
Authorized redirect URIs.
1. **Assignments**: Limit to the groups you wish to provide access to your
Firezone instance.
<Image
className="mx-auto"
alt="okta settings"
src="/images/okta-settings.png"
width={960}
height={540}
/>
Once settings are saved, you will be given a **Client ID**, **Client Secret**,
and **Okta Domain**. These 3 values will be used in Step 2 to configure
Firezone.
<Image
className="mx-auto"
alt="okta credentials"
src="/images/okta-credentials.png"
width={960}
height={540}
/>
## Step 2: Integrate with Firezone
Navigate to the `/settings/security` page in the admin portal, click "Add OpenID
Connect Provider" and enter the details you obtained in the steps above.
Enable or disable the **Auto create users** option to automatically create an
unprivileged user when signing in via this authentication mechanism.
And that's it! The configuration should be updated immediately. You should now
see a `Sign in with Okta` button on the sign in page.
## Step 3 (optional): Restrict Access to specific users
Okta can limit the users with access to the Firezone app. To do this, go to the
Assignments tab of the Firezone App Integration in your Okta Admin Console.
<Image
className="mx-auto"
alt="okta assignments"
src="/images/okta-assignments.png"
width={960}
height={540}
/>

7
website/src/app/docs/authenticate/oidc/onelogin/_page.tsx
View File

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

12
website/src/app/docs/authenticate/oidc/onelogin/page.tsx
View File

@@ -1,12 +0,0 @@
import _Page from "./_page";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Onelogin OIDC • Firezone Docs",
description:
"Enforce 2FA/MFA for users of Firezone's WireGuard®-based secure access platform. This guide walks through integrating Onelogin for single sign-on using OpenID Connect (OIDC).",
};
export default function Page() {
return <_Page />;
}

70
website/src/app/docs/authenticate/oidc/onelogin/readme.mdx
View File

@@ -1,70 +0,0 @@
import Image from "next/image";
# Enable SSO with OneLogin (OIDC)
Firezone supports Single Sign-On (SSO) using OneLogin through the generic OIDC
connector. This guide will walk you through how to obtain the following config
settings required for the integration:
1. **Config ID**: The provider's config ID. (e.g. `onelogin`)
1. **Label**: The button label text that shows up on your Firezone login screen.
(e.g. `OneLogin`)
1. **Scope**:
[OIDC scopes](https://openid.net/specs/openid-connect-basic-1_0.html#Scopes)
to obtain from your OIDC provider. This should be set to
`openid email profile` to provide Firezone with the user's email in the
returned claims.
1. **Response type**: Set to `code`.
1. **Client ID**: The client ID of the application.
1. **Client secret**: The client secret of the application.
1. **Discovery Document URI**: The
[OpenID Connect provider configuration URI](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig)
which returns a JSON document used to construct subsequent requests to this
OIDC provider.
## Step 1: Create custom connector
Create a new OIDC connector by visiting **Appliances > Custom Connectors**.
1. **App name**: `Firezone`
1. **Icon**: [icon](/images/save-link-as-icon.png) and
[logo](/images/save-logo.png).
1. **Sign on method**: select **OpenID Connect**
1. **Redirect URI**: Add your Firezone
`<EXTERNAL_URL> + /auth/oidc/<Config ID>/callback/` (e.g.
`https://firezone.example.com/auth/oidc/onelogin/callback/`).
<Image
className="mx-auto"
alt="onelogin configuration"
src="/images/onelogin-configuration.png"
width={960}
height={540}
/>
## Step 2: Obtain configuration parameters
Next, click **Add App to Connector** to create an OIDC application. Visit the
**SSO** tab, then change the token endpoint authentication method to **POST**.
You will find the values for the config settings required by Firezone on this
page as well.
<Image
className="mx-auto"
alt="onelogin config parameters"
src="/images/onelogin-config-parameters.png"
width={960}
height={540}
/>
## Step 3: Integrate with Firezone
Navigate to the `/settings/security` page in the admin portal, click "Add OpenID
Connect Provider" and enter the details you obtained in the steps above.
Enable or disable the **Auto create users** option to automatically create an
unprivileged user when signing in via this authentication mechanism.
And that's it! The configuration should be updated immediately. You should now
see a `Sign in with OneLogin` button on the sign in page.

12
website/src/app/docs/authenticate/oidc/page.tsx
View File

@@ -1,12 +0,0 @@
import Content from "./readme.mdx";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "OpenID Connect • Firezone Docs",
description:
"Setup single sign-on with your identity provider. Integrate providers like Okta, Google, Azure, and JumpCloud using Firezone's OpenID Connect (OIDC) connector.",
};
export default function Page() {
return <Content />;
}

63
website/src/app/docs/authenticate/oidc/readme.mdx
View File

@@ -1,63 +0,0 @@
# Integrate your identity provider using OIDC
Firezone supports Single Sign-On (SSO) via OpenID Connect (OIDC).
## Supported identity providers
In general, most identity providers that offer OIDC support work with Firezone.
Some providers that only implement the OIDC partially or use uncommon
configurations may have issues, however. If your identity provider falls into
this category, [contact us](/contact/sales) about a custom integration.
The following OIDC providers are known to work well with Firezone:
| Provider | Support Status | Notes |
| --------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Azure Active Directory](/docs/authenticate/oidc/azuread) | **Fully tested and supported** | Ensure the [`email` claim](https://learn.microsoft.com/en-us/azure/active-directory/develop/active-directory-optional-claims) is present in the token. |
| [Okta](/docs/authenticate/oidc/okta) | **Fully tested and supported** | |
| [Onelogin](/docs/authenticate/oidc/onelogin) | **Fully tested and supported** | |
| [Keycloak](/docs/authenticate/oidc/keycloak) | **Fully tested and supported** | |
| [Auth0](/docs/authenticate/oidc/auth0) | **Fully tested and supported** | Auth0 does not provide an `end_session_uri` in its OIDC discovery document. Signing out of Auth0 from Firezone is not supported. |
| [Google Workspace](/docs/authenticate/oidc/google) | **Fully tested and supported** | Google does not provide an `end_session_uri` in its OIDC discovery document. Signing out of Google Workspace from Firezone is not supported. |
| [Zitadel](/docs/authenticate/oidc/zitadel) | Untested but known to work | |
| [Authentik](https://goauthentik.io) | Untested but known to work | |
## General setup guide
If you're using an OIDC provider not listed above, the following OIDC attributes
are required for setting up an OIDC provider in Firezone:
1. `discovery_document_uri`: The
[OpenID Connect provider configuration URI](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig)
which returns a JSON document used to construct subsequent requests to this
OIDC provider. Some providers refer to this as the "well-known URL".
1. `client_id`: The client ID of the application.
1. `client_secret`: The client secret of the application.
1. `redirect_uri`: Instructs OIDC provider where to redirect after
authentication. This should be your Firezone
`EXTERNAL_URL + /auth/oidc/<provider_key>/callback/` (e.g.
`https://firezone.example.com/auth/oidc/google/callback/`).
1. `response_type`: Set to `code`.
1. `scope`:
[OIDC scopes](https://openid.net/specs/openid-connect-basic-1_0.html#Scopes)
to obtain from your OIDC provider. At a minimum, Firezone requires the
`openid` and `email` scopes.
1. `label`: The button label text displayed on the Firezone portal login page.
### PKCE
Firezone supports Proof Key for Code Exchange (PKCE) for increased login
security. We recommend you enable PKCE in your IdP's settings whenever
available. [Read more about PKCE here](https://oauth.net/2/pkce).
### OIDC logout URI
The OpenID Connect standard
[defines a mechanism](https://openid.net/specs/openid-connect-rpinitiated-1_0.html)
for a Relying Party (RP) to request that an OpenID Provider log out the
End-User.
Unfortunately, not all IdPs support this (e.g. Google, Auth0). For the providers
that do support this mechanism, Firezone automatically detects the
`end_session_uri` found in the provider's discovery document and uses that to
log out the End-User.

7
website/src/app/docs/authenticate/oidc/zitadel/_page.tsx
View File

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

12
website/src/app/docs/authenticate/oidc/zitadel/page.tsx
View File

@@ -1,12 +0,0 @@
import _Page from "./_page";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Zitadel OIDC • Firezone Docs",
description:
"Enforce 2FA/MFA for users of Firezone's WireGuard®-based secure access platform. This guide walks through integrating Zitadel for single sign-on using OpenID Connect (OIDC).",
};
export default function Page() {
return <_Page />;
}

159
website/src/app/docs/authenticate/oidc/zitadel/readme.mdx
View File

@@ -1,159 +0,0 @@
import Image from "next/image";
# Enable SSO with Zitadel (OIDC)
Firezone supports Single Sign-On (SSO) using Zitadel through the generic OIDC
connector. This guide will walk you through how to obtain the following config
settings required for the integration:
1. **Config ID**: The provider's config ID. (e.g. `zitadel`)
1. **Label**: The button label text that shows up on your Firezone login screen.
(e.g. `Zitadel`)
1. **Scope**:
[OIDC scopes](https://openid.net/specs/openid-connect-basic-1_0.html#Scopes)
to obtain from your OIDC provider. This should be set to
`openid email profile offline_access` to provide Firezone with the user's
email in the returned claims.
1. **Response type**: Set to `code`.
1. **Client ID**: The client ID of the application.
1. **Client secret**: The client secret of the application.
1. **Discovery Document URI**: The
[OpenID Connect provider configuration URI](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig)
which returns a JSON document used to construct subsequent requests to this
OIDC provider.
<Image
className="mx-auto"
alt="firezone zitadel sso login"
src="/images/firezone-sso-zitadel-login.gif"
width={960}
height={540}
/>
## Requirements
- Set up your own [Zitadel Cloud](https://zitadel.com) account.
- Create your first Zitadel instance in the
[Zitadel Customer portal](https://zitadel.com/signin)
- Login to your Zitadel instance and create a project (i.e. "Internal")
More information about these steps can be found in
[Zitadel's documentation](https://zitadel.com/docs/guides/start/quickstart).
## Create Zitadel Application
In the Instance Console, go to **Projects** and select the project you want,
then click **New**.
<Image
className="mx-auto"
alt="zitadel new application"
src="/images/zitadel-new-application.png"
width={960}
height={540}
/>
Give the application a name (e.g. "Firezone") and select **WEB** for the
application type.
<Image
className="mx-auto"
alt="zitadel name application"
src="/images/zitadel-name-application.png"
width={960}
height={540}
/>
Select **CODE** for the authentication method.
<Image
className="mx-auto"
alt="zitadel auth method"
src="/images/zitadel-auth-method.png"
width={960}
height={540}
/>
Specify the redirect URI and post logout URI.
1. **Redirect URIs**: `EXTERNAL_URL + /auth/oidc/<Config ID>/callback/` (e.g.
`https://vpn.example.com/auth/oidc/zitadel/callback/`)
1. **Post Logout URIs**: `EXTERNAL_URL` (e.g. `https://vpn.example.com`)
<Image
className="mx-auto"
alt="zitadel uri"
src="/images/zitadel-uri.png"
width={960}
height={540}
/>
Double-check the configuration, then click **Create**.
<Image
className="mx-auto"
alt="zitadel configuration overview"
src="/images/zitadel-configuration-overview.png"
width={960}
height={540}
/>
Copy the **ClientId** and **ClientSecret** as it will be used for the Firezone
configuration.
<Image
className="mx-auto"
alt="zitadel client creds"
src="/images/zitadel-client-creds.png"
width={960}
height={540}
/>
In the application **Configuration** click **Refresh Token** and then on
**Save**. The refresh token is optional for some features of Firezone.
<Image
className="mx-auto"
alt="zitadel configuration"
src="/images/zitadel-configuration.png"
width={960}
height={540}
/>
In the application **Token Settings** select **User roles inside ID Token** and
**User Info inside ID Token**. Save it with a click on **Save**.
<Image
className="mx-auto"
alt="zitadel token settings"
src="/images/zitadel-token-settings.png"
width={960}
height={540}
/>
![Application Token Settings]()
## Integrate With Firezone
Navigate to the `/settings/security` page in the admin portal, click "Add OpenID
Connect Provider" and enter the details you obtained in the steps above.
Enable or disable the **Auto create users** option to automatically create an
unprivileged user when signing in via this authentication mechanism.
And that's it! The configuration should be updated immediately. You should now
see a `Sign in with Zitadel` button on the sign in page.
## Step 3 (optional): Restrict access to specific users
Zitadel can limit which users have access to Firezone. To do this, go to the
project where your created your application. In **General** you can find **Check
Authorization on Authentication** which allows only users with at least one role
to login to Firezone.
<Image
className="mx-auto"
alt="zitadel check authorization"
src="/images/zitadel-check-authorization.png"
width={960}
height={540}
/>

11
website/src/app/docs/authenticate/page.tsx
View File

@@ -1,11 +0,0 @@
import _Page from "./_page";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Authenticate • Firezone Docs",
description: "Authenticating with Firezone.",
};
export default function Page() {
return <_Page />;
}

96
website/src/app/docs/authenticate/readme.mdx
View File

@@ -1,96 +0,0 @@
import Alert from "@/components/DocsAlert";
import SupportOptions from "@/components/SupportOptions";
import Image from "next/image";
# User Authentication
Firezone supports the following authentication methods:
1. [Local email/password (default)](/docs/authenticate/local-auth)
1. [SSO authentication via OpenID Connect](/docs/authenticate/oidc)
1. [SSO authentication via SAML 2.0](/docs/authenticate/saml)
<Alert color="info">
If your Identity Provider doesn't work with the methods listed above, [contact
us](/contact/sales) about a custom integration.
</Alert>
## Integrate an SSO provider
We've included instructions on how to set up Firezone with several popular
identity providers using our Generic OIDC integration:
- [Okta](/docs/authenticate/oidc/okta)
- [Azure Active Directory](/docs/authenticate/oidc/azuread)
- [Google](/docs/authenticate/oidc/google)
- [Onelogin](/docs/authenticate/oidc/onelogin)
- [JumpCloud](/docs/authenticate/saml/jumpcloud)
- [Keycloak](/docs/authenticate/oidc/keycloak)
- [Zitadel](/docs/authenticate/oidc/zitadel)
- [Auth0](/docs/authenticate/oidc/auth0)
If your identity provider is not listed above, but has a generic OIDC or SAML
connector, please consult their documentation to find instructions on obtaining
the configuration settings required. Instructions for setting up Firezone with
any generic OIDC provider can be found [here](/docs/authenticate/oidc).
Open a [Github issue](https://github.com/firezone/firezone/issues) to request
documentation or submit a pull request to add documentation for your provider.
### The OIDC redirect URI
For each OIDC provider a corresponding URL is created for redirecting to the
configured provider's sign-in URL. The URL format is
`https://firezone.example.com/auth/oidc/CONFIG_ID` where `CONFIG_ID` is the OIDC
Config ID for that particular provider.
For example, the OIDC config below:
<center>
<Image
className="mx-auto"
width={509}
height={509}
alt="config-oidc"
src="/images/config-oidc.png"
/>
</center>
would generate the following OIDC login URL:
- `https://firezone.example.com/auth/oidc/google`
This URL could then be distributed to end users for direct navigation to the
identity provider's login portal for authentication to Firezone.
## Enforce periodic re-authentication
Periodic re-authentication can be enforced by changing the setting in
`settings/security`. This can be used to ensure a user must sign in to Firezone
periodically in order to maintain their VPN session.
You can set the session length to a minimum of **1 hour** and maximum of **90
days**. Setting this to Never disables this setting, allowing VPN sessions
indefinitely. This is the default.
### Re-authentication
To re-authenticate an expired VPN session, a user will need to turn off their
VPN session and sign in to the Firezone portal (URL specified during
[deployment](/docs/deploy/#prepare-to-deploy)).
See detailed Client Instructions on how to re-authenticate your session
[here](/docs/user-guides/client-instructions).
#### VPN connection status
A user's connection status is shown on the Users page under the table column
`VPN Connection`. The connection statuses are:
- ENABLED - The connection is enabled.
- DISABLED - The connection is disabled by an administrator or OIDC refresh
failure.
- EXPIRED - The connection is disabled due to authentication expiration or a
user has not signed in for the first time.
<SupportOptions />

7
website/src/app/docs/authenticate/saml/google/_page.tsx
View File

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

12
website/src/app/docs/authenticate/saml/google/page.tsx
View File

@@ -1,12 +0,0 @@
import _Page from "./_page";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Google Workspace SAML • Firezone Docs",
description:
"Enforce 2FA/MFA for users of Firezone's WireGuard®-based secure access platform. This guide walks through integrating Google Workspace for single sign-on using the SAML 2.0 connector.",
};
export default function Page() {
return <_Page />;
}

61
website/src/app/docs/authenticate/saml/google/readme.mdx
View File

@@ -1,61 +0,0 @@
import Image from "next/image";
# Enable SSO with Google Workspace (SAML 2.0)
Firezone supports Single Sign-On (SSO) using Google through the generic SAML 2.0
connector. This guide will walk you through how to configure the integration.
## Step 1: Create a SAML connector
In the Google Workspace admin portal, create a new SAML app under the
Application > Web and mobile apps tab. Use the following config values during
setup:
| Setting | Value |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| App name | Firezone |
| App icon | [save link as](/images/save-link-as-icon.png) |
| ACS URL | This is your Firezone `EXTERNAL_URL/auth/saml/sp/consume/:config_id` (e.g., `https://firezone.company.com/auth/saml/sp/consume/google`). |
| Entity ID | This should be the same as your Firezone `SAML_ENTITY_ID`, defaults to `urn:firezone.dev:firezone-app`. |
| Signed response | Unchecked. |
| Name ID format | Unspecified |
| Name ID | Basic Information > Primary email |
<Image
className="mx-auto"
alt="google saml"
width={960}
height={540}
src="/images/google-saml.png"
/>
Once complete, save the changes and download the SAML metadata document. You'll
need to copy-paste the contents of this document into the Firezone portal in the
next step.
## Step 2: Add SAML identity provider to Firezone
In the Firezone portal, add a SAML identity provider under the Security tab by
filling out the following information:
| Setting | Value | Notes |
| ------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Config ID | google | Firezone uses this value to construct endpoints required in the SAML authentication flow (e.g., receiving assertions, login requests). |
| Label | Google | Appears on the sign in button for authentication. |
| Metadata | see note | Paste the contents of the SAML metadata document you downloaded in the previous step from Google. |
| Sign assertions | Checked. | |
| Sign metadata | Checked. | |
| Require signed assertions | Checked. | |
| Require signed envelopes | **Unchecked.** | |
| Auto create users | Default `false` | Enable this setting to automatically create users when signing in with this connector for the first time. Disable to manually create users. |
<Image
className="mx-auto"
alt="firezone saml"
width={960}
height={540}
src="/images/firezone-saml-3.png"
/>
After saving the SAML config, you should see a `Sign in with Google` button on
your Firezone portal sign-in page.

7
website/src/app/docs/authenticate/saml/jumpcloud/_page.tsx
View File

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

12
website/src/app/docs/authenticate/saml/jumpcloud/page.tsx
View File

@@ -1,12 +0,0 @@
import _Page from "./_page";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Jumpcloud SAML • Firezone Docs",
description:
"Enforce 2FA/MFA for users of Firezone's WireGuard®-based secure access platform. This guide walks through integrating Jumpcloud for single sign-on using the SAML 2.0 connector.",
};
export default function Page() {
return <_Page />;
}

81
website/src/app/docs/authenticate/saml/jumpcloud/readme.mdx
View File

@@ -1,81 +0,0 @@
import Alert from "@/components/DocsAlert";
import Image from "next/image";
# Enable SSO with JumpCloud (SAML 2.0)
<Alert color="info">
This guide assumes you have completed the prerequisite steps (e.g. generate
self-signed X.509 certificates) outlined
<a href="/docs/authenticate/saml#prerequisites">here</a>.
</Alert>
Firezone supports Single Sign-On (SSO) using JumpCloud through the generic SAML
2.0 connector. This guide will walk you through how to configure the
integration.
## Step 1: Create a SAML connector
In the JumpCloud admin portal, create a new App under the SSO tab. At the bottom
of the popup window, click `Custom SAML App`.
After entering your desired value for `Display Label`, click the `SSO` tab, then
use the following configuration values:
| Setting | Value |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| IdP Entity ID | Any unique string will work, e.g. `firezone-jumpcloud`. |
| SP Entity ID | This should be the same as your Firezone `SAML_ENTITY_ID`, defaults to `urn:firezone.dev:firezone-app`. |
| ACS URL | This is your Firezone `EXTERNAL_URL/auth/saml/sp/consume/:config_id`, e.g. `https://firezone.company.com/auth/saml/sp/consume/jumpcloud`. |
| SAMLSubject NameID | `email` |
| SAMLSubject NameID Format | Leave at the default. |
| Signature Algorithm | `RSA-SHA256` |
| Sign Assertion | **Checked**. |
| Login URL | This is your Firezone `EXTERNAL_URL/auth/saml/auth/signin/:config_id`, e.g. `https://firezone.company.com/auth/saml/auth/signin/jumpcloud` |
Leave the rest of the settings unchanged, then click the `activate` button at
the bottom-right.
Your JumpCloud configuration should now resemble the following:
<Image
className="mx-auto"
alt="jumpcloud saml"
width={960}
height={540}
src="/images/jumpcloud-saml.png"
/>
Now, download the IdP Metadata document by selecting the App you just created
and then clicking the `export metadata` button in the upper-right. You'll need
to copy-paste the contents of this document into the Firezone portal in the next
step.
## Step 2: Add SAML identity provider to Firezone
In the Firezone portal, add a SAML identity provider under the Security tab by
filling out the following information:
| Setting | Value | Notes |
| ------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Config ID | `jumpcloud` | Firezone uses this value to construct endpoints required in the SAML authentication flow (e.g., receiving assertions, login requests). |
| Label | `JumpCloud` | Appears on the sign in button for authentication. |
| Base URL | Leave unchanged. | |
| Metadata | see note | Copy-paste the contents of the SAML metadata document you downloaded in the previous step from JumpCloud. |
| Sign assertions | Checked. | |
| Sign metadata | Checked. | |
| Require signed assertions | Checked. | |
| Require signed envelopes | **Unchecked.** | |
| Auto create users | Default `false` | Enable this setting to automatically create users when signing in with this connector for the first time. Disable to manually create users. |
Your Firezone configuration should now resemble the following:
<Image
className="mx-auto"
alt="firezone saml"
width={960}
height={540}
src="/images/firezone-saml.png"
/>
After saving the SAML config, you should see a `Sign in with JumpCloud` button
on your Firezone portal sign-in page.

5
website/src/app/docs/authenticate/saml/okta/_page.tsx
View File

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

12
website/src/app/docs/authenticate/saml/okta/page.tsx
View File

@@ -1,12 +0,0 @@
import _Page from "./_page";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Okta SAML • Firezone Docs",
description:
"Enforce 2FA/MFA for users of Firezone's WireGuard®-based secure access platform. This guide walks through integrating Okta for single sign-on using the SAML 2.0 connector.",
};
export default function Page() {
return <_Page />;
}

71
website/src/app/docs/authenticate/saml/okta/readme.mdx
View File

@@ -1,71 +0,0 @@
import Image from "next/image";
import Alert from "@/components/DocsAlert";
# Enable SSO with Okta (SAML 2.0)
<Alert color="info">
This guide assumes you have completed the prerequisite steps (e.g. generate
self-signed X.509 certificates) outlined
[here](/docs/authenticate/saml#prerequisites).
</Alert>
Firezone supports Single Sign-On (SSO) using Okta through the generic SAML 2.0
connector. This guide will walk you through how to configure the integration.
## Step 1: Create a SAML connector
In the Okta admin portal, create a new app integration under the Application
tab. Select `SAML 2.0` as the authentication method. Use the following config
values during setup:
| Setting | Value |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| App name | Firezone |
| App logo | [save link as](/images/save-logo.png) |
| Single sign on URL | This is your Firezone `EXTERNAL_URL/auth/saml/sp/consume/:config_id` (e.g., `https://firezone.company.com/auth/saml/sp/consume/okta`). |
| Audience (EntityID) | This should be the same as your Firezone `SAML_ENTITY_ID`, defaults to `urn:firezone.dev:firezone-app`. |
| Name ID format | EmailAddress |
| Application username | Email |
| Update application username on | Create and update |
[Okta's documentation](https://help.okta.com/oie/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_SAML.htm)
contains additional details on the purpose of each configuration setting.
<Image
className="mx-auto"
src="/images/okta-saml.png"
width={960}
height={540}
alt="onelogin saml"
/>
After creating the SAML connector, visit the `View SAML setup instructions` link
in the Sign On tab to download the metadata document. You'll need to copy-paste
the contents of this document into the Firezone portal in the next step.
## Step 2: Add SAML identity provider to Firezone
In the Firezone portal, add a SAML identity provider under the Security tab by
filling out the following information:
| Setting | Value | Notes |
| ------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Config ID | Okta | Used to construct endpoints required in the SAML authentication flow (e.g., receiving assertions, login requests). |
| Label | Okta | Appears on the sign in button for authentication. |
| Metadata | see note | Paste the contents of the SAML metadata document you downloaded in the previous step from Okta. |
| Sign assertions | Checked. | |
| Sign metadata | Checked. | |
| Require signed assertions | Checked. | |
| Require signed envelopes | Checked. | |
| Auto create users | Default `false` | Enable this setting to automatically create users when signing in with this connector for the first time. Disable to manually create users. |
<Image
className="mx-auto"
alt="firezone saml"
width={960}
height={540}
src="/images/firezone-saml-2.png"
/>
After saving the SAML config, you should see a `Sign in with Okta` button on
your Firezone portal sign-in page.

7
website/src/app/docs/authenticate/saml/onelogin/_page.tsx
View File

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

12
website/src/app/docs/authenticate/saml/onelogin/page.tsx
View File

@@ -1,12 +0,0 @@
import _Page from "./_page";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Onelogin SAML • Firezone Docs",
description:
"Enforce 2FA/MFA for users of Firezone's WireGuard®-based secure access platform. This guide walks through integrating Onelogin for single sign-on using the SAML 2.0 connector.",
};
export default function Page() {
return <_Page />;
}

75
website/src/app/docs/authenticate/saml/onelogin/readme.mdx
View File

@@ -1,75 +0,0 @@
import Alert from "@/components/DocsAlert";
import Image from "next/image";
# Enable SSO with OneLogin (SAML 2.0)
<Alert color="info">
This guide assumes you have completed the prerequisite steps (e.g. generate
self-signed X.509 certificates) outlined
[here](/docs/authenticate/saml#prerequisites).
</Alert>
Firezone supports Single Sign-On (SSO) using OneLogin through the generic SAML
2.0 connector. This guide will walk you through how to configure the
integration.
## Step 1: Create a SAML connector
In the OneLogin admin portal, add an app under the application tab. Select
`SAML Custom Connector (Advanced)` and provide the appropriate configuration
settings under the under the configuration tab.
The following fields should be filled out on this page:
| Setting | Value |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Audience (EntityID) | This should be the same as your Firezone `SAML_ENTITY_ID`, defaults to `urn:firezone.dev:firezone-app`. |
| Recipient | This is your Firezone `EXTERNAL_URL/auth/saml/sp/consume/:config_id` (e.g., `https://firezone.company.com/auth/saml/sp/consume/onelogin`). |
| ACS URL Validator | This field is regex to ensure OneLogin posts the response to the correct URL. For the sample URL below, we can use `^https:\/\/firezone\.company\.com\/auth\/saml\/sp\/consume\/onelogin` |
| ACS URL | This is your Firezone `EXTERNAL_URL/auth/saml/sp/consume/:config_id` (e.g., `https://firezone.company.com/auth/saml/sp/consume/onelogin`). |
| Login URL | This is your Firezone `EXTERNAL_URL/auth/saml/auth/signin/:config_id` (e.g., `https://firezone.company.com/auth/saml/sp/consume/onelogin`). |
| SAML initiator | Service Provider |
| SAML signature element | Both |
| Encrypt Assertion | Checked. |
[OneLogin's docs](https://onelogin.service-now.com/support?id=kb_article&sys_id=912bb23edbde7810fe39dde7489619de&kb_category=93e869b0db185340d5505eea4b961934)
provide a good overview of each field's purpose.
<Image
className="mx-auto"
alt="onelogin configs"
width={960}
height={540}
src="/images/onelogin-configs.png"
/>
Once complete, save the changes and download the SAML metadata document found
unde the `More Actions` dropdown. You'll need to copy-paste the contents of this
document into the Firezone portal in the next step.
## Step 2: Add SAML identity provider to Firezone
In the Firezone portal, add a SAML identity provider under the Security tab by
filling out the following information:
| Setting | Value | Notes |
| ------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Config ID | `onelogin` | Used to construct endpoints required in the SAML authentication flow (e.g., receiving assertions, login requests). |
| Label | `OneLogin` | Appears on the sign in button for authentication. |
| Metadata | see note | Paste the contents of the SAML metadata document you downloaded in the previous step from OneLogin. |
| Sign assertions | Checked. | |
| Sign metadata | Checked. | |
| Require signed assertions | Checked. | |
| Require signed envelopes | Checked. | |
| Auto create users | Default `false` | Enable this setting to automatically create users when signing in with this connector for the first time. Disable to manually create users. |
<Image
className="mx-auto"
alt="onelogin saml"
width={960}
height={540}
src="/images/onelogin-saml.png"
/>
After saving the SAML config, you should see a `Sign in with OneLogin` button on
your Firezone portal sign-in page.

12
website/src/app/docs/authenticate/saml/page.tsx
View File

@@ -1,12 +0,0 @@
import Content from "./readme.mdx";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "SAML 2.0 • Firezone Docs",
description:
"Enforce single sign-on with your identity provider. Integrate providers like Okta, Google, OneLogin, and JumpCloud using Firezone's SAML 2.0 connector.",
};
export default function Page() {
return <Content />;
}

91
website/src/app/docs/authenticate/saml/readme.mdx
View File

@@ -1,91 +0,0 @@
import { TabsGroup, TabsItem } from "@/components/Tabs";
# Integrate your identity provider using SAML 2.0
Firezone supports Single Sign-On (SSO) via SAML 2.0.
## Supported identity providers
In general, most identity providers that support SAML 2.0 should work with
Firezone.
| Provider | Support Status | Notes |
| -------------------------------------------------- | ------------------------ | ---------------------------------- |
| [Okta](/docs/authenticate/saml/okta) | **Tested and supported** | |
| [Google Workspace](/docs/authenticate/saml/google) | **Tested and supported** | Uncheck `Require signed envelopes` |
| [OneLogin](/docs/authenticate/saml/onelogin) | **Tested and supported** | |
| [JumpCloud](/docs/authenticate/saml/jumpcloud) | **Tested and supported** | Uncheck `Require signed envelopes` |
Occasionally, providers that don't implement the full SAML 2.0 standard or use
uncommon configurations may be problematic. If this is the case,
[contact us](/contact/sales) about a custom integration.
## Custom SAML cert and keyfile
SAML 2.0 requires a set of private and public keys using the RSA or DSA
algorithms along with an X.509 certificate that contains the public key.
Firezone automatically generates these for on both Docker and Omnibus-based
deployments. If you'd like to use your own cert and key, however, you can
generate them with `openssl`:
```bash
openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout saml.key -out saml.crt
```
Then use them with your Firezone installation:
<TabsGroup>
<TabsItem title="Docker" active>
Set the `SAML_KEYFILE_PATH` and `SAML_CERTFILE_PATH` environment variables to
the path containing your `saml.key` and `saml.crt` above. If using our
[example docker compose file](https://github.com/firezone/firezone/blob/legacy/docker-compose.prod.yml),
which includes a volume for mapping configuration, save these files to
`$HOME/.firezone/firezone` on the Docker host and set the
`SAML_KEYFILE_PATH=/var/firezone/saml.key` and
`SAML_CERTFILE_PATH=/var/firezone/saml.crt` environment variables for the
Firezone container.
</TabsItem>
<TabsItem title="Omnibus">
Set the following attributes in your `/etc/firezone/firezone.rb` configuration
file:
```ruby
default['firezone']['authentication']['saml']['key'] = '/path/to/your/saml.key'
default['firezone']['authentication']['saml']['cert'] = '/path/to/your/saml.crt'
```
and run `firezone-ctl reconfigure` to pick up the changes.
</TabsItem>
</TabsGroup>
## General setup instructions
Once you've configured Firezone with an X.509 certificate and corresponding
private key as shown above, you'll need a few more things to set up a generic
SAML integration.
### IdP metadata document
You'll need to get the SAML Metadata XML document from your identity provider.
In most cases this can be downloaded from your IdP's SAML App configuration
dashboard.
### ACS URL
Firezone constructs the ACS URL based on the Base URL and Configuration ID
entered in the Firezone SAML configuration, defaulting to:
`EXTERNAL_URL/auth/saml/sp/consume/:config_id`, e.g.
`https://firezone.company.com/auth/saml/sp/consume/okta`.
### Entity ID
The Firezone Entity ID can be configured with the `SAML_ENTITY_ID` environment
variable and defaults to `urn:firezone.dev:firezone-app` if not set.
See the [environment variable reference](/docs/reference/env-vars) for more
information.

6
website/src/app/docs/banner.mdx
View File

@@ -1,6 +0,0 @@
import Alert from "@/components/DocsAlert";
<Alert color="danger">
You're viewing documentation for the legacy version of Firezone, now
End-of-Life. [View the latest docs here](/kb).
</Alert>

11
website/src/app/docs/deploy/advanced/build-from-source/page.tsx
View File

@@ -1,11 +0,0 @@
import Content from "./readme.mdx";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Build From Source • Firezone Docs",
description: "How to build Firezone from source.",
};
export default function Page() {
return <Content />;
}

94
website/src/app/docs/deploy/advanced/build-from-source/readme.mdx
View File

@@ -1,94 +0,0 @@
import Alert from "@/components/DocsAlert";
# Build From Source
Building from source allows you to bring Firezone to unsupported platforms.
<Alert color="warning">
You're entering unsupported territory. This is not for the faint of heart and
will require being able to figure out snags you may hit on your own. If you're
very comfortable with your environment of choice, then read on to learn how to
build Firezone from source.
</Alert>
<Alert color="info">
You will need to setup your own service management for Firezone (eg. runit,
systemd, shell scripts). You will also need to install and configure your own
database (eg. postgres) and reverse proxy (eg. caddy, nginx). Info about
database configuration is
[here](/docs/deploy/advanced/external-database/#configure-firezone-to-connect),
and info about configuring a reverse proxy is
[here](/docs/deploy/advanced/reverse-proxy/#proxy-requirements).
</Alert>
## Prerequisites
<Alert color="info">
Check the `.tool-versions` file
[here](https://github.com/firezone/firezone/blob/legacy/.tool-versions) for
the versions we use for Erlang, Elixir, and Node. If your system supports it,
you can install these using
[asdf-vm](https://asdf-vm.com/guide/getting-started.html) using a similar
`.tool-versions` of your own to match versions. Your system's package manager
may have them as well.
</Alert>
**These must be available in the user's path that runs Firezone.**
- [Erlang/OTP](https://www.erlang.org)
- [Elixir](https://elixir-lang.org)
- [NodeJS](https://nodejs.org)
## Steps
From your terminal, run these steps to build Firezone:
```bash
git clone https://github.com/firezone/firezone
cd firezone
mix local.rebar --force
mix local.hex --force
MIX_ENV=prod mix deps.get
MIX_ENV=prod mix release
```
After the release build finishes, you should have a shiny new Firezone release
artifact in `<CURRENT_DIR>/_build/dev/rel/firezone`. In the `bin` folder, the
`firezone` binary can be used to start up Firezone. If you run it without any
arguments you should see a list of available commands like this:
```bash
Usage: firezone COMMAND [ARGS]
The known commands are:
start Starts the system
start_iex Starts the system with IEx attached
daemon Starts the system as a daemon
daemon_iex Starts the system as a daemon with IEx attached
eval "EXPR" Executes the given expression on a new, non-booted system
rpc "EXPR" Executes the given expression remotely on the running system
remote Connects to the running system via a remote shell
restart Restarts the running system via a remote command
stop Stops the running system via a remote command
pid Prints the operating system PID of the running system via a remote command
version Prints the release name and version to be booted
```
Most deployment-related configuration is handled with environment variables.
You'll probably want to at least set variables related to your reverse proxy and
database. See the [ENV var reference](/docs/reference/env-vars) for an
exhaustive list.
Now all you need are the database and reverse proxy that you've previously set
up. Once that's done, you can use `firezone start` to start Firezone and run
`create-or-reset-admin` (in the same `bin` dir) to create the admin user and use
it to log into Firezone from a web browser to start setting up your brand new
custom instance that you built by hand with a little bit of elbow grease :)
<Alert color="info">
As mentioned at the top, it's recommended to use some sort of service
management to start and stop Firezone easily without having to manually do it
using the `firezone` binary directly. But the choice is yours, since you're in
control!
</Alert>

11
website/src/app/docs/deploy/advanced/external-database/page.tsx
View File

@@ -1,11 +0,0 @@
import Content from "./readme.mdx";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "External Database • Firezone Docs",
description: "Using an external database with Firezone.",
};
export default function Page() {
return <Content />;
}

80
website/src/app/docs/deploy/advanced/external-database/readme.mdx
View File

@@ -1,80 +0,0 @@
import { TabsGroup, TabsItem } from "@/components/Tabs";
import Alert from "@/components/DocsAlert";
# Custom External Database
Firezone uses [Postgresql DB](https://postgresql.org) as its primary data store.
## Compatibility
Firezone should work fine on Postgres versions 12 and above, but we recommend
using the latest stable version whenever possible. If you find an issue with
your particular version of Postgres,
[please open a GitHub issue ](https://github.com/firezone/firezone/issues).
In general, Firezone should also work fine using external Postgres-based
database services like Amazon RDS. See the
[configuration ](#configure-firezone-to-connect) section below for more
information configuring Firezone with an external DB.
<Alert color="warning">
Configuring Firezone to use an external database can be complicated and
error-prone. We recommend using the bundled Postgres for Omnibus-based
deployments or the official Postgres Docker image for Docker-based deployments
if possible.
</Alert>
## Configure Firezone to Connect
<TabsGroup>
<TabsItem title="Docker" active>
The Firezone Docker image uses the following environment variables to connect to
the DB (fields in bold required):
| Name | Description | Format | Default |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ------------------------------------ |
| **`DATABASE_ENCRYPTION_KEY`** | The base64-encoded symmetric encryption key used to encrypt and decrypt sensitive fields. | base64-encoded String | None -- must be generated on install |
| `DATABASE_HOST` | Database host | IP or hostname | `postgres` |
| `DATABASE_PORT` | Database port | Integer | `5432` |
| `DATABASE_NAME` | Name of database | String | `firezone` |
| `DATABASE_USER` | User | String | `postgres` |
| `DATABASE_PASSWORD` | Password | String | `postgres` |
| `DATABASE_POOL` | Size of the Firezone connection pool | Integer | `10` |
| `DATABASE_SSL` | Whether to connect to the database over SSL | Boolean | `false` |
| `DATABASE_SSL_OPTS` | Map of options to send to the `:ssl_opts` option when connecting over SSL. See [Ecto.Adapters.Postgres documentation](https://hexdocs.pm/ecto_sql/Ecto.Adapters.Postgres.html#module-connection-options) | JSON-encoded String | `{}` |
| `DATABASE_PARAMETERS` | Map of parameters to send to the `:parameters` option when connecting to the database. See [Ecto.Adapters.Postgres documentation](https://hexdocs.pm/ecto_sql/Ecto.Adapters.Postgres.html#module-connection-options). | JSON-encoded String | `{}` |
For more information, see the
[environment variable reference ](/docs/reference/env-vars).
<Alert color="info">
The official `postgres` docker image can be configured by setting environment
variables for the container. See the Postgres image
[documentation](https://hub.docker.com/_/postgres) for more details.
</Alert>
</TabsItem>
<TabsItem title="Omnibus">
The following configuration options are used to configure the bundled Postgres
for Omnibus-based deployments:
| Config Key | Description | Default |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `default['firezone']['database']['user']` | Specifies the username Firezone will use to connect to the DB. | `node['firezone']['postgresql']['username']` |
| `default['firezone']['database']['password']` | If using an external DB, specifies the password Firezone will use to connect to the DB. | `'change_me'` |
| `default['firezone']['database']['name']` | Database that Firezone will use. Will be created if it doesn't exist. | `'firezone'` |
| `default['firezone']['database']['host']` | Database host that Firezone will connect to. | `node['firezone']['postgresql']['listen_address']` |
| `default['firezone']['database']['port']` | Database port that Firezone will connect to. | `node['firezone']['postgresql']['port']` |
| `default['firezone']['database']['pool']` | Database pool size Firezone will use. | `[10, Etc.nprocessors].max` |
| `default['firezone']['database']['ssl']` | Whether to connect to the database over SSL. | `false` |
| `default['firezone']['database']['ssl_opts']` | Hash of options to send to the `:ssl_opts` option when connecting over SSL. See [Ecto.Adapters.Postgres documentation](https://hexdocs.pm/ecto_sql/Ecto.Adapters.Postgres.html#module-connection-options). | `{}` |
| `default['firezone']['database']['parameters']` | Hash of parameters to send to the `:parameters` option when connecting to the database. See [Ecto.Adapters.Postgres documentation](https://hexdocs.pm/ecto_sql/Ecto.Adapters.Postgres.html#module-connection-options). | `{}` |
| `default['firezone']['database']['extensions']` | Database extensions to enable. | `{ 'plpgsql' => true, 'pg_trgm' => true }` |
For more details, see the
[configuration file reference ](/docs/reference/configuration-file).
</TabsItem>
</TabsGroup>

11
website/src/app/docs/deploy/advanced/reverse-proxy/page.tsx
View File

@@ -1,11 +0,0 @@
import Content from "./readme.mdx";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Custom Reverse Proxy • Firezone Docs",
description: "Using a custom reverse proxy with Firezone.",
};
export default function Page() {
return <Content />;
}

108
website/src/app/docs/deploy/advanced/reverse-proxy/readme.mdx
View File

@@ -1,108 +0,0 @@
import Alert from "@/components/DocsAlert";
# Custom Reverse Proxy
<Alert color="warning">
Using a custom reverse proxy is an advanced configuration. The default bundled
Nginx proxy (Omnibus-based deployments) and Caddy (Docker-based deployments)
is suitable for the vast majority of use cases and is recommended for most
users. There are important security risks if the reverse proxy is not set up
correctly.
</Alert>
## Introduction
Firezone comes with bundled [Nginx](https://www.nginx.com) (Omnibus-based
deployments) or uses Caddy (Docker-based deployments) by default. However, in
some cases you might want to deploy your own server such as when using your own
load balancer.
## Prerequisites
Below you will find the requirements in order to setup Firezone with a custom
reverse proxy.
### Firezone configuration requirements
- Disable the bundled Nginx by setting `default['firezone']['nginx']['enabled']`
to `false` in the config file.
- If you have any immediate proxies between your primary reverse proxy and the
Firezone web app, add their IPs to
`default['firezone']['phoenix']['external_trusted_proxies']`. Because of the
way the
[X-Forwarded-For header works](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For),
this is needed to parse the actual client's IP address to prevent IP spoofing.
<Alert color="info">
<div>
The `external_trusted_proxies` list automatically implicitly includes the
following private CIDR ranges, even if they're not specified in the
configuration file:
- `127.0.0.0/8`
- `10.0.0.0/8`
- `172.16.0.0/12`
- `192.168.0.0/16`
- `::1/128`
- `fc00::/7`
This means any web requests originating from these IPs are automatically ignored
from the `X-Forwarded-For` headers. If you're accessing Firezone from any IPs in
this range (as seen by the Firezone web app), be sure to add them to the
`default['firezone']['phoenix']['clients']` configuration option instead.
</div>
</Alert>
Read more about the configuration options
[here](/docs/reference/configuration-file).
### Proxy requirements
- All your proxies need to configure the `X-Forwarded-For` header as explained
[here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)
- Your proxy should also set the `X-Forwarded-Proto` to `https`.
- Your proxy (or another downstream proxy) **must** terminate SSL since we
enforce
[secure cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies).
- Firezone requires the use of WebSockets to establish realtime connections. We
recommend following your proxy's specific documentation for supporting
WebSockets as each proxy varies. In general, your proxy needs to be able to
proxy HTTP 1.1 connections, and the Firezone web app expects the following
headers to be set:
- `Connection: upgrade`
- `Upgrade: websocket`
## Security considerations
In addition to the headers above, we recommend adding the following headers for
security purposes:
- `X-XSS-Protection: 1; mode=block`
- `X-Content-Type-Options nosniff`
- `Referrer-Policy no-referrer-when-downgrade`
- `Content-Security-Policy: default-src 'self' ws: wss: http: https: data: blob: 'unsafe-inline'; frame-ancestors 'self';`
- `Permissions-Policy: interest-cohort=()`
Since the upstream Firezone web app expects plain HTTP traffic, any requests the
proxy forwards is sent over HTTP and thus is **not encrypted**. In most cases,
the reverse proxy is installed in a trusted network, and this is not an issue.
But the connection between your trusted proxy and the Firezone web app spans an
untrusted network (such as the Internet), you may want to leave the bundled
`nginx` proxy enabled for SSL termination, and set up your custom reverse proxy
to proxy to that instead.
## Example configurations
- [Apache](/docs/reference/reverse-proxy-templates/apache)
- [Traefik](/docs/reference/reverse-proxy-templates/traefik)
- [HAProxy](/docs/reference/reverse-proxy-templates/haproxy)
These configurations are written to be as simple as possible. They're designed
to function as a simple template which you can customize further to suit your
needs.
If you have a working configuration for a different reverse proxy or a different
version of an existing one we appreciate any
[contribution](https://github.com/firezone/firezone) to expand the examples for
the community.

11
website/src/app/docs/deploy/configure/page.tsx
View File

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

57
website/src/app/docs/deploy/configure/readme.mdx
View File

@@ -1,57 +0,0 @@
import { TabsGroup, TabsItem } from "@/components/Tabs";
# Configure Firezone
There are two types of configuration in Firezone:
- [Runtime configuration](#runtime-configuration): Application configuration
related to day-to-day operation of Firezone.
- [Deployment configuration](#deployment-configuration): Deployment or
infrastructure-related configuration relevant to running Firezone on-prem.
## Runtime configuration
Most day-to-day configuration of Firezone can be done via the Web UI or
[REST API](/docs/reference/rest-api/configurations). This type of configuration
can be expected to be changed **with no downtime** in a production deployment.
We're actively working to move more configuration variables to this type of
configuration, so expect more ENV vars to transition to runtime configuration in
the future.
## Deployment configuration
Deployment-related and infrastructure configuration require restarting Firezone
services after change.
<TabsGroup>
<TabsItem title="Docker" active>
Docker-based deployments are configured through environment variables passed to
the `firezone` container. These can be specified either in a `.env` file in the
current directory, the `docker-compose.yml` file, or passed to the `docker run`
call directly. See the [env var reference](/docs/reference/env-vars) for a
complete listing.
See
[Docker's documentation ](https://docs.docker.com/compose/envvars-precedence)
for more information.
</TabsItem>
<TabsItem title="Omnibus">
For Omnibus-based deployments, Firezone leverages
[Chef Omnibus ](https://github.com/chef/omnibus) to handle release packaging,
process supervision, log management, and more.
The main configuration file is written in [Ruby](https://ruby-lang.org) and can
be found at `/etc/firezone/firezone.rb` on a default installation. Changing this
file **requires re-running** `sudo firezone-ctl reconfigure` which triggers Chef
to pick up the changes and apply them to the running system.
For an exhaustive list of Omnibus configuration variables and their
descriptions, see the
[configuration file reference ](/docs/reference/configuration-file).
</TabsItem>
</TabsGroup>

12
website/src/app/docs/deploy/docker/page.tsx
View File

@@ -1,12 +0,0 @@
import Content from "./readme.mdx";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Install Firezone with Docker • Firezone Docs",
description:
"Install Firezone via Docker to manage secure remote access to private networks and resources.",
};
export default function Page() {
return <Content />;
}

183
website/src/app/docs/deploy/docker/readme.mdx
View File

@@ -1,183 +0,0 @@
import Alert from "@/components/DocsAlert";
import SupportOptions from "@/components/SupportOptions";
# Install Firezone with Docker
As of 0.6.0, Docker is now the **preferred method** for deploying Firezone.
Docker offers a number of benefits over the old
[Omnibus method](/docs/deploy/omnibus):
- **Simpler, more robust upgrades**: In most cases, simply pull the latest
`firezone/firezone` image and restart the container.
- **Simpler configuration**: Most day-to-day configuration of Firezone can now
be done in the web UI instead of the `/etc/firezone/firezone.rb` configuration
file. All other configuration variables can be specified as ENV vars to the
Firezone container.
- **Smaller footprint**: The Firezone image weighs in at a couple dozen
megabytes versus hundreds of megabytes for the Omnibus package.
- **Portability**: Firezone now runs on any platform that supports Docker.
- **Security**: Containerization providers better security isolation than simply
running as an unprivileged local user.
## Step 1: Prerequisites
- Ensure you're on a
[supported platform](/docs/deploy/docker/supported-platforms) with
[ docker-compose](https://docs.docker.com/compose/install) **version 2 or
higher** installed.
- Ensure port forwarding is enabled on your firewall. The default Firezone
configuration requires the following ports to be open:
- `80/tcp` (optional): For automatically issuing SSL certificates.
- `443/tcp`: To access the web UI.
- `51820/udp`: VPN traffic listen port.
<Alert color="warning">
Before deploying Firezone in **production**, you'll need a valid DNS record
pointing to this instance. See [Prepare to
deploy](/docs/deploy/#prepare-to-deploy) if you haven't done this already.
</Alert>
## Step 2: Install server
After prerequisites are satisfied, you're ready to install the Firezone Server.
### Option 1: Automatic install
The easiest way to deploy Firezone with Docker is the automatic install script:
```bash
bash <(curl -fsSL https://github.com/firezone/firezone/raw/legacy/scripts/install.sh)
```
This will ask you a few questions regarding initial configuration, then proceed
to download a sample docker-compose.yml file, configure it with your responses,
and then print instructions for accessing the Web UI.
Firezone files will be installed in `$HOME/.firezone` by default.
### Option 2: Manual install
If the automatic install fails, or you'd just like more control over the
installation process, follow the steps below to install manually.
1. Download the docker compose template to a local working directory: **For
Linux**:
```bash
curl -fsSL https://raw.githubusercontent.com/firezone/firezone/legacy/docker-compose.prod.yml -o docker-compose.yml
```
**For macOS, Windows (non-production only)**:
```bash
curl -fsSL https://raw.githubusercontent.com/firezone/firezone/legacy/docker-compose.desktop.yml -o docker-compose.yml
```
1. Generate required secrets:
```bash
docker run --rm firezone/firezone bin/gen-env > .env
```
2. At a minimum, change the `DEFAULT_ADMIN_EMAIL` and `EXTERNAL_URL` variables.
Optionally modify other secrets as needed.
3. Migrate the database:
```bash
docker compose run --rm firezone bin/migrate
```
4. Create the first admin:
```bash
docker compose run --rm firezone bin/create-or-reset-admin
```
5. Bring the services up: `docker compose up -d`
You should now be able to access the Firezone web portal at the `EXTERNAL_URL`
variable you defined above.
## Step 3 (optional): Enable on boot
If you'd like Firezone to start automatically on boot, first ensure Docker is
enabled at startup:
```bash
sudo systemctl enable docker
```
Then, make sure your Firezone services have the `restart: always` or
`restart: unless-stopped` option specified in the `docker-compose.yml` file.
This is the default used in the docker-compose.prod.yml production template
file.
## Step 4 (optional): Enable IPv6
By default, Firezone ships with IPv6 connectivity enabled inside the tunnel but
not routable to the public internet. To enable IPv6 support in Docker-deployed
Firezone, follow the steps below.
1. Enable IPv6 support within Docker by adding the following to
`/etc/docker/daemon.json`:
```json
{
"ipv6": true,
"ip6tables": true,
"experimental": true,
"fixed-cidr-v6": "fcff:db8:1::/64"
}
```
This enables IPv6 NAT and configures IPv6 forwarding for Docker containers.
1. Enable router advertisements on boot for your default egress interface:
```bash
egress=`ip route show default 0.0.0.0/0 | grep -oP '(?<=dev ).*' | cut -f1 -d' ' | tr -d '\n'`
sudo bash -c "echo net.ipv6.conf.${egress}.accept_ra=2 >> /etc/sysctl.conf"
```
2. Reboot
You should now be able to ping google from within a docker container:
```bash
docker run --rm -t busybox ping6 -c 4 google.com
```
You shouldn't need to manually add any `iptables` rules to enable IPv6
SNAT/masquerading for tunneled traffic; Firezone handles this for you by default
on start.
## Step 5: Install client apps
<Alert color="info">
Firezone currently uses WireGuard's [open-source client
apps](https://www.wireguard.com/install).
</Alert>
Once successfully deployed, users and devices can be added to connect to the VPN
server:
- [Add Users](/docs/user-guides/add-users): Add users to grant them access to
your network.
- [Client Instructions](/docs/user-guides/client-instructions): Instructions to
establish a VPN session.
<SupportOptions />
## Post Setup
Congrats! You have completed the setup, but there's a lot more you can do with
Firezone:
- [Integrate your identity provider](/docs/authenticate) for authenticating
clients
- Using Firezone as a NAT gateway to
[establish a static IP for your team](/docs/user-guides/use-cases/nat-gateway)
- Create tunnels between multiple peers with
[reverse tunnels](/docs/user-guides/use-cases/reverse-tunnel)
- Only route certain traffic through Firezone with
[split tunneling](/docs/user-guides/use-cases/split-tunnel)

11
website/src/app/docs/deploy/docker/supported-platforms/page.tsx
View File

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

30
website/src/app/docs/deploy/docker/supported-platforms/readme.mdx
View File

@@ -1,30 +0,0 @@
# Supported Platforms for Docker-based Deployments
Firezone currently supports the following platforms for Docker-based
deployments.
| OS | Architecture(s) | Runtime | Status | Notes |
| ------- | --------------- | -------------- | ----------------------- | --------------------------------------------------------------------------------------- |
| Linux | `amd64` `arm64` | Docker Server | **Fully-supported** | Kernel `5.6` or higher recommended. |
| Linux | `amd64` `arm64` | Docker Desktop | Works, but unsupported. | Not recommended for production deployments. See [caveats](#docker-desktop-caveats). |
| macOS | `amd64` `arm64` | Docker Desktop | Works. but unsupported. | Not recommended for production deployments. See [caveats](#non-linux-platform-caveats). |
| Windows | `amd64` `arm64` | Docker Desktop | **Untested** | Not recommended for production deployments. See [caveats](#non-linux-platform-caveats). |
## Docker Desktop caveats
Docker Desktop
[rewrites the source address ](https://www.docker.com/blog/how-docker-desktop-networking-works-under-the-hood)
for packets flowing out of container networks under some conditions. This can
cause routing loops and other hard to debug connectivity issues with Firezone.
We recommend **only** using Docker Server for Linux for production deployments.
## Non-Linux platform caveats
Only Docker for Linux supports the host networking mode, so macOS and Windows
platforms will be able unable to properly attribute client source address for
HTTP requests. This means any IP-based throttling or logging in your chosen
proxy (`caddy` by default) will be ineffective, since the source IP will always
be the Docker-side host IP (typically `172.X.0.1`).
Egress rules operate on the tunneled client IP address and aren't affected by
this limitation.

7
website/src/app/docs/deploy/omnibus/_page.tsx
View File

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

12
website/src/app/docs/deploy/omnibus/page.tsx
View File

@@ -1,12 +0,0 @@
import _Page from "./_page";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Install Firezone with Omnibus • Firezone Docs",
description:
"Install Firezone via our Omnibus deployment option to manage secure access to private networks and resources.",
};
export default function Page() {
return <_Page />;
}

201
website/src/app/docs/deploy/omnibus/readme.mdx
View File

@@ -1,201 +0,0 @@
import Image from "next/image";
import Alert from "@/components/DocsAlert";
import SupportOptions from "@/components/SupportOptions";
# Install Firezone with Omnibus
<Alert color="warning">
Due to Omnibus being EOL'd by Chef in 2024, Docker is now the preferred method
of deploying Firezone. See the [Docker deployment guide](/docs/deploy/docker)
to get started. Read below to continue with an Omnibus-based deployment.
</Alert>
Firezone can be deployed on a server running a supported
[Linux distribution](/docs/deploy/omnibus/supported-platforms) in a few minutes
with our Debian or Red Hat package. This guide will walk you through the steps
to get started.
## Step 1: Prerequisites
- Ensure you're on a
[supported Linux distribution](/docs/deploy/omnibus/supported-platforms). A
kernel upgrade may be required to ensure WireGuard® is available.
- Ensure port forwarding is enabled on your firewall. The default Firezone
configuration requires the following ports to be open:
- `80/tcp` (optional): For automatically issuing SSL certificates.
- `443/tcp`: To access the web UI.
- `51820/udp`: VPN traffic listen port.
<Alert color="warning">
Before deploying Firezone in <strong>production</strong>, you'll need a valid
DNS record pointing to this instance. See [Prepare to
deploy](/docs/deploy/#prepare-to-deploy) if you haven't done this already.
</Alert>
<Alert color="info">
Firezone modifies the kernel netfilter and routing tables. Other programs that
modify the Linux routing table or firewall may interfere with Firezone’s
operation. For help troubleshooting connectivity issues, see the
[troubleshooting guide](/docs/administer/troubleshoot)
</Alert>
## Step 2: Install server
After prerequisites are satisfied, you're ready to install the Firezone Server.
### Option 1: Automatic install
The easiest way to get started using Firezone is via the automatic installation
script below.
```bash
sudo -E bash -c "$(curl -fsSL https://github.com/firezone/firezone/raw/legacy/scripts/omnibus_install.sh)"
```
This will ask you a few questions regarding your install, install the latest
release for your platform, create an administrator user, then print to the
console instructions for logging in to the web UI.
<Image
className="mx-auto"
alt="install complete"
src="/images/install-complete.png"
width={960}
height={540}
/>
By default, the web UI can be reached at the IP or domain name of your server.
You can regenerate the admin credentials using the
`firezone-ctl create-or-reset-admin` command.
### Option 2: Install from our Debian or RedHat repositories
If the automatic install script fails, try these steps to install Firezone from
our [Cloudsmith repository](https://cloudsmith.io/~firezone/repos/firezone).
1. [Install WireGuard](https://www.wireguard.com/install) for your distro. If
using Linux kernel 5.6 or higher, skip this step.
1. Install our package repository for your distro's package format:
- deb packages:
```bash
curl -1sLf \
'https://dl.cloudsmith.io/public/firezone/firezone/setup.deb.sh' \
| sudo -E bash
```
See the
[Debian setup docs](https://cloudsmith.io/~firezone/repos/firezone/setup/#formats-deb)
for more options if the script fails to setup the repo.
- rpm packages:
```bash
curl -1sLf \
'https://dl.cloudsmith.io/public/firezone/firezone/setup.rpm.sh' \
| sudo -E bash
```
See the
[RedHat setup docs](https://cloudsmith.io/~firezone/repos/firezone/setup/#formats-rpm)
for more options if the script fails to setup the repo.
1. Install Firezone with your distro's package manager:
```bash
# Using apt
sudo apt install firezone
# Using dnf
sudo dnf install firezone
# Using yum
sudo yum install firezone
# Using zypper
sudo zypper install firezone
```
1. Follow the [bootstrap instructions](#bootstrap-firezone) to setup Firezone.
### Option 3: Manual install
If all else fails, try these steps to install Firezone manually.
1. [Install WireGuard](https://www.wireguard.com/install) for your distro. If
using Linux kernel 5.6 or higher, skip this step.
1. Download the relevant package for your distribution from the
[releases page](https://github.com/firezone/firezone/releases).
1. Install with `sudo rpm -i firezone*.rpm` or `sudo dpkg -i firezone*.deb`
depending on your distro.
1. Follow the [bootstrap instructions](#bootstrap-firezone) to setup Firezone.
### Bootstrap Firezone
1. Bootstrap the application with `sudo firezone-ctl reconfigure`. This will
initialize config files, set up needed services and generate the default
configuration.
1. Edit the default configuration located at `/etc/firezone/firezone.rb`. We've
chosen sensible defaults that should be a good starting point for most
installations. For production installations, you'll want to specify a valid
external URL and enable ACME for certificate issuance and renewal:
```ruby
# Auto-generated based on the server's hostname.
# Set this to the URL used to access the Firezone Web UI.
default['firezone']['external_url'] = 'https://firezone.example.com'
# Set the email that will be used for the issued certificates and certifications.
default['firezone']['ssl']['email_address'] = 'your@email.com'
# Enable ACME renewal
default['firezone']['ssl']['acme']['enabled'] = true
```
See the complete
[configuration file reference for more details ](/docs/reference/configuration-file).
1. Reconfigure the application to pick up the new changes:
`sudo firezone-ctl reconfigure`.
1. Finally, create an admin user with `sudo firezone-ctl create-or-reset-admin`.
The login credentials will be printed to the console output.
1. Now you should be able to sign in to the web UI at the URL you specified in
step 5 above, e.g. `https://firezone.example.com`
Find solutions to common issues during deployment in
[Troubleshoot ](/docs/administer/troubleshoot).
## Step 3: Install client apps
Once successfully deployed, users and devices can be added to connect to the VPN
server:
- [Add Users](/docs/user-guides/add-users): Add users to grant them access to
your network.
- [Client Instructions](/docs/user-guides/client-instructions): Instructions to
establish a VPN session.
<SupportOptions />
## Post setup
Congrats! You have completed the setup, but there's a lot more you can do with
Firezone:
- [Integrate your identity provider](/docs/authenticate) for authenticating
clients
- Using Firezone to
[establish a static IP](/docs/user-guides/use-cases/nat-gateway)
- Create tunnels between multiple peers with
[reverse tunnels](/docs/user-guides/use-cases/reverse-tunnel)
- Only route certain traffic through Firezone with
[split tunneling](/docs/user-guides/use-cases/split-tunnel)
Support us by:
- Starring our repo on [Github](https://github.com/firezone/firezone)
- Following us on X at [@firezonehq](https://x.com/firezonehq)
- Following us on LinkedIn at
[@firezonehq](https://www.linkedin.com/company/firezonehq)

11
website/src/app/docs/deploy/omnibus/supported-platforms/page.tsx
View File

@@ -1,11 +0,0 @@
import Content from "./readme.mdx";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Support Platforms for Omnibus • Firezone Docs",
description: "Supported platforms for Omnibus-based deployments of Firezone.",
};
export default function Page() {
return <Content />;
}

118
website/src/app/docs/deploy/omnibus/supported-platforms/readme.mdx
View File

@@ -1,118 +0,0 @@
# Support Platforms for Omnibus-based Deployments
Omnibus Firezone currently supports the following platforms:
| OS | Architectures | Status | Notes |
| -------------------------- | --------------- | ------------------- | ----------------------------------------------- |
| AmazonLinux 2 | `amd64` `arm64` | **Fully-supported** | See [AmazonLinux 2 Notes](#amazonlinux-2-notes) |
| CentOS 7 | `amd64` | **Fully-supported** | See [CentOS 7 Notes](#centos-7-notes) |
| CentOS 8 | `amd64` `arm64` | **Fully-supported** | See [CentOS 8 Notes](#centos-8-notes) |
| CentOS Stream 9 | `amd64` `arm64` | **Fully-supported** | Works as-is |
| Red Hat Enterprise Linux 7 | `amd64` | **Fully-supported** | See [RHEL 7 Notes](#rhel-7-notes) |
| Red Hat Enterprise Linux 8 | `amd64` `arm64` | **Fully-supported** | See [RHEL 8 Notes](#rhel-8-notes) |
| Red Hat Enterprise Linux 9 | `amd64` `arm64` | **Fully-supported** | See [RHEL 9 Notes](#rhel-9-notes) |
| Debian 10 | `amd64` `arm64` | **Fully-supported** | See [Debian 10 Notes](#debian-10-notes) |
| Debian 11 | `amd64` `arm64` | **Fully-supported** | Works as-is |
| Fedora 33 | `amd64` `arm64` | **Fully-supported** | See [Fedora Notes](#fedora-notes) |
| Fedora 34 | `amd64` `arm64` | **Fully-supported** | See [Fedora Notes](#fedora-notes) |
| Fedora 35 | `amd64` `arm64` | **Fully-supported** | See [Fedora Notes](#fedora-notes) |
| Ubuntu 18.04 | `amd64` `arm64` | **Fully-supported** | See [Ubuntu 18.04 Notes](#ubuntu-1804-notes) |
| Ubuntu 20.04 | `amd64` `arm64` | **Fully-supported** | Works as-is |
| Ubuntu 22.04 | `amd64` `arm64` | **Fully-supported** | Works as-is |
| openSUSE Leap 15.3 | `amd64` | **Fully-supported** | See [openSUSE Notes](#opensuse-notes) |
If your distro isn't listed here please try using a package for the closest
distro first. For example, since Raspberry Pi OS is based on Debian, try using
the Debian Firezone package.
If that doesn't work, please
[open an issue](https://github.com/firezone/firezone/issues/new/choose) and let
us know. New distros are being supported on a regular basis and there's a good
chance yours will be added soon.
Note that we only support RPM and DEB based packaging systems. Others, like Arch
Linux are currently being investigated
[ in this issue](https://github.com/firezone/firezone/issues/378).
## AmazonLinux 2 notes
Kernel upgrade required:
```bash
sudo amazon-linux-extras install -y kernel-5.10
```
## CentOS 7 notes
Kernel upgrade to 5.6+ required. To upgrade to the latest mainline kernel and
select it as the default boot kernel:
```bash
sudo rpm --import https://www.elrepo.org/RPM-GPG-KEY-elrepo.org
sudo yum install -y https://www.elrepo.org/elrepo-release-7.el7.elrepo.noarch.rpm
sudo yum install -y elrepo-release
sudo yum --enablerepo=elrepo-kernel install -y kernel-ml
sudo grub2-set-default 0
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
sudo reboot
```
## CentOS 8 notes
The WireGuard kernel module needs to be installed:
```bash
yum install elrepo-release epel-release
yum install kmod-wireguard
```
## RHEL 7 notes
Red Hat Enterprise Linux is binary compatible with CentOS, so the Firezone
package for CentOS 7 should work just fine for RHEL 7. You'll still need to
upgrade your kernel to 5.6+ however. To do so, follow the steps for
[CentOS 7 Notes](#centos-7-notes) above.
## RHEL 8 notes
Red Hat Enterprise Linux is binary compatible with CentOS, so the Firezone
package for CentOS 8 should work just fine for RHEL 8. You'll still need to
install the WireGuard kernel module, however. See
[CentOS 8 Notes ](#centos-8-notes) above.
## RHEL 9 notes
Use the package for CentOS 9.
## Fedora notes
On fresh Fedora installations you'll probably need to install a cron
implementation to support the logrotate functionality, otherwise you may receive
errors about a missing `/etc/cron.hourly` directory.
```bash
yum install cronie-anacron
```
## Ubuntu 18.04 notes
Kernel upgrade to 5.4+ required:
```bash
sudo apt install linux-image-generic-hwe-18.04
```
## Debian 10 notes
Kernel upgrade to 5.6+ required. See
[this guide ](https://jensd.be/968/linux/install-a-newer-kernel-in-debian-10-buster-stable)
for an example.
## openSUSE notes
Firezone requires the `setcap` utility, but some recent openSUSE releases may
not have it installed by default. To fix, ensure `libcap-progs` is installed:
```bash
sudo zypper install libcap-progs
```

12
website/src/app/docs/deploy/page.tsx
View File

@@ -1,12 +0,0 @@
import Content from "./readme.mdx";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Deploy Firezone • Firezone Docs",
description:
"Install Firezone's WireGuard®-based secure access platform on a support host using our Docker (recommended) or Omnibus deployment methods.",
};
export default function Page() {
return <Content />;
}

103
website/src/app/docs/deploy/readme.mdx
View File

@@ -1,103 +0,0 @@
import { TabsGroup, TabsItem } from "@/components/Tabs";
import Alert from "@/components/DocsAlert";
# Deploy Firezone
Firezone can be deployed on most Docker-supported platforms in a couple of
minutes. Read more below to get started.
## Step 1: Prepare to deploy
Regardless of which deployment method you choose, you'll need to follow the
preparation steps below before deploying Firezone to production.
1. [Create a DNS record](#create-a-dns-record)
1. [Set up SSL](#set-up-ssl)
1. [Open required firewall ports](#open-required-firewall-ports)
### Create a DNS record
Firezone requires a fully-qualified domain name (e.g. `firezone.company.com`)
for production use. You'll need to create the appropriate DNS record at your
registrar to achieve this. Typically this is either an A, CNAME, or AAAA record
depending on your requirements.
### Set up SSL
You'll need a valid SSL certificate to use Firezone in a production capacity.
Firezone supports ACME for automatic provisioning of SSL certificates for both
Docker-based and Omnibus-based installations. This is recommended in most cases.
<TabsGroup>
<TabsItem title="Docker" active>
#### Setting up ACME for Docker-based deployments
For Docker-based deployments, the simplest way to provision an SSL certificate
is to use our Caddy service example in docker-compose.yml. Caddy uses ACME to
automatically provision SSL certificates as long as it's available on port
80/tcp and the DNS record for the server is valid.
See the [Docker deployment guide](/docs/deploy/docker) for more info.
</TabsItem>
<TabsItem title="Omnibus">
For Omnibus-based deployments, ACME is disabled by default to maintain
compatibility with existing installations.
To enable ACME, ensure the following conditions are met:
- `80/tcp` is allow inbound
- The bundled Firezone `nginx` service is enabled and functioning
- You have a valid DNS record assigned to this instance's public IP
- The following 3 settings are configured in the
[configuration file](/docs/reference/configuration-file):
- `default['firezone']['external_url']`: The FQDN for the server.
- `default['firezone']['ssl']['email_address']`: The email that will be used
for the issued certificates.
- `default['firezone']['ssl']['acme']['enabled']`: Set this to true to enable
it.
</TabsItem>
</TabsGroup>
### Open required firewall ports
By default, Firezone requires ports `443/tcp` and `51820/udp` to be accessible
for HTTPS and WireGuard traffic respectively. These ports can change based on
what you've configured in the configuration file. See the
[configuration file reference](/docs/reference/configuration-file) for details.
### Resource requirements
We recommend **starting with 1 vCPU and 1 GB of RAM and scaling up** as the
number of users and devices grows.
For Omnibus-based deployments on servers with less than 1GB of memory, we
recommend turning on swap to prevent the Linux kernel from killing Firezone
processes unexpectedly. When this happens, it's often difficult to debug and
results in strange, unpredictable failure modes.
For the VPN tunnels themselves, Firezone uses in-kernel WireGuard, so its
performance should be very good. 1 vCPU should be more than enough to saturate a
1 Gbps link.
## Step 2: Deploy
You have two options for deploying Firezone:
1. [Docker](/docs/deploy/docker) (recommended)
1. [Omnibus](/docs/deploy/omnibus)
Docker is the easiest way to install, manage, and upgrade Firezone and is the
preferred method of deployment.
<Alert color="warning">
Chef Infra Client, the configuration system Chef Omnibus relies on, has been
[scheduled for End-of-Life in 2024](https://docs.chef.io/versions). As such,
support for Omnibus-based deployments will be removed starting with Firezone
0.8. To transition to Docker from Omnibus today, follow our [migration
guide](/docs/administer/upgrade).
</Alert>

11
website/src/app/docs/deploy/security-considerations/page.tsx
View File

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

58
website/src/app/docs/deploy/security-considerations/readme.mdx
View File

@@ -1,58 +0,0 @@
import { TabsGroup, TabsItem } from "@/components/Tabs";
import Alert from "@/components/DocsAlert";
# Security considerations
**Disclaimer**: Firezone is still beta software. The codebase has not yet
received a formal security audit. For highly sensitive and mission-critical
production deployments, we recommend disabling local authentication as detailed
[below](#production-deployments).
## List of services and ports
Shown below is a table of default ports used by Firezone services.
<TabsGroup>
<TabsItem title="Docker" active>
| Service | Port | Listen address | Description |
| ---------- | ----------- | -------------- | ----------------------------------------------------------------------------- |
| Caddy | `443/tcp` | `all` | Public HTTPS port for administering Firezone and facilitating authentication. |
| Caddy | `80/tcp` | `all` | Public HTTP port used for ACME. Disabled when ACME is disabled. |
| WireGuard | `51820/udp` | `all` | Public WireGuard port used for VPN sessions. |
| Postgresql | `5432/tcp` | `-` | Containerized port used for bundled Postgresql server. |
| Phoenix | `13000/tcp` | `-` | Containerized port used by upstream elixir app server. |
</TabsItem>
<TabsItem title="Omnibus">
| Service | Port | Listen address | Description |
| ---------- | ----------- | -------------- | ----------------------------------------------------------------------------- |
| Nginx | `443/tcp` | `all` | Public HTTPS port for administering Firezone and facilitating authentication. |
| Nginx | `80/tcp` | `all` | Public HTTP port used for ACME. Disabled when ACME is disabled. |
| WireGuard | `51820/udp` | `all` | Public WireGuard port used for VPN sessions. |
| Postgresql | `15432/tcp` | `127.0.0.1` | Local-only port used for bundled Postgresql server. |
| Phoenix | `13000/tcp` | `127.0.0.1` | Local-only port used by upstream elixir app server. |
</TabsItem>
</TabsGroup>
## Production deployments
For production deployments of Firezone, we recommend you disable local
authentication altogether by setting
`default['firezone']['authentication']['local']['enabled'] = false`
(Omnibus-based deployments) or `LOCAL_AUTH_ENABLED=false` (Docker-based
deployments). Local authentication can also be disabled on the
`/settings/security` page.
<Alert color="warning">
Ensure you've set up a working [OIDC](/docs/authenticate/oidc) or
[SAML](/docs/authenticate/saml)-based authentication provider before disabling
the local authentication method.
</Alert>
## Reporting security issues
To report any security-related bugs, see
[our security bug reporting policy ](https://github.com/firezone/firezone/blob/main/docs/SECURITY.md).

30
website/src/app/docs/layout.tsx
View File

@@ -1,30 +0,0 @@
import fs from "fs";
import path from "path";
import LastUpdated from "@/components/LastUpdated";
import DocsSidebar from "@/components/DocsSidebar";
import Banner from "./banner.mdx";
export default function Layout({ children }: { children: React.ReactNode }) {
// timestamps.json was generated during build
const timestampsFile = path.resolve("timestamps.json");
const timestampsData = fs.readFileSync(timestampsFile, "utf-8");
const timestamps = JSON.parse(timestampsData);
return (
<div className="flex">
<DocsSidebar />
<main className="p-4 pt-32 -ml-64 md:ml-0 lg:mx-auto">
<div className="px-4">
<article className="max-w-screen-md tracking-[-0.01em] format format-sm md:format-md lg:format-lg format-firezone">
<Banner />
{children}
</article>
<div className="mt-8 flex flex-wrap justify-end text-sm text-neutral-600">
<LastUpdated timestamps={timestamps} />
</div>
</div>
</main>
</div>
);
}

11
website/src/app/docs/page.tsx
View File

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

54
website/src/app/docs/readme.mdx
View File

@@ -1,54 +0,0 @@
import SupportOptions from "@/components/SupportOptions";
import Image from "next/image";
# Docs Overview
Welcome to the Firezone Documentation! Use the sections below to get started.
## What is Firezone?
[Firezone](/) is an open-source secure remote access platform that can be
deployed on your own infrastructure in minutes. Use it to **quickly and easily**
secure access to your private network and internal applications from an
intuitive web UI.
<Image
className="mx-auto"
width={960}
height={540}
alt="firezone architecture"
src="/images/firezone-architecture.png"
/>
These docs explain how to deploy, configure, and use Firezone.
## Quick start
1. [Deploy](/docs/deploy): A step-by-step walk-through setting up Firezone.
Start here if you are new.
1. [Authenticate](/docs/authenticate): Set up authentication using local
email/password, OpenID Connect, or SAML 2.0 and optionally enable TOTP-based
MFA.
1. [Administer](/docs/administer): Day to day administration of the Firezone
server.
1. [User Guides](/docs/user-guides): Useful guides to help you learn how to use
Firezone and troubleshoot common issues. Consult this section after you
successfully deploy the Firezone server.
## Common configuration guides
1. [Split Tunneling](/docs/user-guides/use-cases/split-tunnel): Only route
traffic to certain IP ranges through the VPN.
1. [Setting up a NAT Gateway with a Static IP](/docs/user-guides/use-cases/nat-gateway):
Configure Firezone with a static IP address to provide a single egress IP for
your team's traffic.
1. [Reverse Tunnels](/docs/user-guides/use-cases/reverse-tunnel): Establish
tunnels between multiple peers.
<SupportOptions />
## Contribute to Firezone
We deeply appreciate any and all contributions to the project and do our best to
ensure your contribution is included. To get started, see
[CONTRIBUTING.md](https://github.com/firezone/firezone/blob/main/docs/CONTRIBUTING.md).

11
website/src/app/docs/reference/configuration-file/page.tsx
View File

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

180
website/src/app/docs/reference/configuration-file/readme.mdx
View File

@@ -1,180 +0,0 @@
import Alert from "@/components/DocsAlert";
# Omnibus configuration options
<Alert color="warning">
This reference is written for Omnibus-based deployments of Firezone. For
Docker-based deployments visit the [Environment
Variables](/docs/reference/env-vars) page.
</Alert>
To configure Omnibus-based deployments of Firezone:
1. Edit `/etc/firezone/firezone.rb` with your changes.
1. Run `sudo firezone-ctl reconfigure` to process the changes and restart
affected services.
Read more about configuring Firezone in the
[configure guide](/docs/deploy/configure).
## Configuration file reference
Shown below is a complete listing of the configuration options available in
`/etc/firezone/firezone.rb`.
| Option | Description | Default Value |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `default['firezone']['external_url']` | URL used to access the web portal of this Firezone instance. | `"https://#{node['fqdn'] \|\| node['hostname']}"` |
| `default['firezone']['config_directory']` | Top-level directory for Firezone configuration. | `'/etc/firezone'` |
| `default['firezone']['install_directory']` | Top-level directory to install Firezone to. | `'/opt/firezone'` |
| `default['firezone']['app_directory']` | Top-level directory to install the Firezone web application. | `"#{node['firezone']['install_directory']}/embedded/service/firezone"` |
| `default['firezone']['log_directory']` | Top-level directory for Firezone logs. | `'/var/log/firezone'` |
| `default['firezone']['var_directory']` | Top-level directory for Firezone runtime files. | `'/var/opt/firezone'` |
| `default['firezone']['user']` | Name of unprivileged Linux user most services and files will belong to. | `'firezone'` |
| `default['firezone']['group']` | Name of Linux group most services and files will belong to. | `'firezone'` |
| `default['firezone']['admin_email']` | Email address for initial Firezone user. | `"firezone@localhost"` |
| `default['firezone']['max_devices_per_user']` | Maximum number of devices a user can have. | `10` |
| `default['firezone']['allow_unprivileged_device_management']` | Allows non-admin users to create and delete devices. | `true` |
| `default['firezone']['allow_unprivileged_device_configuration']` | Allows non-admin users to modify device configurations. When disabled, prevents unprivileged users from changing all device fields except for `name` and `description`. | `true` |
| `default['firezone']['egress_interface']` | Interface name where tunneled traffic will exit. If nil, the default route interface will be used. | `nil` |
| `default['firezone']['fips_enabled']` | Enable or disable OpenSSL FIPs mode. | `nil` |
| `default['firezone']['logging']['enabled']` | Enable or disable logging across Firezone. Set to `false` to disable logging entirely. | `true` |
| `default['enterprise']['name']` | Name used by the Chef 'enterprise' cookbook. | `'firezone'` |
| `default['firezone']['install_path']` | Install path used by Chef 'enterprise' cookbook. Should be set to the same as the `install_directory` above. | `node['firezone']['install_directory']` |
| `default['firezone']['sysvinit_id']` | An identifier used in `/etc/inittab`. Must be a unique sequence of 1-4 characters. | `'SUP'` |
| `default['firezone']['authentication']['local']['enabled']` | Enable or disable local email/password authentication. | `true` |
| `default['firezone']['authentication']['disable_vpn_on_oidc_error']` | Disable a user's VPN if an error is detected trying to refresh their OIDC token. | `false` |
| `default['firezone']['authentication']['oidc']` | OpenID Connect config, in the format of `{"provider" => [config...]}` - See [OpenIDConnect documentation](https://hexdocs.pm/openid_connect/readme.html) for config examples. | `{}` |
| `default['firezone']['nginx']['enabled']` | Enable or disable the bundled nginx server. | `true` |
| `default['firezone']['nginx']['ssl_port']` | HTTPS listen port. | `443` |
| `default['firezone']['nginx']['directory']` | Directory to store Firezone-related nginx virtual host configuration. | `"#{node['firezone']['var_directory']}/nginx/etc"` |
| `default['firezone']['nginx']['log_directory']` | Directory to store Firezone-related nginx log files. | `"#{node['firezone']['log_directory']}/nginx"` |
| `default['firezone']['nginx']['log_rotation']['file_maxbytes']` | File size at which to rotate Nginx log files. | `104857600` |
| `default['firezone']['nginx']['log_rotation']['num_to_keep']` | Number of Firezone nginx log files to keep before discarding. | `10` |
| `default['firezone']['nginx']['log_x_forwarded_for']` | Whether to log Firezone nginx `x-forwarded-for` header. | `true` |
| `default['firezone']['nginx']['hsts_header']['enabled']` | Enable or disable [HSTS](https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx). | `true` |
| `default['firezone']['nginx']['hsts_header']['include_subdomains']` | Enable or disable `includeSubDomains` for the HSTS header. | `true` |
| `default['firezone']['nginx']['hsts_header']['max_age']` | Max age for the HSTS header. | `31536000` |
| `default['firezone']['nginx']['redirect_to_canonical']` | Whether to redirect URLs to the canonical FQDN specified above | `false` |
| `default['firezone']['nginx']['cache']['enabled']` | Enable or disable the Firezone nginx cache. | `false` |
| `default['firezone']['nginx']['cache']['directory']` | Directory for Firezone nginx cache. | `"#{node['firezone']['var_directory']}/nginx/cache"` |
| `default['firezone']['nginx']['user']` | Firezone nginx user. | `node['firezone']['user']` |
| `default['firezone']['nginx']['group']` | Firezone nginx group. | `node['firezone']['group']` |
| `default['firezone']['nginx']['dir']` | Top-level nginx configuration directory. | `node['firezone']['nginx']['directory']` |
| `default['firezone']['nginx']['log_dir']` | Top-level nginx log directory. | `node['firezone']['nginx']['log_directory']` |
| `default['firezone']['nginx']['pid']` | Location for nginx pid file. | `"#{node['firezone']['nginx']['directory']}/nginx.pid"` |
| `default['firezone']['nginx']['daemon_disable']` | Disable nginx daemon mode so we can monitor it instead. | `true` |
| `default['firezone']['nginx']['gzip']` | Turn nginx gzip compression on or off. | `'on'` |
| `default['firezone']['nginx']['gzip_static']` | Turn nginx gzip compression on or off for static files. | `'off'` |
| `default['firezone']['nginx']['gzip_http_version']` | HTTP version to use for serving static files. | `'1.0'` |
| `default['firezone']['nginx']['gzip_comp_level']` | nginx gzip compression level. | `'2'` |
| `default['firezone']['nginx']['gzip_proxied']` | Enables or disables gzipping of responses for proxied requests depending on the request and response. | `'any'` |
| `default['firezone']['nginx']['gzip_vary']` | Enables or disables inserting the “Vary: Accept-Encoding” response header. | `'off'` |
| `default['firezone']['nginx']['gzip_buffers']` | Sets the number and size of buffers used to compress a response. If `nil`, nginx default is used. | `nil` |
| `default['firezone']['nginx']['gzip_types']` | MIME types to enable gzip compression for. | `['text/plain', 'text/css','application/x-javascript', 'text/xml', 'application/xml', 'application/rss+xml', 'application/atom+xml', 'text/javascript', 'application/javascript', 'application/json']` |
| `default['firezone']['nginx']['gzip_min_length']` | Minimum file length to enable file gzip compression for. | `1000` |
| `default['firezone']['nginx']['gzip_disable']` | User-agent matcher to disable gzip compression for. | `'MSIE [1-6]\.'` |
| `default['firezone']['nginx']['keepalive']` | Activates cache for connection to upstream servers. | `'on'` |
| `default['firezone']['nginx']['keepalive_timeout']` | Timeout in seconds for keepalive connection to upstream servers. | `65` |
| `default['firezone']['nginx']['worker_processes']` | Number of nginx worker processes. | `node['cpu'] && node['cpu']['total'] ? node['cpu']['total'] : 1` |
| `default['firezone']['nginx']['worker_connections']` | Max number of simultaneous connections that can be opened by a worker process. | `1024` |
| `default['firezone']['nginx']['worker_rlimit_nofile']` | Changes the limit on the maximum number of open files for worker processes. Uses nginx default if nil. | `nil` |
| `default['firezone']['nginx']['multi_accept']` | Whether workers should accept one connection at a time or multiple. | `true` |
| `default['firezone']['nginx']['event']` | Specifies the connection processing method to use inside nginx events context. | `'epoll'` |
| `default['firezone']['nginx']['server_tokens']` | Enables or disables emitting nginx version on error pages and in the “Server” response header field. | `nil` |
| `default['firezone']['nginx']['server_names_hash_bucket_size']` | Sets the bucket size for the server names hash tables. | `64` |
| `default['firezone']['nginx']['sendfile']` | Enables or disables the use of nginx's `sendfile()`. | `'on'` |
| `default['firezone']['nginx']['access_log_options']` | Sets nginx access log options. | `nil` |
| `default['firezone']['nginx']['error_log_options']` | Sets nginx error log options. | `nil` |
| `default['firezone']['nginx']['disable_access_log']` | Disables nginx access log. | `false` |
| `default['firezone']['nginx']['types_hash_max_size']` | nginx types hash max size. | `2048` |
| `default['firezone']['nginx']['types_hash_bucket_size']` | nginx types hash bucket size. | `64` |
| `default['firezone']['nginx']['proxy_read_timeout']` | nginx proxy read timeout. Set to `nil` to use nginx default. | `nil` |
| `default['firezone']['nginx']['client_body_buffer_size']` | nginx client body buffer size. Set to `nil` to use nginx default. | `nil` |
| `default['firezone']['nginx']['client_max_body_size']` | nginx client max body size. | `'250m'` |
| `default['firezone']['nginx']['default']['modules']` | Specify additional nginx modules. | `[]` |
| `default['firezone']['nginx']['enable_rate_limiting']` | Enable or disable nginx rate limiting. | `true` |
| `default['firezone']['nginx']['rate_limiting_zone_name']` | Nginx rate limiting zone name. | `'firezone'` |
| `default['firezone']['nginx']['rate_limiting_backoff']` | Nginx rate limiting backoff. | `'10m'` |
| `default['firezone']['nginx']['rate_limit']` | Nginx rate limit. | `'10r/s'` |
| `default['firezone']['nginx']['ipv6']` | Allow nginx to listen for HTTP requests for IPv6 in addition to IPv4. | `true` |
| `default['firezone']['postgresql']['enabled']` | Enable or disable bundled Postgresql. Set to `false` and fill in the `database` options below to use your own Postgresql instance. | `true` |
| `default['firezone']['postgresql']['username']` | Username for Postgresql. | `node['firezone']['user']` |
| `default['firezone']['postgresql']['data_directory']` | Postgresql data directory. | `"#{node['firezone']['var_directory']}/postgresql/13.3/data"` |
| `default['firezone']['postgresql']['log_directory']` | Postgresql log directory. | `"#{node['firezone']['log_directory']}/postgresql"` |
| `default['firezone']['postgresql']['log_rotation']['file_maxbytes']` | Postgresql log file maximum size before it's rotated. | `104857600` |
| `default['firezone']['postgresql']['log_rotation']['num_to_keep']` | Number of Postgresql log files to keep. | `10` |
| `default['firezone']['postgresql']['checkpoint_completion_target']` | Postgresql checkpoint completion target. | `0.5` |
| `default['firezone']['postgresql']['checkpoint_segments']` | Number of Postgresql checkpoint segments. | `3` |
| `default['firezone']['postgresql']['checkpoint_timeout']` | Postgresql checkpoint timeout. | `'5min'` |
| `default['firezone']['postgresql']['checkpoint_warning']` | Postgresql checkpoint warning time in seconds. | `'30s'` |
| `default['firezone']['postgresql']['effective_cache_size']` | Postgresql effective cache size. | `'128MB'` |
| `default['firezone']['postgresql']['listen_address']` | Postgresql listen address. | `'127.0.0.1'` |
| `default['firezone']['postgresql']['max_connections']` | Postgresql max connections. | `350` |
| `default['firezone']['postgresql']['md5_auth_cidr_addresses']` | Postgresql CIDRs to allow for md5 auth. | `['127.0.0.1/32', '::1/128']` |
| `default['firezone']['postgresql']['port']` | Postgresql listen port. | `15432` |
| `default['firezone']['postgresql']['shared_buffers']` | Postgresql shared buffers size. | `"#{(node['memory']['total'].to_i / 4) / 1024}MB"` |
| `default['firezone']['postgresql']['shmmax']` | Postgresql shmmax in bytes. | `17179869184` |
| `default['firezone']['postgresql']['shmall']` | Postgresql shmall in bytes. | `4194304` |
| `default['firezone']['postgresql']['work_mem']` | Postgresql working memory size. | `'8MB'` |
| `default['firezone']['database']['user']` | Specifies the username Firezone will use to connect to the DB. | `node['firezone']['postgresql']['username']` |
| `default['firezone']['database']['password']` | If using an external DB, specifies the password Firezone will use to connect to the DB. | `'change_me'` |
| `default['firezone']['database']['name']` | Database that Firezone will use. Will be created if it doesn't exist. | `'firezone'` |
| `default['firezone']['database']['host']` | Database host that Firezone will connect to. | `node['firezone']['postgresql']['listen_address']` |
| `default['firezone']['database']['port']` | Database port that Firezone will connect to. | `node['firezone']['postgresql']['port']` |
| `default['firezone']['database']['pool']` | Database pool size Firezone will use. | `[10, Etc.nprocessors].max` |
| `default['firezone']['database']['ssl']` | Whether to connect to the database over SSL. | `false` |
| `default['firezone']['database']['ssl_opts']` | Hash of options to send to the `:ssl_opts` option when connecting over SSL. See [Ecto.Adapters.Postgres documentation](https://hexdocs.pm/ecto_sql/Ecto.Adapters.Postgres.html#module-connection-options). | `{}` |
| `default['firezone']['database']['parameters']` | Hash of parameters to send to the `:parameters` option when connecting to the database. See [Ecto.Adapters.Postgres documentation](https://hexdocs.pm/ecto_sql/Ecto.Adapters.Postgres.html#module-connection-options). | `{}` |
| `default['firezone']['database']['extensions']` | Database extensions to enable. | `{ 'plpgsql' => true, 'pg_trgm' => true }` |
| `default['firezone']['phoenix']['enabled']` | Enable or disable the Firezone web application. | `true` |
| `default['firezone']['phoenix']['listen_address']` | Firezone web application listen address. This will be the upstream listen address that nginx proxies. | `'127.0.0.1'` |
| `default['firezone']['phoenix']['port']` | Firezone web application listen port. This will be the upstream port that nginx proxies. | `13000` |
| `default['firezone']['phoenix']['log_directory']` | Firezone web application log directory. | `"#{node['firezone']['log_directory']}/phoenix"` |
| `default['firezone']['phoenix']['log_rotation']['file_maxbytes']` | Firezone web application log file size. | `104857600` |
| `default['firezone']['phoenix']['log_rotation']['num_to_keep']` | Number of Firezone web application log files to keep. | `10` |
| `default['firezone']['phoenix']['crash_detection']['enabled']` | Enable or disable bringing down the Firezone web application when a crash is detected. | `true` |
| `default['firezone']['phoenix']['external_trusted_proxies']` | List of trusted reverse proxies formatted as an Array of IPs and/or CIDRs. | `[]` |
| `default['firezone']['phoenix']['private_clients']` | List of private network HTTP clients, formatted an Array of IPs and/or CIDRs. | `[]` |
| `default['firezone']['wireguard']['enabled']` | Enable or disable bundled WireGuard management. | `true` |
| `default['firezone']['wireguard']['log_directory']` | Log directory for bundled WireGuard management. | `"#{node['firezone']['log_directory']}/wireguard"` |
| `default['firezone']['wireguard']['log_rotation']['file_maxbytes']` | WireGuard log file max size. | `104857600` |
| `default['firezone']['wireguard']['log_rotation']['num_to_keep']` | Number of WireGuard log files to keep. | `10` |
| `default['firezone']['wireguard']['interface_name']` | WireGuard interface name. **Changing this parameter may cause a temporary loss in VPN connectivity**. | `'wg-firezone'` |
| `default['firezone']['wireguard']['port']` | WireGuard listen port. | `51820` |
| `default['firezone']['wireguard']['persistent_keepalive']` | Default PersistentKeepalive setting for generated device configurations. A value of 0 disables. | `0` |
| `default['firezone']['wireguard']['ipv4']['enabled']` | Enable or disable IPv4 for WireGuard network. | `true` |
| `default['firezone']['wireguard']['ipv4']['masquerade']` | Enable or disable masquerade for packets leaving the IPv4 tunnel. | `true` |
| `default['firezone']['wireguard']['ipv4']['network']` | WireGuard network IPv4 address pool. | `'10.3.2.0/24'` |
| `default['firezone']['wireguard']['ipv4']['address']` | WireGuard interface IPv4 address. Must be within WireGuard address pool. | `'10.3.2.1'` |
| `default['firezone']['wireguard']['ipv6']['enabled']` | Enable or disable IPv6 for WireGuard network. | `true` |
| `default['firezone']['wireguard']['ipv6']['masquerade']` | Enable or disable masquerade for packets leaving the IPv6 tunnel. | `true` |
| `default['firezone']['wireguard']['ipv6']['network']` | WireGuard network IPv6 address pool. | `'fd00::3:2:0/120'` |
| `default['firezone']['wireguard']['ipv6']['address']` | WireGuard interface IPv6 address. Must be within IPv6 address pool. | `'fd00::3:2:1'` |
| `default['firezone']['runit']['svlogd_bin']` | Runit svlogd bin location. | `"#{node['firezone']['install_directory']}/embedded/bin/svlogd"` |
| `default['firezone']['ssl']['directory']` | SSL directory for storing generated certs. | `'/var/opt/firezone/ssl'` |
| `default['firezone']['ssl']['email_address']` | Email address to use for self-signed certs and ACME protocol renewal notices. | `'you@example.com'` |
| `default['firezone']['ssl']['acme']['enabled']` | Enable ACME for automatic SSL cert provisioning. | `false` |
| `default['firezone']['ssl']['acme']['server']` | ACME server to use for certificate issuance/renewal. Can be any [valid acme.sh server](https://github.com/acmesh-official/acme.sh/wiki/Server) | `letsencrypt` |
| `default['firezone']['ssl']['acme']['keylength']` | Specify the key type and length for SSL certificates. See [here](https://github.com/acmesh-official/acme.sh#10-issue-ecc-certificates) | `ec-256` |
| `default['firezone']['ssl']['certificate']` | Path to the certificate file for your FQDN. Overrides ACME setting above if specified. If both ACME and this are `nil` a self-signed cert will be generated. | `nil` |
| `default['firezone']['ssl']['certificate_key']` | Path to the certificate file. | `nil` |
| `default['firezone']['ssl']['ssl_dhparam']` | nginx ssl dh_param. | `nil` |
| `default['firezone']['ssl']['country_name']` | Country name for self-signed cert. | `'US'` |
| `default['firezone']['ssl']['state_name']` | State name for self-signed cert. | `'CA'` |
| `default['firezone']['ssl']['locality_name']` | Locality name for self-signed cert. | `'San Francisco'` |
| `default['firezone']['ssl']['company_name']` | Company name self-signed cert. | `'My Company'` |
| `default['firezone']['ssl']['organizational_unit_name']` | Organizational unit name for self-signed cert. | `'Operations'` |
| `default['firezone']['ssl']['ciphers']` | SSL ciphers for nginx to use. | `'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA'` |
| `default['firezone']['ssl']['fips_ciphers']` | SSL ciphers for FIPs mode. | `'FIPS@STRENGTH:!aNULL:!eNULL'` |
| `default['firezone']['ssl']['protocols']` | TLS protocols to use. | `'TLSv1 TLSv1.1 TLSv1.2'` |
| `default['firezone']['ssl']['session_cache']` | SSL session cache. | `'shared:SSL:4m'` |
| `default['firezone']['ssl']['session_timeout']` | SSL session timeout. | `'5m'` |
| `default['firezone']['robots_allow']` | nginx robots allow. | `'/'` |
| `default['firezone']['robots_disallow']` | nginx robots disallow. | `nil` |
| `default['firezone']['outbound_email']['from']` | Outbound email from address. | `nil` |
| `default['firezone']['outbound_email']['provider']` | Outbound email service provider. | `nil` |
| `default['firezone']['outbound_email']['configs']` | Outbound email provider configs. | see `omnibus/cookbooks/firezone/attributes/default.rb` |
| `default['firezone']['telemetry']['enabled']` | Enable or disable anonymized product telemetry. | `true` |
| `default['firezone']['connectivity_checks']['enabled']` | Enable or disable the Firezone connectivity checks service. | `true` |
| `default['firezone']['connectivity_checks']['interval']` | Interval between connectivity checks in seconds. | `3_600` |

12
website/src/app/docs/reference/env-vars/page.tsx
View File

@@ -1,12 +0,0 @@
import Content from "./readme.mdx";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Environment Variables • Firezone Docs",
description:
"Environment variables for Docker-based deployments of Firezone.",
};
export default function Page() {
return <Content />;
}

158
website/src/app/docs/reference/env-vars/readme.mdx
View File

@@ -1,158 +0,0 @@
# Environment Variables
Most day-to-day config of Firezone can be done via the Firezone Web UI, but for
zero-touch deployments we allow to override most of configuration options using
environment variables.
Read more about configuring Firezone in our
[configure guide](/docs/deploy/configure).
## Errors
Firezone will not boot if the configuration is invalid, providing a detailed
error message and a link to the documentation for the configuration key with
samples how to set it.
## Naming
If environment variables are used, the configuration key must be in uppercase.
The database variables are the same as the configuration keys.
## Precedence
The configuration precedence is as follows:
1. Environment variables
2. Database values
3. Default values
It means that if environment variable is set, it will be used, regardless of the
database value, and UI to edit database value will be disabled.
## Environment Variable Listing
We recommend setting these in your Docker ENV file (`$HOME/.firezone/.env` by
default). Required fields in **bold**.
### WebServer
| Env Key | Description | Format | Default |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------- |
| **EXTERNAL_URL** | The external URL the web UI will be accessible at.<br /> <br />Must be a valid and public FQDN for ACME SSL issuance to function.<br /> <br />You can add a path suffix if you want to serve firezone from a non-root path, eg: `https://firezone.mycorp.com/vpn/`. | string | |
| PHOENIX_SECURE_COOKIES | Enable or disable requiring secure cookies. Required for HTTPS. | boolean | true |
| PHOENIX_HTTP_PORT | Internal port to listen on for the Phoenix web server. | integer | 13000 |
| PHOENIX_HTTP_PROTOCOL_OPTIONS | Allows to override Cowboy HTTP server options.<br /> <br />Keep in mind though changing those limits can pose a security risk. Other times, browsers and proxies along the way may have equally strict limits, which means the request will still fail or the URL will be pruned.<br /> <br />You can see all supported options at https://ninenines.eu/docs/en/cowboy/2.12/manual/cowboy_http2/. | JSON-encoded map | `{}` |
| PHOENIX_EXTERNAL_TRUSTED_PROXIES | List of trusted reverse proxies.<br /> <br />This is used to determine the correct IP address of the client when the application is behind a reverse proxy by skipping a trusted proxy IP from a list of possible source IPs. | JSON-encoded list | `"[]"` |
| PHOENIX_PRIVATE_CLIENTS | List of trusted clients.<br /> <br />This is used to determine the correct IP address of the client when the application is behind a reverse proxy by picking a trusted client IP from a list of possible source IPs. | JSON-encoded list | `"[]"` |
| HTTP_CLIENT_SSL_OPTS | JSON-encoded ssl options to pass to Erlang's [`ssl` module](https://www.erlang.org/doc/man/ssl.html).<br />. Most users don't need to override many, if any, SSL opts. Most commonly this is to use custom cacert files and TLS versions for self-hosted OIDC providers. | JSON-encoded map | `{}` |
### Database
| Env Key | Description | Format | Default |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | --------- |
| DATABASE_HOST | PostgreSQL host. | string | postgres |
| DATABASE_PORT | PostgreSQL port. | integer | 5432 |
| DATABASE_NAME | Name of the PostgreSQL database. | string | firezone |
| DATABASE_USER | User that will be used to access the PostgreSQL database. | string | postgres |
| DATABASE_PASSWORD | Password that will be used to access the PostgreSQL database. | string | |
| DATABASE_POOL_SIZE | Size of the connection pool to the PostgreSQL database. | integer | generated |
| DATABASE_SSL_ENABLED | Whether to connect to the database over SSL.<br /> <br />If this field is set to `true`, the `database_ssl_opts` config must be set too with at least `cacertfile` option present. | boolean | false |
| DATABASE_SSL_OPTS | SSL options for connecting to the PostgreSQL database.<br /> <br />Typically, to enabled SSL you want following options: <br /> - `cacertfile` - path to the CA certificate file;<br /> - `verify` - set to `verify_peer` to verify the server certificate;<br /> - `fail_if_no_peer_cert` - set to `true` to require the server to present a certificate;<br /> - `server_name_indication` - specify the hostname to be used in TLS Server Name Indication extension.<br /> <br />See [Ecto.Adapters.Postgres documentation](https://hexdocs.pm/ecto_sql/Ecto.Adapters.Postgres.html#module-connection-options). For list of all supported options, see the [`ssl`](http://erlang.org/doc/man/ssl.html#type-tls_client_option) module documentation. | JSON-encoded map | `{}` |
### Admin Setup
Options responsible for initial admin provisioning and resetting the admin
password.
For more details see
[troubleshooting guide](/docs/administer/troubleshoot/#admin-login-isnt-working).
| Env Key | Description | Format | Default |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- |
| RESET_ADMIN_ON_BOOT | Set this variable to `true` to create or reset the admin password every time Firezone starts. By default, the admin password is only set when Firezone is installed.<br /> <br />Note: This **will not** change the status of local authentication. | boolean | false |
| DEFAULT_ADMIN_EMAIL | Primary administrator email. | string | |
| DEFAULT_ADMIN_PASSWORD | Default password that will be used for creating or resetting the primary administrator account. | string | |
### Secrets and Encryption
Your secrets should be generated during installation automatically and persisted
to `.env` file.
All secrets should be a **base64-encoded string**.
| Env Key | Description | Format | Default |
| --------------------------- | ------------------------------------------------------------------ | ------ | ------- |
| **GUARDIAN_SECRET_KEY** | Secret key used for signing JWTs. | string | |
| **DATABASE_ENCRYPTION_KEY** | Secret key used for encrypting sensitive data in the database. | string | |
| **SECRET_KEY_BASE** | Primary secret key base for the Phoenix application. | string | |
| **LIVE_VIEW_SIGNING_SALT** | Signing salt for Phoenix LiveView connection tokens. | string | |
| **COOKIE_SIGNING_SALT** | Signing salt for cookies issued by the Phoenix web application. | string | |
| **COOKIE_ENCRYPTION_SALT** | Encryption salt for cookies issued by the Phoenix web application. | string | |
### Devices
| Env Key | Description | Format | Default |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------- |
| ALLOW_UNPRIVILEGED_DEVICE_MANAGEMENT | Enable or disable management of devices on unprivileged accounts. | boolean | true |
| ALLOW_UNPRIVILEGED_DEVICE_CONFIGURATION | Enable or disable configuration of device network settings for unprivileged users. | boolean | true |
| VPN_SESSION_DURATION | Optionally require users to periodically authenticate to the Firezone web UI in order to keep their VPN sessions active. | integer | 0 |
| DEFAULT_CLIENT_PERSISTENT_KEEPALIVE | Interval for WireGuard [persistent keepalive](https://www.wireguard.com/quickstart/#nat-and-firewall-traversal-persistence).<br /> <br />If you experience NAT or firewall traversal problems, you can enable this to send a keepalive packet every 25 seconds. Otherwise, keep it disabled with a 0 default value. | integer | 25 |
| DEFAULT_CLIENT_MTU | WireGuard interface MTU for devices. 1280 is a safe bet for most networks. Leave this blank to omit this field from generated configs. | integer | 1280 |
| DEFAULT_CLIENT_ENDPOINT | IPv4, IPv6 address, or FQDN that devices will be configured to connect to. Defaults to this server's FQDN. | one of `IP with port`, `string` | generated |
| DEFAULT_CLIENT_DNS | Comma-separated list of DNS servers to use for devices.<br /> <br />It can be either an IP address or a FQDN if you intend to use a DNS-over-TLS server.<br /> <br />Leave this blank to omit the `DNS` section from generated configs. | `{:array, ",", {:one_of, \[FzHttp.Types.IP, :string]}, \[validate_unique: true]}` | `[]` |
| DEFAULT_CLIENT_ALLOWED_IPS | Configures the default AllowedIPs setting for devices.<br /> <br />AllowedIPs determines which destination IPs get routed through Firezone.<br /> <br />Specify a comma-separated list of IPs or CIDRs here to achieve split tunneling, or use `0.0.0.0/0, ::/0` to route all device traffic through this Firezone server. | `{:array, ",", {:one_of, \[FzHttp.Types.CIDR, FzHttp.Types.IP]}, \[validate_unique: true]}` | `0.0.0.0/0, ::/0` |
### Limits
| Env Key | Description | Format | Default |
| -------------------- | --------------------------------------------------- | ------- | ------- |
| MAX_DEVICES_PER_USER | Changes how many devices a user can have at a time. | integer | 10 |
### Authentication
| Env Key | Description | Format | Default |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | ----------------------------- |
| LOCAL_AUTH_ENABLED | Enable or disable the local authentication method for all users. | boolean | true |
| DISABLE_VPN_ON_OIDC_ERROR | Enable or disable auto disabling VPN connection on OIDC refresh error. | boolean | false |
| SAML_ENTITY_ID | Entity ID for SAML authentication. | string | urn:firezone.dev:firezone-app |
| SAML_KEYFILE_PATH | Path to the SAML keyfile inside the container. Should be either a PEM or DER-encoded private key, with file extension `.pem` or `.key`. | string | /var/firezone/saml.key |
| SAML_CERTFILE_PATH | Path to the SAML certificate file inside the container. Should be either a PEM or DER-encoded certificate, with file extension `.crt` or `.pem`. | string | /var/firezone/saml.crt |
| OPENID_CONNECT_PROVIDERS | List of OpenID Connect identity providers configurations.<br /> <br />For example:<br /> <br />`[ { "auto_create_users": false, "id": "google", "label": "google", "client_id": "test-id", "client_secret": "test-secret", "discovery_document_uri": "https://accounts.google.com/.well-known/openid-configuration", "redirect_uri": "https://invalid", "response_type": "response-type", "scope": "oauth email profile" } ]`<br /> <br />For more details see https://docs.firezone.dev/authenticate/oidc/. | JSON-encoded list | `"[]"` |
| SAML_IDENTITY_PROVIDERS | List of SAML identity providers configurations.<br /> <br />For example:<br /> <br />`[ { "auto_create_users": false, "base_url": "https://saml", "id": "okta", "label": "okta", "metadata": "<?xml version="1.0"?>...", "sign_metadata": false, "sign_requests": false, "signed_assertion_in_resp": false, "signed_envelopes_in_resp": false } ]`<br /> <br />For more details see https://docs.firezone.dev/authenticate/saml/. | JSON-encoded list | `"[]"` |
### WireGuard
| Env Key | Description | Format | Default |
| ------------------------- | --------------------------------------------------------------- | ------- | ------- |
| WIREGUARD_PORT | A port on which WireGuard will listen for incoming connections. | integer | 51820 |
| WIREGUARD_IPV4_ENABLED | Enable or disable IPv4 support for WireGuard. | boolean | true |
| WIREGUARD_IPV4_MASQUERADE | Enable or disable IPv4 masqeurading. | boolean | true |
| WIREGUARD_IPV6_ENABLED | Enable or disable IPv6 support for WireGuard. | boolean | true |
| WIREGUARD_IPV6_MASQUERADE | Enable or disable IPv6 masqeurading. | boolean | true |
### Outbound Emails
| Env Key | Description | Format | Default |
| --------------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| OUTBOUND_EMAIL_FROM | From address to use for sending outbound emails. If not set, sending email will be disabled (default). | string | generated |
| OUTBOUND_EMAIL_ADAPTER | Method to use for sending outbound email. | One of `Elixir.Swoosh.Adapters.AmazonSES`, `Elixir.Swoosh.Adapters.CustomerIO`, `Elixir.Swoosh.Adapters.Dyn`, `Elixir.Swoosh.Adapters.ExAwsAmazonSES`, `Elixir.Swoosh.Adapters.Gmail`, `Elixir.Swoosh.Adapters.MailPace`, `Elixir.Swoosh.Adapters.Mailgun`, `Elixir.Swoosh.Adapters.Mailjet`, `Elixir.Swoosh.Adapters.Mandrill`, `Elixir.Swoosh.Adapters.Postmark`, `Elixir.Swoosh.Adapters.ProtonBridge`, `Elixir.Swoosh.Adapters.SMTP`, `Elixir.Swoosh.Adapters.SMTP2GO`, `Elixir.Swoosh.Adapters.Sendgrid`, `Elixir.Swoosh.Adapters.Sendinblue`, `Elixir.Swoosh.Adapters.Sendmail`, `Elixir.Swoosh.Adapters.SocketLabs`, `Elixir.Swoosh.Adapters.SparkPost`, `Elixir.FzHttpWeb.Mailer.NoopAdapter` | `Elixir.FzHttpWeb.Mailer.NoopAdapter` |
| OUTBOUND_EMAIL_ADAPTER_OPTS | Adapter configuration, for list of options see [Swoosh Adapters](https://github.com/swoosh/swoosh#adapters). | JSON-encoded map | `{}` |
### Connectivity Checks
| Env Key | Description | Format | Default |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------- | ------- |
| CONNECTIVITY_CHECKS_ENABLED | Enable / disable periodic checking for egress connectivity. Determines the instance's public IP to populate `Endpoint` fields. | boolean | true |
| CONNECTIVITY_CHECKS_INTERVAL | Periodicity in seconds to check for egress connectivity. | integer | 43200 |
### Telemetry
| Env Key | Description | Format | Default |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- |
| TELEMETRY_ENABLED | Enable or disable the Firezone telemetry collection.<br /> <br />For more details see https://docs.firezone.dev/reference/telemetry/. | boolean | true |
### Other
| Env Key | Description | Format | Default |
| ------- | --------------------------------------------------------------- | ------------------------------ | ------- |
| LOGO | The path to a logo image file to replace default Firezone logo. | `{:embed, FzHttp.Config.Logo}` | `` |

11
website/src/app/docs/reference/file-and-directory-locations/page.tsx
View File

@@ -1,11 +0,0 @@
import Content from "./readme.mdx";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "File and Directory Locations • Firezone Docs",
description: "File and directory locations for Firezone.",
};
export default function Page() {
return <Content />;
}

36
website/src/app/docs/reference/file-and-directory-locations/readme.mdx
View File

@@ -1,36 +0,0 @@
import { TabsGroup, TabsItem } from "@/components/Tabs";
# File and Directory Locations
Here you'll find a listing of files and directories related to a typical
Firezone installation. These can change depending on how you've configured your
installation.
<TabsGroup>
<TabsItem title="Docker" active>
| Default path | Description |
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `$HOME/.firezone/.env` | Firezone secrets used for encryption, cookies, and sessions. **Losing this file will result in irrecoverable data loss**. |
| `$HOME/.firezone/docker-compose.yml` | Docker Compose file used to manage Firezone services. |
| `$HOME/.firezone/firezone` | Top-level directory containing Firezone-related persisted data |
| `$HOME/.firezone/caddy` | Caddy persisted files. |
| Default Docker named volume location, typically `/var/lib/docker/volumes/firezone_postgres-data` for Linux. | Postgres DB files. |
</TabsItem>
<TabsItem title="Omnibus">
| Path | Description |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `/var/opt/firezone` | Top-level directory containing data and generated configuration for Firezone bundled services. |
| `/opt/firezone` | Top-level directory containing built libraries, binaries and runtime files needed by Firezone. |
| `/usr/bin/firezone-ctl` | `firezone-ctl` utility for managing your Firezone installation. |
| `/etc/systemd/system/firezone-runsvdir-start.service` | systemd unit file for starting the Firezone runsvdir supervisor process. |
| `/etc/firezone` | Firezone configuration files. |
</TabsItem>
</TabsGroup>
## Backup and restore
See our [backup guide](/docs/administer/backup).

11
website/src/app/docs/reference/firewall-templates/nftables/page.tsx
View File

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

343
website/src/app/docs/reference/firewall-templates/nftables/readme.mdx
View File

@@ -1,343 +0,0 @@
# `nftables` Firewall Template
The following nftables firewall template can be used to secure the server
running Firezone. The template does make some assumptions; you may need to
adjust the rules to suit your use case:
- The WireGuard interface is named `wg-firezone`. If this is not correct, change
the `DEV_WIREGUARD` variable to match the
`default['firezone']['wireguard']['interface_name']` configuration option.
- The port WireGuard is listening on is `51820`. If you are not using the
default port change the `WIREGUARD_PORT` variable.
- Only the following inbound traffic will be allowed to the server:
- SSH (TCP dport 22)
- HTTP (TCP dport 80)
- HTTPS (TCP dport 443)
- WireGuard (UDP dport `WIREGUARD_PORT`)
- UDP traceroute (UDP dport 33434-33524, rate limited to 500/second)
- ICMP and ICMPv6 (ping/ping responses rate limited to 2000/second)
- Only the following outbound traffic will be allowed from the server:
- DNS (UDP and TCP dport 53)
- HTTP (TCP dport 80)
- NTP (UDP port 123)
- HTTPS (TCP dport 443)
- SMTP submission (TCP dport 587)
- UDP traceroute (UDP dport 33434-33524, rate limited to 500/second)
- Unmatched traffic will be logged. The rules used for logging are separated
from the rules to drop traffic and are rate limited. Removing the relevant
logging rules will not affect traffic.
## Firezone-managed rules
Firezone configures its own nftables rules to permit/reject traffic to
destinations configured in the web interface and to handle outbound NAT for
client traffic.
Applying the below firewall template on an already running server (not at boot
time) will result in the Firezone rules being cleared. This may have security
implications.
To work around this restart the `phoenix` service:
```bash
firezone-ctl restart phoenix
```
## Base firewall template
**Note**: This template assumes your interface doesn't change on reboot. See
[this issue](https://github.com/firezone/firezone/issues/1865) for more
information.
```bash
#!/usr/sbin/nft -f
## Clear/flush all existing rules
flush ruleset
################################ VARIABLES ################################
## Internet/WAN interface name
define DEV_WAN = eth0
## WireGuard interface name
define DEV_WIREGUARD = wg-firezone
## WireGuard listen port
define WIREGUARD_PORT = 51820
############################## VARIABLES END ##############################
# Main inet family filtering table
table inet filter {
# Rules for forwarded traffic
# This chain is processed before the Firezone forward chain
chain forward {
type filter hook forward priority filter - 5; policy accept
}
# Rules for input traffic
chain input {
type filter hook input priority filter; policy drop
## Permit inbound traffic to loopback interface
iif lo \
accept \
comment "Permit all traffic in from loopback interface"
## Permit established and related connections
ct state established,related \
accept \
comment "Permit established/related connections"
## Permit inbound WireGuard traffic
iif $DEV_WAN udp dport $WIREGUARD_PORT \
counter \
accept \
comment "Permit inbound WireGuard traffic"
## Log and drop new TCP non-SYN packets
tcp flags != syn ct state new \
limit rate 100/minute burst 150 packets \
log prefix "IN - New !SYN: " \
comment "Rate limit logging for new connections that do not have the SYN TCP flag set"
tcp flags != syn ct state new \
counter \
drop \
comment "Drop new connections that do not have the SYN TCP flag set"
## Log and drop TCP packets with invalid fin/syn flag set
tcp flags & (fin|syn) == (fin|syn) \
limit rate 100/minute burst 150 packets \
log prefix "IN - TCP FIN|SIN: " \
comment "Rate limit logging for TCP packets with invalid fin/syn flag set"
tcp flags & (fin|syn) == (fin|syn) \
counter \
drop \
comment "Drop TCP packets with invalid fin/syn flag set"
## Log and drop TCP packets with invalid syn/rst flag set
tcp flags & (syn|rst) == (syn|rst) \
limit rate 100/minute burst 150 packets \
log prefix "IN - TCP SYN|RST: " \
comment "Rate limit logging for TCP packets with invalid syn/rst flag set"
tcp flags & (syn|rst) == (syn|rst) \
counter \
drop \
comment "Drop TCP packets with invalid syn/rst flag set"
## Log and drop invalid TCP flags
tcp flags & (fin|syn|rst|psh|ack|urg) < (fin) \
limit rate 100/minute burst 150 packets \
log prefix "IN - FIN:" \
comment "Rate limit logging for invalid TCP flags (fin|syn|rst|psh|ack|urg) < (fin)"
tcp flags & (fin|syn|rst|psh|ack|urg) < (fin) \
counter \
drop \
comment "Drop TCP packets with flags (fin|syn|rst|psh|ack|urg) < (fin)"
## Log and drop invalid TCP flags
tcp flags & (fin|syn|rst|psh|ack|urg) == (fin|psh|urg) \
limit rate 100/minute burst 150 packets \
log prefix "IN - FIN|PSH|URG:" \
comment "Rate limit logging for invalid TCP flags (fin|syn|rst|psh|ack|urg) == (fin|psh|urg)"
tcp flags & (fin|syn|rst|psh|ack|urg) == (fin|psh|urg) \
counter \
drop \
comment "Drop TCP packets with flags (fin|syn|rst|psh|ack|urg) == (fin|psh|urg)"
## Drop traffic with invalid connection state
ct state invalid \
limit rate 100/minute burst 150 packets \
log flags all prefix "IN - Invalid: " \
comment "Rate limit logging for traffic with invalid connection state"
ct state invalid \
counter \
drop \
comment "Drop traffic with invalid connection state"
## Permit IPv4 ping/ping responses but rate limit to 2000 PPS
ip protocol icmp icmp type { echo-reply, echo-request } \
limit rate 2000/second \
counter \
accept \
comment "Permit inbound IPv4 echo (ping) limited to 2000 PPS"
## Permit all other inbound IPv4 ICMP
ip protocol icmp \
counter \
accept \
comment "Permit all other IPv4 ICMP"
## Permit IPv6 ping/ping responses but rate limit to 2000 PPS
icmpv6 type { echo-reply, echo-request } \
limit rate 2000/second \
counter \
accept \
comment "Permit inbound IPv6 echo (ping) limited to 2000 PPS"
## Permit all other inbound IPv6 ICMP
meta l4proto { icmpv6 } \
counter \
accept \
comment "Permit all other IPv6 ICMP"
## Permit inbound traceroute UDP ports but limit to 500 PPS
udp dport 33434-33524 \
limit rate 500/second \
counter \
accept \
comment "Permit inbound UDP traceroute limited to 500 PPS"
## Permit inbound SSH
tcp dport ssh ct state new \
counter \
accept \
comment "Permit inbound SSH connections"
## Permit inbound HTTP and HTTPS
tcp dport { http, https } ct state new \
counter \
accept \
comment "Permit inbound HTTP and HTTPS connections"
## Log any unmatched traffic but rate limit logging to a maximum of 60 messages/minute
## The default policy will be applied to unmatched traffic
limit rate 60/minute burst 100 packets \
log prefix "IN - Drop: " \
comment "Log any unmatched traffic"
## Count the unmatched traffic
counter \
comment "Count any unmatched traffic"
}
# Rules for output traffic
chain output {
type filter hook output priority filter; policy drop
## Permit outbound traffic to loopback interface
oif lo \
accept \
comment "Permit all traffic out to loopback interface"
## Permit established and related connections
ct state established,related \
counter \
accept \
comment "Permit established/related connections"
## Permit outbound WireGuard traffic before dropping connections with bad state
oif $DEV_WAN udp sport $WIREGUARD_PORT \
counter \
accept \
comment "Permit WireGuard outbound traffic"
## Drop traffic with invalid connection state
ct state invalid \
limit rate 100/minute burst 150 packets \
log flags all prefix "OUT - Invalid: " \
comment "Rate limit logging for traffic with invalid connection state"
ct state invalid \
counter \
drop \
comment "Drop traffic with invalid connection state"
## Permit all other outbound IPv4 ICMP
ip protocol icmp \
counter \
accept \
comment "Permit all IPv4 ICMP types"
## Permit all other outbound IPv6 ICMP
meta l4proto { icmpv6 } \
counter \
accept \
comment "Permit all IPv6 ICMP types"
## Permit outbound traceroute UDP ports but limit to 500 PPS
udp dport 33434-33524 \
limit rate 500/second \
counter \
accept \
comment "Permit outbound UDP traceroute limited to 500 PPS"
## Permit outbound HTTP and HTTPS connections
tcp dport { http, https } ct state new \
counter \
accept \
comment "Permit outbound HTTP and HTTPS connections"
## Permit outbound SMTP submission
tcp dport submission ct state new \
counter \
accept \
comment "Permit outbound SMTP submission"
## Permit outbound DNS requests
udp dport 53 \
counter \
accept \
comment "Permit outbound UDP DNS requests"
tcp dport 53 \
counter \
accept \
comment "Permit outbound TCP DNS requests"
## Permit outbound NTP requests
udp dport 123 \
counter \
accept \
comment "Permit outbound NTP requests"
## Log any unmatched traffic but rate limit logging to a maximum of 60 messages/minute
## The default policy will be applied to unmatched traffic
limit rate 60/minute burst 100 packets \
log prefix "OUT - Drop: " \
comment "Log any unmatched traffic"
## Count the unmatched traffic
counter \
comment "Count any unmatched traffic"
}
}
# Main NAT filtering table
table inet nat {
# Rules for NAT traffic pre-routing
chain prerouting {
type nat hook prerouting priority dstnat; policy accept
}
# Rules for NAT traffic post-routing
# This table is processed before the Firezone post-routing chain
chain postrouting {
type nat hook postrouting priority srcnat - 5; policy accept
}
}
```
## Usage
The firewall should be stored in the relevant location for the Linux
distribution that is running. For Debian/Ubuntu this is `/etc/nftables.conf` and
for RHEL this is `/etc/sysconfig/nftables.conf`.
`nftables.service` will need to be configured to start on boot (if not already)
set:
```bash
systemctl enable nftables.service
```
If making any changes to the firewall template the syntax can be validated by
running the check command:
```bash
nft -f /path/to/nftables.conf -c
```
Be sure to validate the firewall works as expected as certain nftables features
may not be available depending on the release running on the server.

11
website/src/app/docs/reference/rest-api/configurations/page.tsx
View File

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

160
website/src/app/docs/reference/rest-api/configurations/readme.mdx
View File

@@ -1,160 +0,0 @@
# REST API: Configurations
This endpoint allows an administrator to manage Configurations.
Updates here can be applied at runtime with little to no downtime of affected
services.
## API Documentation
### GET /v0/configuration
#### Example
```bash
$ curl -i \
-X GET "https://{firezone_host}/v0/configuration" \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {api_token}' \
HTTP/1.1 200
Content-Type: application/json; charset=utf-8
{
"data": {
"allow_unprivileged_device_configuration": true,
"allow_unprivileged_device_management": true,
"default_client_allowed_ips": [
"0.0.0.0/0",
"::/0"
],
"default_client_dns": [
"1.1.1.1",
"1.0.0.1"
],
"default_client_endpoint": "localhost:51820",
"default_client_mtu": 1280,
"default_client_persistent_keepalive": 25,
"disable_vpn_on_oidc_error": false,
"id": "c4582e2b-cba3-4a4e-9f05-0f37666c41fe",
"inserted_at": "2023-03-29T15:10:03.142320Z",
"local_auth_enabled": true,
"logo": {},
"openid_connect_providers": [],
"saml_identity_providers": [],
"updated_at": "2023-03-29T15:10:03.142320Z",
"vpn_session_duration": 0
}
}
```
### PATCH /v0/configuration
#### Example
```bash
$ curl -i \
-X PUT "https://{firezone_host}/v0/configuration" \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {api_token}' \
--data-binary @- << EOF
{
"configuration": {
"allow_unprivileged_device_configuration": false,
"allow_unprivileged_device_management": false,
"default_client_allowed_ips": [
"1.1.1.1",
"2.2.2.2"
],
"default_client_dns": [
"1.1.1.1"
],
"default_client_endpoint": "new-endpoint",
"default_client_mtu": 1100,
"default_client_persistent_keepalive": 1,
"disable_vpn_on_oidc_error": true,
"local_auth_enabled": false,
"openid_connect_providers": [
{
"auto_create_users": false,
"client_id": "test-id",
"client_secret": "test-secret",
"discovery_document_uri": "https://accounts.google.com/.well-known/openid-configuration",
"id": "google",
"label": "google",
"redirect_uri": "https://invalid",
"response_type": "code",
"scope": "email openid"
}
],
"saml_identity_providers": [
{
"auto_create_users": false,
"base_url": "https://saml",
"id": "okta",
"label": "okta",
"metadata": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<md:EntityDescriptor entityID=\"http://www.okta.com/exk6ff6p62kFjUR3X5d7\"\n xmlns:md=\"urn:oasis:names:tc:SAML:2.0:metadata\">\n <md:IDPSSODescriptor WantAuthnRequestsSigned=\"false\" protocolSupportEnumeration=\"urn:oasis:names:tc:SAML:2.0:protocol\">\n <md:KeyDescriptor use=\"signing\">\n <ds:KeyInfo\n xmlns:ds=\"http://www.w3.org/2000/09/xmldsig#\">\n <ds:X509Data>\n <ds:X509Certificate>MIIDqDCCApCgAwIBAgIGAYMaIfiKMA0GCSqGSIb3DQEBCwUAMIGUMQswCQYDVQQGEwJVUzETMBEG\nA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU\nMBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGRldi04Mzg1OTk1NTEcMBoGCSqGSIb3DQEJ\nARYNaW5mb0Bva3RhLmNvbTAeFw0yMjA5MDcyMjQ1MTdaFw0zMjA5MDcyMjQ2MTdaMIGUMQswCQYD\nVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsG\nA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGRldi04Mzg1OTk1NTEc\nMBoGCSqGSIb3DQEJARYNaW5mb0Bva3RhLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC\nggEBAOmj276L3kHm57hNGYTocT6NS4mffPbcvsA2UuKIWfmpV8HLTcmS+NahLtuN841OnRnTn+2p\nfjlwa1mwJhCODbF3dcVYOkGTPUC4y2nvf1Xas6M7+0O2WIfrzdX/OOUs/ROMnB/O/MpBwMR2SQh6\nQ3V+9v8g3K9yfMvcifDbl6g9fTliDzqV7I9xF5eJykl+iCAKNaQgp3cO6TaIa5u2ZKtRAdzwnuJC\nBXMyzaoNs/vfnwzuFtzWP1PSS1Roan+8AMwkYA6BCr1YRIqZ0GSkr/qexFCTZdq0UnSN78fY6CCM\nRFw5wU0WM9nEpbWzkBBWsYHeTLo5JqR/mZukfjlPDlcCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEA\nlUhwzCSnuqt4wlHxJONN4kxUBG8bPnjHxob6jBKK+onFDuSVWZ+7LZw67blz6xdxvlOLaQLi1fK2\nFifehbc7KbRLckcgNgg7Y8qfUKdP0/nS0JlyAvlnICQqaHTHwhIzQqTHtTZeeIJHtpWOX/OPRI0S\nbkygh2qjF8bYn3sX8bGNUQL8iiMxFnvwGrXaErPqlRqFJbWQDBXD+nYDIBw7WN3Jyb0Ydin2zrlh\ngp3Qooi0TnAir3ncw/UF/+sivCgd+6nX7HkbZtipkMbg7ZByyD9xrOQG2JXrP6PyzGCPwnGMt9pL\niiVMepeLNqKZ3UvhrR1uRN0KWu7lduIRhxldLA==</ds:X509Certificate>\n </ds:X509Data>\n </ds:KeyInfo>\n </md:KeyDescriptor>\n <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>\n <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>\n <md:SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\" Location=\"https://dev-83859955.okta.com/app/dev-83859955_firezonesaml_1/exk6ff6p62kFjUR3X5d7/sso/saml\"/>\n <md:SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\" Location=\"https://dev-83859955.okta.com/app/dev-83859955_firezonesaml_1/exk6ff6p62kFjUR3X5d7/sso/saml\"/>\n </md:IDPSSODescriptor>\n</md:EntityDescriptor>\n",
"sign_metadata": false,
"sign_requests": false,
"signed_assertion_in_resp": false,
"signed_envelopes_in_resp": false
}
],
"vpn_session_duration": 100
}
}
EOF
HTTP/1.1 200
Content-Type: application/json; charset=utf-8
{
"data": {
"allow_unprivileged_device_configuration": false,
"allow_unprivileged_device_management": false,
"default_client_allowed_ips": [
"1.1.1.1",
"2.2.2.2"
],
"default_client_dns": [
"1.1.1.1"
],
"default_client_endpoint": "new-endpoint",
"default_client_mtu": 1100,
"default_client_persistent_keepalive": 1,
"disable_vpn_on_oidc_error": true,
"id": "c4582e2b-cba3-4a4e-9f05-0f37666c41fe",
"inserted_at": "2023-03-29T15:10:03.142320Z",
"local_auth_enabled": false,
"logo": {},
"openid_connect_providers": [
{
"auto_create_users": false,
"client_id": "test-id",
"client_secret": "test-secret",
"discovery_document_uri": "https://accounts.google.com/.well-known/openid-configuration",
"id": "google",
"label": "google",
"redirect_uri": "https://invalid",
"response_type": "code",
"scope": "email openid"
}
],
"saml_identity_providers": [
{
"auto_create_users": false,
"base_url": "https://saml",
"id": "okta",
"label": "okta",
"metadata": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<md:EntityDescriptor entityID=\"http://www.okta.com/exk6ff6p62kFjUR3X5d7\"\n xmlns:md=\"urn:oasis:names:tc:SAML:2.0:metadata\">\n <md:IDPSSODescriptor WantAuthnRequestsSigned=\"false\" protocolSupportEnumeration=\"urn:oasis:names:tc:SAML:2.0:protocol\">\n <md:KeyDescriptor use=\"signing\">\n <ds:KeyInfo\n xmlns:ds=\"http://www.w3.org/2000/09/xmldsig#\">\n <ds:X509Data>\n <ds:X509Certificate>MIIDqDCCApCgAwIBAgIGAYMaIfiKMA0GCSqGSIb3DQEBCwUAMIGUMQswCQYDVQQGEwJVUzETMBEG\nA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU\nMBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGRldi04Mzg1OTk1NTEcMBoGCSqGSIb3DQEJ\nARYNaW5mb0Bva3RhLmNvbTAeFw0yMjA5MDcyMjQ1MTdaFw0zMjA5MDcyMjQ2MTdaMIGUMQswCQYD\nVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsG\nA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGRldi04Mzg1OTk1NTEc\nMBoGCSqGSIb3DQEJARYNaW5mb0Bva3RhLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC\nggEBAOmj276L3kHm57hNGYTocT6NS4mffPbcvsA2UuKIWfmpV8HLTcmS+NahLtuN841OnRnTn+2p\nfjlwa1mwJhCODbF3dcVYOkGTPUC4y2nvf1Xas6M7+0O2WIfrzdX/OOUs/ROMnB/O/MpBwMR2SQh6\nQ3V+9v8g3K9yfMvcifDbl6g9fTliDzqV7I9xF5eJykl+iCAKNaQgp3cO6TaIa5u2ZKtRAdzwnuJC\nBXMyzaoNs/vfnwzuFtzWP1PSS1Roan+8AMwkYA6BCr1YRIqZ0GSkr/qexFCTZdq0UnSN78fY6CCM\nRFw5wU0WM9nEpbWzkBBWsYHeTLo5JqR/mZukfjlPDlcCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEA\nlUhwzCSnuqt4wlHxJONN4kxUBG8bPnjHxob6jBKK+onFDuSVWZ+7LZw67blz6xdxvlOLaQLi1fK2\nFifehbc7KbRLckcgNgg7Y8qfUKdP0/nS0JlyAvlnICQqaHTHwhIzQqTHtTZeeIJHtpWOX/OPRI0S\nbkygh2qjF8bYn3sX8bGNUQL8iiMxFnvwGrXaErPqlRqFJbWQDBXD+nYDIBw7WN3Jyb0Ydin2zrlh\ngp3Qooi0TnAir3ncw/UF/+sivCgd+6nX7HkbZtipkMbg7ZByyD9xrOQG2JXrP6PyzGCPwnGMt9pL\niiVMepeLNqKZ3UvhrR1uRN0KWu7lduIRhxldLA==</ds:X509Certificate>\n </ds:X509Data>\n </ds:KeyInfo>\n </md:KeyDescriptor>\n <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>\n <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>\n <md:SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\" Location=\"https://dev-83859955.okta.com/app/dev-83859955_firezonesaml_1/exk6ff6p62kFjUR3X5d7/sso/saml\"/>\n <md:SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\" Location=\"https://dev-83859955.okta.com/app/dev-83859955_firezonesaml_1/exk6ff6p62kFjUR3X5d7/sso/saml\"/>\n </md:IDPSSODescriptor>\n</md:EntityDescriptor>\n",
"sign_metadata": false,
"sign_requests": false,
"signed_assertion_in_resp": false,
"signed_envelopes_in_resp": false
}
],
"updated_at": "2023-03-29T15:11:47.879874Z",
"vpn_session_duration": 100
}
}
```

11
website/src/app/docs/reference/rest-api/devices/page.tsx
View File

@@ -1,11 +0,0 @@
import Content from "./readme.mdx";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "REST API: Devices • Firezone Docs",
description: "REST API documentation for devices in Firezone.",
};
export default function Page() {
return <Content />;
}

Some files were not shown because too many files have changed in this diff Show More