diff --git a/website/redirects.js b/website/redirects.js index 143b1c598..d1bf069b6 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -150,4 +150,9 @@ module.exports = [ destination: "/kb/client-apps/linux-headless-client", permanent: true, }, + { + source: "/docs/:path*", + destination: "/kb", + permanent: true, + }, ]; diff --git a/website/src/app/docs/_page.tsx b/website/src/app/docs/_page.tsx deleted file mode 100644 index 8f8abd30f..000000000 --- a/website/src/app/docs/_page.tsx +++ /dev/null @@ -1,6 +0,0 @@ -"use client"; -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/administer/backup/_page.tsx b/website/src/app/docs/administer/backup/_page.tsx deleted file mode 100644 index 8f8abd30f..000000000 --- a/website/src/app/docs/administer/backup/_page.tsx +++ /dev/null @@ -1,6 +0,0 @@ -"use client"; -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/administer/backup/page.tsx b/website/src/app/docs/administer/backup/page.tsx deleted file mode 100644 index dc14f5cbc..000000000 --- a/website/src/app/docs/administer/backup/page.tsx +++ /dev/null @@ -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 />; -} diff --git a/website/src/app/docs/administer/backup/readme.mdx b/website/src/app/docs/administer/backup/readme.mdx deleted file mode 100644 index f7507290b..000000000 --- a/website/src/app/docs/administer/backup/readme.mdx +++ /dev/null @@ -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. - - - This guide is written for Firezone deployments using **Docker Engine** on - **Linux** only. - - -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. - - - - -### 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 -``` - - - - -### 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 -``` - - - - - diff --git a/website/src/app/docs/administer/debug-logs/page.tsx b/website/src/app/docs/administer/debug-logs/page.tsx deleted file mode 100644 index 9ed00bab8..000000000 --- a/website/src/app/docs/administer/debug-logs/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/administer/debug-logs/readme.mdx b/website/src/app/docs/administer/debug-logs/readme.mdx deleted file mode 100644 index 279cbbff6..000000000 --- a/website/src/app/docs/administer/debug-logs/readme.mdx +++ /dev/null @@ -1,48 +0,0 @@ -import Alert from "@/components/DocsAlert"; - -# Debug Logs - - - This article is written for Docker based deployments of Firezone. - - -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. diff --git a/website/src/app/docs/administer/migrate/page.tsx b/website/src/app/docs/administer/migrate/page.tsx deleted file mode 100644 index c0a3a0809..000000000 --- a/website/src/app/docs/administer/migrate/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/administer/migrate/readme.mdx b/website/src/app/docs/administer/migrate/readme.mdx deleted file mode 100644 index 3ef9a2a5b..000000000 --- a/website/src/app/docs/administer/migrate/readme.mdx +++ /dev/null @@ -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. - - diff --git a/website/src/app/docs/administer/page.tsx b/website/src/app/docs/administer/page.tsx deleted file mode 100644 index 3e5fd0869..000000000 --- a/website/src/app/docs/administer/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/administer/readme.mdx b/website/src/app/docs/administer/readme.mdx deleted file mode 100644 index 11944249c..000000000 --- a/website/src/app/docs/administer/readme.mdx +++ /dev/null @@ -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) diff --git a/website/src/app/docs/administer/regen-keys/page.tsx b/website/src/app/docs/administer/regen-keys/page.tsx deleted file mode 100644 index 3a23fd3b3..000000000 --- a/website/src/app/docs/administer/regen-keys/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/administer/regen-keys/readme.mdx b/website/src/app/docs/administer/regen-keys/readme.mdx deleted file mode 100644 index 3e000c43e..000000000 --- a/website/src/app/docs/administer/regen-keys/readme.mdx +++ /dev/null @@ -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 - - - 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. - - - - 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. - - -Use the procedure below to regenerate secrets: - - - - -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. - - - - -```bash -mv /etc/firezone/secrets.json /etc/firezone/secrets.bak.json -sudo firezone-ctl reconfigure -``` - - - - -## Regenerate WireGuard private key - - - 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. - - -To regenerate WireGuard private key, simply move or rename the private key file. -Firezone will generate a new one on next start. - - - - -```bash -cd $HOME/.firezone -docker-compose stop firezone -sudo mv firezone/private_key firezone/private_key.bak -docker-compose start firezone -``` - - - - -```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 -``` - - - diff --git a/website/src/app/docs/administer/troubleshoot/page.tsx b/website/src/app/docs/administer/troubleshoot/page.tsx deleted file mode 100644 index 6b85311f6..000000000 --- a/website/src/app/docs/administer/troubleshoot/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/administer/troubleshoot/readme.mdx b/website/src/app/docs/administer/troubleshoot/readme.mdx deleted file mode 100644 index 5acef21a7..000000000 --- a/website/src/app/docs/administer/troubleshoot/readme.mdx +++ /dev/null @@ -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. - - - - -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. - - - - -Firezone logs are stored in `/var/log/firezone` and can be viewed with -`sudo firezone-ctl tail`. - - - - -## 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: - - - - -```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 = '[]'" -``` - - - - -```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 = '[]'" -``` - - - - -## 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: - - - - -- `firezone` service logs: `docker compose logs firezone` -- `caddy` service logs: `docker compose logs caddy` - - - - -- 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"} -``` - - - - -## 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. - - - - -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. - - - - -Run the following command to reset the password on the default admin user. - -```bash -sudo firezone-ctl create-or-reset-admin -``` - - - - -## 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'" -``` - - diff --git a/website/src/app/docs/administer/uninstall/page.tsx b/website/src/app/docs/administer/uninstall/page.tsx deleted file mode 100644 index 3ab550b68..000000000 --- a/website/src/app/docs/administer/uninstall/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/administer/uninstall/readme.mdx b/website/src/app/docs/administer/uninstall/readme.mdx deleted file mode 100644 index 4ff84f901..000000000 --- a/website/src/app/docs/administer/uninstall/readme.mdx +++ /dev/null @@ -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. - - - This will irreversibly destroy ALL Firezone data and can't be undone. - - - - - -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 -``` - - - - -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)" -``` - - - diff --git a/website/src/app/docs/administer/upgrade/_page.tsx b/website/src/app/docs/administer/upgrade/_page.tsx deleted file mode 100644 index 5b854431b..000000000 --- a/website/src/app/docs/administer/upgrade/_page.tsx +++ /dev/null @@ -1,7 +0,0 @@ -"use client"; - -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/administer/upgrade/page.tsx b/website/src/app/docs/administer/upgrade/page.tsx deleted file mode 100644 index 7cdd1b99f..000000000 --- a/website/src/app/docs/administer/upgrade/page.tsx +++ /dev/null @@ -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 />; -} diff --git a/website/src/app/docs/administer/upgrade/readme.mdx b/website/src/app/docs/administer/upgrade/readme.mdx deleted file mode 100644 index aa073996a..000000000 --- a/website/src/app/docs/administer/upgrade/readme.mdx +++ /dev/null @@ -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. - - - 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. - - -Follow the steps below to upgrade Firezone: - - - - -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 -``` - - - - -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. - - - - -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 < 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. - -oidc connections - -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 -``` diff --git a/website/src/app/docs/authenticate/_page.tsx b/website/src/app/docs/authenticate/_page.tsx deleted file mode 100644 index 5b854431b..000000000 --- a/website/src/app/docs/authenticate/_page.tsx +++ /dev/null @@ -1,7 +0,0 @@ -"use client"; - -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/authenticate/local-auth/page.tsx b/website/src/app/docs/authenticate/local-auth/page.tsx deleted file mode 100644 index 81a3f61e0..000000000 --- a/website/src/app/docs/authenticate/local-auth/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/authenticate/local-auth/readme.mdx b/website/src/app/docs/authenticate/local-auth/readme.mdx deleted file mode 100644 index dd72f6211..000000000 --- a/website/src/app/docs/authenticate/local-auth/readme.mdx +++ /dev/null @@ -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. - - - 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. - - -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. diff --git a/website/src/app/docs/authenticate/multi-factor/page.tsx b/website/src/app/docs/authenticate/multi-factor/page.tsx deleted file mode 100644 index e726d6956..000000000 --- a/website/src/app/docs/authenticate/multi-factor/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/authenticate/multi-factor/readme.mdx b/website/src/app/docs/authenticate/multi-factor/readme.mdx deleted file mode 100644 index 42330dcdc..000000000 --- a/website/src/app/docs/authenticate/multi-factor/readme.mdx +++ /dev/null @@ -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) diff --git a/website/src/app/docs/authenticate/oidc/auth0/_page.tsx b/website/src/app/docs/authenticate/oidc/auth0/_page.tsx deleted file mode 100644 index 5b854431b..000000000 --- a/website/src/app/docs/authenticate/oidc/auth0/_page.tsx +++ /dev/null @@ -1,7 +0,0 @@ -"use client"; - -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/authenticate/oidc/auth0/page.tsx b/website/src/app/docs/authenticate/oidc/auth0/page.tsx deleted file mode 100644 index e0e2ee0a0..000000000 --- a/website/src/app/docs/authenticate/oidc/auth0/page.tsx +++ /dev/null @@ -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 />; -} diff --git a/website/src/app/docs/authenticate/oidc/auth0/readme.mdx b/website/src/app/docs/authenticate/oidc/auth0/readme.mdx deleted file mode 100644 index 88d88e35d..000000000 --- a/website/src/app/docs/authenticate/oidc/auth0/readme.mdx +++ /dev/null @@ -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. - -auth0 configuration - -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:///.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//callback/` (e.g. - `https://firezone.example.com/auth/oidc/auth0/callback/`). - -auth0 settings 1 -auth0 settings 2 -auth0 settings 3 - -## 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. diff --git a/website/src/app/docs/authenticate/oidc/azuread/_page.tsx b/website/src/app/docs/authenticate/oidc/azuread/_page.tsx deleted file mode 100644 index 5b854431b..000000000 --- a/website/src/app/docs/authenticate/oidc/azuread/_page.tsx +++ /dev/null @@ -1,7 +0,0 @@ -"use client"; - -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/authenticate/oidc/azuread/page.tsx b/website/src/app/docs/authenticate/oidc/azuread/page.tsx deleted file mode 100644 index c4311e242..000000000 --- a/website/src/app/docs/authenticate/oidc/azuread/page.tsx +++ /dev/null @@ -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 />; -} diff --git a/website/src/app/docs/authenticate/oidc/azuread/readme.mdx b/website/src/app/docs/authenticate/oidc/azuread/readme.mdx deleted file mode 100644 index 75c7d0376..000000000 --- a/website/src/app/docs/authenticate/oidc/azuread/readme.mdx +++ /dev/null @@ -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. - -azure sso login - -## 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//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).** - -azure app registration - -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**. - -azure client id - -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**. - -azure client secret - -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. - -azure permissions - -## 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. diff --git a/website/src/app/docs/authenticate/oidc/google/_page.tsx b/website/src/app/docs/authenticate/oidc/google/_page.tsx deleted file mode 100644 index 5b854431b..000000000 --- a/website/src/app/docs/authenticate/oidc/google/_page.tsx +++ /dev/null @@ -1,7 +0,0 @@ -"use client"; - -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/authenticate/oidc/google/page.tsx b/website/src/app/docs/authenticate/oidc/google/page.tsx deleted file mode 100644 index 78745ead8..000000000 --- a/website/src/app/docs/authenticate/oidc/google/page.tsx +++ /dev/null @@ -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 />; -} diff --git a/website/src/app/docs/authenticate/oidc/google/readme.mdx b/website/src/app/docs/authenticate/oidc/google/readme.mdx deleted file mode 100644 index c2df6023b..000000000 --- a/website/src/app/docs/authenticate/oidc/google/readme.mdx +++ /dev/null @@ -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. - -firezone google sso login - -## 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. - -oauth consent internal - -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. - -oauth consent app info - -On the next step add the following scopes: - -oauth consent scopes - -## 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`. - -create oauth client id - -On the OAuth client ID creation screen: - -1. Set `Application Type` to `Web application` -1. Add your Firezone `EXTERNAL_URL + /auth/oidc//callback/` (e.g. - `https://firezone.example.com/auth/oidc/google/callback/`) as an entry to - Authorized redirect URIs. - -create oauth client id - -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. diff --git a/website/src/app/docs/authenticate/oidc/keycloak/_page.tsx b/website/src/app/docs/authenticate/oidc/keycloak/_page.tsx deleted file mode 100644 index 5b854431b..000000000 --- a/website/src/app/docs/authenticate/oidc/keycloak/_page.tsx +++ /dev/null @@ -1,7 +0,0 @@ -"use client"; - -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/authenticate/oidc/keycloak/page.tsx b/website/src/app/docs/authenticate/oidc/keycloak/page.tsx deleted file mode 100644 index 7a054c9dd..000000000 --- a/website/src/app/docs/authenticate/oidc/keycloak/page.tsx +++ /dev/null @@ -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 />; -} diff --git a/website/src/app/docs/authenticate/oidc/keycloak/readme.mdx b/website/src/app/docs/authenticate/oidc/keycloak/readme.mdx deleted file mode 100644 index faeea6819..000000000 --- a/website/src/app/docs/authenticate/oidc/keycloak/readme.mdx +++ /dev/null @@ -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. - -keycloak realm - -### 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**. - -create firezone client - -1. Toggle **Client authentication** to `On` to generate the client secret. -1. Click **Save**. - -save firezone client - -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//callback/` (e.g. - `https://firezone.example.com/auth/oidc/keycloak/callback/`). -1. Click **Add valid redirect URIs** - -firezone access settings - -Click the **Credentials** tab and copy the client secret. - -firezone client secret - -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. - -keycloak realm settings - -## 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. diff --git a/website/src/app/docs/authenticate/oidc/okta/_page.tsx b/website/src/app/docs/authenticate/oidc/okta/_page.tsx deleted file mode 100644 index 5b854431b..000000000 --- a/website/src/app/docs/authenticate/oidc/okta/_page.tsx +++ /dev/null @@ -1,7 +0,0 @@ -"use client"; - -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/authenticate/oidc/okta/page.tsx b/website/src/app/docs/authenticate/oidc/okta/page.tsx deleted file mode 100644 index ee8359909..000000000 --- a/website/src/app/docs/authenticate/oidc/okta/page.tsx +++ /dev/null @@ -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 />; -} diff --git a/website/src/app/docs/authenticate/oidc/okta/readme.mdx b/website/src/app/docs/authenticate/oidc/okta/readme.mdx deleted file mode 100644 index e1bc0caec..000000000 --- a/website/src/app/docs/authenticate/oidc/okta/readme.mdx +++ /dev/null @@ -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. - -firezone okta sso login - -## 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**. - -okta create options - -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//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. - -okta settings - -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. - -okta credentials - -## 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. - -okta assignments diff --git a/website/src/app/docs/authenticate/oidc/onelogin/_page.tsx b/website/src/app/docs/authenticate/oidc/onelogin/_page.tsx deleted file mode 100644 index 5b854431b..000000000 --- a/website/src/app/docs/authenticate/oidc/onelogin/_page.tsx +++ /dev/null @@ -1,7 +0,0 @@ -"use client"; - -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/authenticate/oidc/onelogin/page.tsx b/website/src/app/docs/authenticate/oidc/onelogin/page.tsx deleted file mode 100644 index 3f2595e30..000000000 --- a/website/src/app/docs/authenticate/oidc/onelogin/page.tsx +++ /dev/null @@ -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 />; -} diff --git a/website/src/app/docs/authenticate/oidc/onelogin/readme.mdx b/website/src/app/docs/authenticate/oidc/onelogin/readme.mdx deleted file mode 100644 index 4ad0e8b06..000000000 --- a/website/src/app/docs/authenticate/oidc/onelogin/readme.mdx +++ /dev/null @@ -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 - ` + /auth/oidc//callback/` (e.g. - `https://firezone.example.com/auth/oidc/onelogin/callback/`). - -onelogin configuration - -## 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. - -onelogin config parameters - -## 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. diff --git a/website/src/app/docs/authenticate/oidc/page.tsx b/website/src/app/docs/authenticate/oidc/page.tsx deleted file mode 100644 index ab6038b4f..000000000 --- a/website/src/app/docs/authenticate/oidc/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/authenticate/oidc/readme.mdx b/website/src/app/docs/authenticate/oidc/readme.mdx deleted file mode 100644 index f9edd6ea4..000000000 --- a/website/src/app/docs/authenticate/oidc/readme.mdx +++ /dev/null @@ -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//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. diff --git a/website/src/app/docs/authenticate/oidc/zitadel/_page.tsx b/website/src/app/docs/authenticate/oidc/zitadel/_page.tsx deleted file mode 100644 index 5b854431b..000000000 --- a/website/src/app/docs/authenticate/oidc/zitadel/_page.tsx +++ /dev/null @@ -1,7 +0,0 @@ -"use client"; - -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/authenticate/oidc/zitadel/page.tsx b/website/src/app/docs/authenticate/oidc/zitadel/page.tsx deleted file mode 100644 index a6634fe71..000000000 --- a/website/src/app/docs/authenticate/oidc/zitadel/page.tsx +++ /dev/null @@ -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 />; -} diff --git a/website/src/app/docs/authenticate/oidc/zitadel/readme.mdx b/website/src/app/docs/authenticate/oidc/zitadel/readme.mdx deleted file mode 100644 index 9cce15c1f..000000000 --- a/website/src/app/docs/authenticate/oidc/zitadel/readme.mdx +++ /dev/null @@ -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. - -firezone zitadel sso login - -## 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**. - -zitadel new application - -Give the application a name (e.g. "Firezone") and select **WEB** for the -application type. - -zitadel name application - -Select **CODE** for the authentication method. - -zitadel auth method - -Specify the redirect URI and post logout URI. - -1. **Redirect URIs**: `EXTERNAL_URL + /auth/oidc//callback/` (e.g. - `https://vpn.example.com/auth/oidc/zitadel/callback/`) -1. **Post Logout URIs**: `EXTERNAL_URL` (e.g. `https://vpn.example.com`) - -zitadel uri - -Double-check the configuration, then click **Create**. - -zitadel configuration overview - -Copy the **ClientId** and **ClientSecret** as it will be used for the Firezone -configuration. - -zitadel client creds - -In the application **Configuration** click **Refresh Token** and then on -**Save**. The refresh token is optional for some features of Firezone. - -zitadel configuration - -In the application **Token Settings** select **User roles inside ID Token** and -**User Info inside ID Token**. Save it with a click on **Save**. - -zitadel token settings -![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. - -zitadel check authorization diff --git a/website/src/app/docs/authenticate/page.tsx b/website/src/app/docs/authenticate/page.tsx deleted file mode 100644 index eaa213c2f..000000000 --- a/website/src/app/docs/authenticate/page.tsx +++ /dev/null @@ -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 />; -} diff --git a/website/src/app/docs/authenticate/readme.mdx b/website/src/app/docs/authenticate/readme.mdx deleted file mode 100644 index fa931e155..000000000 --- a/website/src/app/docs/authenticate/readme.mdx +++ /dev/null @@ -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) - - - If your Identity Provider doesn't work with the methods listed above, [contact - us](/contact/sales) about a custom integration. - - -## 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: - -
- config-oidc -
- -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. - - diff --git a/website/src/app/docs/authenticate/saml/google/_page.tsx b/website/src/app/docs/authenticate/saml/google/_page.tsx deleted file mode 100644 index 5b854431b..000000000 --- a/website/src/app/docs/authenticate/saml/google/_page.tsx +++ /dev/null @@ -1,7 +0,0 @@ -"use client"; - -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/authenticate/saml/google/page.tsx b/website/src/app/docs/authenticate/saml/google/page.tsx deleted file mode 100644 index 99172a153..000000000 --- a/website/src/app/docs/authenticate/saml/google/page.tsx +++ /dev/null @@ -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 />; -} diff --git a/website/src/app/docs/authenticate/saml/google/readme.mdx b/website/src/app/docs/authenticate/saml/google/readme.mdx deleted file mode 100644 index 5c0b7d3b2..000000000 --- a/website/src/app/docs/authenticate/saml/google/readme.mdx +++ /dev/null @@ -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 | - -google saml - -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. | - -firezone saml - -After saving the SAML config, you should see a `Sign in with Google` button on -your Firezone portal sign-in page. diff --git a/website/src/app/docs/authenticate/saml/jumpcloud/_page.tsx b/website/src/app/docs/authenticate/saml/jumpcloud/_page.tsx deleted file mode 100644 index 5b854431b..000000000 --- a/website/src/app/docs/authenticate/saml/jumpcloud/_page.tsx +++ /dev/null @@ -1,7 +0,0 @@ -"use client"; - -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/authenticate/saml/jumpcloud/page.tsx b/website/src/app/docs/authenticate/saml/jumpcloud/page.tsx deleted file mode 100644 index d189f1233..000000000 --- a/website/src/app/docs/authenticate/saml/jumpcloud/page.tsx +++ /dev/null @@ -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 />; -} diff --git a/website/src/app/docs/authenticate/saml/jumpcloud/readme.mdx b/website/src/app/docs/authenticate/saml/jumpcloud/readme.mdx deleted file mode 100644 index ca049ac99..000000000 --- a/website/src/app/docs/authenticate/saml/jumpcloud/readme.mdx +++ /dev/null @@ -1,81 +0,0 @@ -import Alert from "@/components/DocsAlert"; -import Image from "next/image"; - -# Enable SSO with JumpCloud (SAML 2.0) - - - This guide assumes you have completed the prerequisite steps (e.g. generate - self-signed X.509 certificates) outlined - here. - - -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: - -jumpcloud saml - -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: - -firezone saml - -After saving the SAML config, you should see a `Sign in with JumpCloud` button -on your Firezone portal sign-in page. diff --git a/website/src/app/docs/authenticate/saml/okta/_page.tsx b/website/src/app/docs/authenticate/saml/okta/_page.tsx deleted file mode 100644 index 9d0d1db44..000000000 --- a/website/src/app/docs/authenticate/saml/okta/_page.tsx +++ /dev/null @@ -1,5 +0,0 @@ -"use client"; -import Content from "./readme.mdx"; -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/authenticate/saml/okta/page.tsx b/website/src/app/docs/authenticate/saml/okta/page.tsx deleted file mode 100644 index 6fd84fce4..000000000 --- a/website/src/app/docs/authenticate/saml/okta/page.tsx +++ /dev/null @@ -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 />; -} diff --git a/website/src/app/docs/authenticate/saml/okta/readme.mdx b/website/src/app/docs/authenticate/saml/okta/readme.mdx deleted file mode 100644 index ff068c541..000000000 --- a/website/src/app/docs/authenticate/saml/okta/readme.mdx +++ /dev/null @@ -1,71 +0,0 @@ -import Image from "next/image"; -import Alert from "@/components/DocsAlert"; - -# Enable SSO with Okta (SAML 2.0) - - - This guide assumes you have completed the prerequisite steps (e.g. generate - self-signed X.509 certificates) outlined - [here](/docs/authenticate/saml#prerequisites). - - -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. - -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. | - -firezone saml - -After saving the SAML config, you should see a `Sign in with Okta` button on -your Firezone portal sign-in page. diff --git a/website/src/app/docs/authenticate/saml/onelogin/_page.tsx b/website/src/app/docs/authenticate/saml/onelogin/_page.tsx deleted file mode 100644 index 5b854431b..000000000 --- a/website/src/app/docs/authenticate/saml/onelogin/_page.tsx +++ /dev/null @@ -1,7 +0,0 @@ -"use client"; - -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/authenticate/saml/onelogin/page.tsx b/website/src/app/docs/authenticate/saml/onelogin/page.tsx deleted file mode 100644 index 992483a2f..000000000 --- a/website/src/app/docs/authenticate/saml/onelogin/page.tsx +++ /dev/null @@ -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 />; -} diff --git a/website/src/app/docs/authenticate/saml/onelogin/readme.mdx b/website/src/app/docs/authenticate/saml/onelogin/readme.mdx deleted file mode 100644 index 48e08bd3a..000000000 --- a/website/src/app/docs/authenticate/saml/onelogin/readme.mdx +++ /dev/null @@ -1,75 +0,0 @@ -import Alert from "@/components/DocsAlert"; -import Image from "next/image"; - -# Enable SSO with OneLogin (SAML 2.0) - - - This guide assumes you have completed the prerequisite steps (e.g. generate - self-signed X.509 certificates) outlined - [here](/docs/authenticate/saml#prerequisites). - - -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. - -onelogin configs - -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. | - -onelogin saml - -After saving the SAML config, you should see a `Sign in with OneLogin` button on -your Firezone portal sign-in page. diff --git a/website/src/app/docs/authenticate/saml/page.tsx b/website/src/app/docs/authenticate/saml/page.tsx deleted file mode 100644 index 982266ad5..000000000 --- a/website/src/app/docs/authenticate/saml/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/authenticate/saml/readme.mdx b/website/src/app/docs/authenticate/saml/readme.mdx deleted file mode 100644 index 0a724b8b9..000000000 --- a/website/src/app/docs/authenticate/saml/readme.mdx +++ /dev/null @@ -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: - - - - -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. - - - - -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. - - - - -## 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. diff --git a/website/src/app/docs/banner.mdx b/website/src/app/docs/banner.mdx deleted file mode 100644 index 0ea6b94f2..000000000 --- a/website/src/app/docs/banner.mdx +++ /dev/null @@ -1,6 +0,0 @@ -import Alert from "@/components/DocsAlert"; - - - You're viewing documentation for the legacy version of Firezone, now - End-of-Life. [View the latest docs here](/kb). - diff --git a/website/src/app/docs/deploy/advanced/build-from-source/page.tsx b/website/src/app/docs/deploy/advanced/build-from-source/page.tsx deleted file mode 100644 index 047cfbca0..000000000 --- a/website/src/app/docs/deploy/advanced/build-from-source/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/deploy/advanced/build-from-source/readme.mdx b/website/src/app/docs/deploy/advanced/build-from-source/readme.mdx deleted file mode 100644 index 6ed3bf318..000000000 --- a/website/src/app/docs/deploy/advanced/build-from-source/readme.mdx +++ /dev/null @@ -1,94 +0,0 @@ -import Alert from "@/components/DocsAlert"; - -# Build From Source - -Building from source allows you to bring Firezone to unsupported platforms. - - - 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. - - - - 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). - - -## Prerequisites - - - 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. - - -**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 `/_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 :) - - - 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! - diff --git a/website/src/app/docs/deploy/advanced/external-database/page.tsx b/website/src/app/docs/deploy/advanced/external-database/page.tsx deleted file mode 100644 index 0083eb16f..000000000 --- a/website/src/app/docs/deploy/advanced/external-database/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/deploy/advanced/external-database/readme.mdx b/website/src/app/docs/deploy/advanced/external-database/readme.mdx deleted file mode 100644 index e5aa1581d..000000000 --- a/website/src/app/docs/deploy/advanced/external-database/readme.mdx +++ /dev/null @@ -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. - - - 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. - - -## Configure Firezone to Connect - - - - -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). - - - 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. - - - - - -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). - - - diff --git a/website/src/app/docs/deploy/advanced/reverse-proxy/page.tsx b/website/src/app/docs/deploy/advanced/reverse-proxy/page.tsx deleted file mode 100644 index 88a5a0ed7..000000000 --- a/website/src/app/docs/deploy/advanced/reverse-proxy/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/deploy/advanced/reverse-proxy/readme.mdx b/website/src/app/docs/deploy/advanced/reverse-proxy/readme.mdx deleted file mode 100644 index 32465251e..000000000 --- a/website/src/app/docs/deploy/advanced/reverse-proxy/readme.mdx +++ /dev/null @@ -1,108 +0,0 @@ -import Alert from "@/components/DocsAlert"; - -# Custom Reverse Proxy - - - 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. - - -## 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. - - -
- 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. - -
- - -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. diff --git a/website/src/app/docs/deploy/configure/page.tsx b/website/src/app/docs/deploy/configure/page.tsx deleted file mode 100644 index 5b8cb06b0..000000000 --- a/website/src/app/docs/deploy/configure/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/deploy/configure/readme.mdx b/website/src/app/docs/deploy/configure/readme.mdx deleted file mode 100644 index a06c4204a..000000000 --- a/website/src/app/docs/deploy/configure/readme.mdx +++ /dev/null @@ -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. - - - - -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. - - - - -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). - - - diff --git a/website/src/app/docs/deploy/docker/page.tsx b/website/src/app/docs/deploy/docker/page.tsx deleted file mode 100644 index 78518fc75..000000000 --- a/website/src/app/docs/deploy/docker/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/deploy/docker/readme.mdx b/website/src/app/docs/deploy/docker/readme.mdx deleted file mode 100644 index 44d560700..000000000 --- a/website/src/app/docs/deploy/docker/readme.mdx +++ /dev/null @@ -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. - - - 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. - - -## 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 - - - Firezone currently uses WireGuard's [open-source client - apps](https://www.wireguard.com/install). - - -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. - - - -## 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) diff --git a/website/src/app/docs/deploy/docker/supported-platforms/page.tsx b/website/src/app/docs/deploy/docker/supported-platforms/page.tsx deleted file mode 100644 index 641a0e355..000000000 --- a/website/src/app/docs/deploy/docker/supported-platforms/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/deploy/docker/supported-platforms/readme.mdx b/website/src/app/docs/deploy/docker/supported-platforms/readme.mdx deleted file mode 100644 index f76b8fc04..000000000 --- a/website/src/app/docs/deploy/docker/supported-platforms/readme.mdx +++ /dev/null @@ -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. diff --git a/website/src/app/docs/deploy/omnibus/_page.tsx b/website/src/app/docs/deploy/omnibus/_page.tsx deleted file mode 100644 index 5b854431b..000000000 --- a/website/src/app/docs/deploy/omnibus/_page.tsx +++ /dev/null @@ -1,7 +0,0 @@ -"use client"; - -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/deploy/omnibus/page.tsx b/website/src/app/docs/deploy/omnibus/page.tsx deleted file mode 100644 index 246d7e1ed..000000000 --- a/website/src/app/docs/deploy/omnibus/page.tsx +++ /dev/null @@ -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 />; -} diff --git a/website/src/app/docs/deploy/omnibus/readme.mdx b/website/src/app/docs/deploy/omnibus/readme.mdx deleted file mode 100644 index ac43db12c..000000000 --- a/website/src/app/docs/deploy/omnibus/readme.mdx +++ /dev/null @@ -1,201 +0,0 @@ -import Image from "next/image"; -import Alert from "@/components/DocsAlert"; -import SupportOptions from "@/components/SupportOptions"; - -# Install Firezone with Omnibus - - - 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. - - -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. - - - 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. - - - - 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) - - -## 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. - -install complete - -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. - - - -## 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) diff --git a/website/src/app/docs/deploy/omnibus/supported-platforms/page.tsx b/website/src/app/docs/deploy/omnibus/supported-platforms/page.tsx deleted file mode 100644 index e7f5c3130..000000000 --- a/website/src/app/docs/deploy/omnibus/supported-platforms/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/deploy/omnibus/supported-platforms/readme.mdx b/website/src/app/docs/deploy/omnibus/supported-platforms/readme.mdx deleted file mode 100644 index 04d91ea82..000000000 --- a/website/src/app/docs/deploy/omnibus/supported-platforms/readme.mdx +++ /dev/null @@ -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 -``` diff --git a/website/src/app/docs/deploy/page.tsx b/website/src/app/docs/deploy/page.tsx deleted file mode 100644 index 735c15700..000000000 --- a/website/src/app/docs/deploy/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/deploy/readme.mdx b/website/src/app/docs/deploy/readme.mdx deleted file mode 100644 index 8c1b7b0f7..000000000 --- a/website/src/app/docs/deploy/readme.mdx +++ /dev/null @@ -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. - - - - -#### 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. - - - - -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. - - - - -### 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. - - - 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). - diff --git a/website/src/app/docs/deploy/security-considerations/page.tsx b/website/src/app/docs/deploy/security-considerations/page.tsx deleted file mode 100644 index 7a5d869e4..000000000 --- a/website/src/app/docs/deploy/security-considerations/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/deploy/security-considerations/readme.mdx b/website/src/app/docs/deploy/security-considerations/readme.mdx deleted file mode 100644 index 843f21de9..000000000 --- a/website/src/app/docs/deploy/security-considerations/readme.mdx +++ /dev/null @@ -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. - - - - -| 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. | - - - - -| 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. | - - - - -## 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. - - - 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. - - -## 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). diff --git a/website/src/app/docs/layout.tsx b/website/src/app/docs/layout.tsx deleted file mode 100644 index 89a9da8fb..000000000 --- a/website/src/app/docs/layout.tsx +++ /dev/null @@ -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 ( -
- -
-
-
- - {children} -
-
- -
-
-
-
- ); -} diff --git a/website/src/app/docs/page.tsx b/website/src/app/docs/page.tsx deleted file mode 100644 index dbedf9bc0..000000000 --- a/website/src/app/docs/page.tsx +++ /dev/null @@ -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 />; -} diff --git a/website/src/app/docs/readme.mdx b/website/src/app/docs/readme.mdx deleted file mode 100644 index c88ddea9a..000000000 --- a/website/src/app/docs/readme.mdx +++ /dev/null @@ -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. - -firezone architecture - -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. - - - -## 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). diff --git a/website/src/app/docs/reference/configuration-file/page.tsx b/website/src/app/docs/reference/configuration-file/page.tsx deleted file mode 100644 index 6b9e90e73..000000000 --- a/website/src/app/docs/reference/configuration-file/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/reference/configuration-file/readme.mdx b/website/src/app/docs/reference/configuration-file/readme.mdx deleted file mode 100644 index 8384980f5..000000000 --- a/website/src/app/docs/reference/configuration-file/readme.mdx +++ /dev/null @@ -1,180 +0,0 @@ -import Alert from "@/components/DocsAlert"; - -# Omnibus configuration options - - - This reference is written for Omnibus-based deployments of Firezone. For - Docker-based deployments visit the [Environment - Variables](/docs/reference/env-vars) page. - - -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` | diff --git a/website/src/app/docs/reference/env-vars/page.tsx b/website/src/app/docs/reference/env-vars/page.tsx deleted file mode 100644 index d0c5e68b2..000000000 --- a/website/src/app/docs/reference/env-vars/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/reference/env-vars/readme.mdx b/website/src/app/docs/reference/env-vars/readme.mdx deleted file mode 100644 index 9f7c560dc..000000000 --- a/website/src/app/docs/reference/env-vars/readme.mdx +++ /dev/null @@ -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.

Must be a valid and public FQDN for ACME SSL issuance to function.

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.

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.

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.

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.

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

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.

Typically, to enabled SSL you want following options:
- `cacertfile` - path to the CA certificate file;
- `verify` - set to `verify_peer` to verify the server certificate;
- `fail_if_no_peer_cert` - set to `true` to require the server to present a certificate;
- `server_name_indication` - specify the hostname to be used in TLS Server Name Indication extension.

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.

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

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.

It can be either an IP address or a FQDN if you intend to use a DNS-over-TLS server.

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.

AllowedIPs determines which destination IPs get routed through Firezone.

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.

For example:

`[ { "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" } ]`

For more details see https://docs.firezone.dev/authenticate/oidc/. | JSON-encoded list | `"[]"` | -| SAML_IDENTITY_PROVIDERS | List of SAML identity providers configurations.

For example:

`[ { "auto_create_users": false, "base_url": "https://saml", "id": "okta", "label": "okta", "metadata": "...", "sign_metadata": false, "sign_requests": false, "signed_assertion_in_resp": false, "signed_envelopes_in_resp": false } ]`

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.

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}` | `` | diff --git a/website/src/app/docs/reference/file-and-directory-locations/page.tsx b/website/src/app/docs/reference/file-and-directory-locations/page.tsx deleted file mode 100644 index 057f89c39..000000000 --- a/website/src/app/docs/reference/file-and-directory-locations/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/reference/file-and-directory-locations/readme.mdx b/website/src/app/docs/reference/file-and-directory-locations/readme.mdx deleted file mode 100644 index deef809c3..000000000 --- a/website/src/app/docs/reference/file-and-directory-locations/readme.mdx +++ /dev/null @@ -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. - - - - -| 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. | - - - - -| 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. | - - - - -## Backup and restore - -See our [backup guide](/docs/administer/backup). diff --git a/website/src/app/docs/reference/firewall-templates/nftables/page.tsx b/website/src/app/docs/reference/firewall-templates/nftables/page.tsx deleted file mode 100644 index bf4971d9a..000000000 --- a/website/src/app/docs/reference/firewall-templates/nftables/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/reference/firewall-templates/nftables/readme.mdx b/website/src/app/docs/reference/firewall-templates/nftables/readme.mdx deleted file mode 100644 index f9f1a8f26..000000000 --- a/website/src/app/docs/reference/firewall-templates/nftables/readme.mdx +++ /dev/null @@ -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. diff --git a/website/src/app/docs/reference/rest-api/configurations/page.tsx b/website/src/app/docs/reference/rest-api/configurations/page.tsx deleted file mode 100644 index a27c691df..000000000 --- a/website/src/app/docs/reference/rest-api/configurations/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/reference/rest-api/configurations/readme.mdx b/website/src/app/docs/reference/rest-api/configurations/readme.mdx deleted file mode 100644 index 0e158bf01..000000000 --- a/website/src/app/docs/reference/rest-api/configurations/readme.mdx +++ /dev/null @@ -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": "\n\n \n \n \n \n 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==\n \n \n \n urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified\n urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress\n \n \n \n\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": "\n\n \n \n \n \n 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==\n \n \n \n urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified\n urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress\n \n \n \n\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 - } -} -``` diff --git a/website/src/app/docs/reference/rest-api/devices/page.tsx b/website/src/app/docs/reference/rest-api/devices/page.tsx deleted file mode 100644 index 1a92de723..000000000 --- a/website/src/app/docs/reference/rest-api/devices/page.tsx +++ /dev/null @@ -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 ; -} diff --git a/website/src/app/docs/reference/rest-api/devices/readme.mdx b/website/src/app/docs/reference/rest-api/devices/readme.mdx deleted file mode 100644 index 6b8e8eaa2..000000000 --- a/website/src/app/docs/reference/rest-api/devices/readme.mdx +++ /dev/null @@ -1,422 +0,0 @@ -# REST API: Devices - -This endpoint allows an administrator to manage Devices. - -## API Documentation - -### GET /v0/devices - -#### Example - -```bash -$ curl -i \ - -X GET "https://{firezone_host}/v0/devices" \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {api_token}' \ - -HTTP/1.1 200 -Content-Type: application/json; charset=utf-8 - -{ - "data": [ - { - "allowed_ips": [ - "0.0.0.0/0", - "::/0" - ], - "description": "factory description", - "dns": [ - "1.1.1.1", - "1.0.0.1" - ], - "endpoint": "localhost:51820", - "id": "61d5930b-2b35-44b3-87a9-904e81806728", - "inserted_at": "2023-03-29T15:11:47.450107Z", - "ipv4": "100.72.98.240", - "ipv6": "fd00::39:bf15", - "latest_handshake": null, - "mtu": 1280, - "name": "factory 4421", - "persistent_keepalive": 25, - "preshared_key": "32vztut9u6QJG2spTUMnvcb+twugGlT1ikM6AyiPDv8=", - "public_key": "cGEIZje2ITjFDn96F3bItc5BCl8G1r4SWHH/6QUF4ek=", - "remote_ip": null, - "rx_bytes": null, - "server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=", - "tx_bytes": null, - "updated_at": "2023-03-29T15:11:47.450107Z", - "use_default_allowed_ips": true, - "use_default_dns": true, - "use_default_endpoint": true, - "use_default_mtu": true, - "use_default_persistent_keepalive": true, - "user_id": "56062619-2fe2-49de-898c-492d8da794c7" - }, - { - "allowed_ips": [ - "0.0.0.0/0", - "::/0" - ], - "description": "factory description", - "dns": [ - "1.1.1.1", - "1.0.0.1" - ], - "endpoint": "localhost:51820", - "id": "05db5d62-218e-4139-92f5-0510903ce4f8", - "inserted_at": "2023-03-29T15:11:47.455712Z", - "ipv4": "100.111.252.39", - "ipv6": "fd00::2:456a", - "latest_handshake": null, - "mtu": 1280, - "name": "factory 5411", - "persistent_keepalive": 25, - "preshared_key": "78O12m5lG+je3eAqlgJ9pd6d/+VeLjsswsljJFV0jU0=", - "public_key": "ADOmUjeMl08RgKNhpRaaaHV3YmI9GOVh81zLVLOPk84=", - "remote_ip": null, - "rx_bytes": null, - "server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=", - "tx_bytes": null, - "updated_at": "2023-03-29T15:11:47.455712Z", - "use_default_allowed_ips": true, - "use_default_dns": true, - "use_default_endpoint": true, - "use_default_mtu": true, - "use_default_persistent_keepalive": true, - "user_id": "9d3e2da3-bce1-4a03-95cc-d8d0a9797a17" - }, - { - "allowed_ips": [ - "0.0.0.0/0", - "::/0" - ], - "description": "factory description", - "dns": [ - "1.1.1.1", - "1.0.0.1" - ], - "endpoint": "localhost:51820", - "id": "c865c545-36bd-473e-9c20-9b76766582b2", - "inserted_at": "2023-03-29T15:11:47.461266Z", - "ipv4": "100.116.252.229", - "ipv6": "fd00::7:f039", - "latest_handshake": null, - "mtu": 1280, - "name": "factory 5766", - "persistent_keepalive": 25, - "preshared_key": "Dlefj06JAOOCtKxoSlLmvmNXq2zql30FvwDFlEpEISQ=", - "public_key": "hH9ifN5kI1RtnG54eUXGLEL7Pue9qgGvJ3Gvef7irzU=", - "remote_ip": null, - "rx_bytes": null, - "server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=", - "tx_bytes": null, - "updated_at": "2023-03-29T15:11:47.461266Z", - "use_default_allowed_ips": true, - "use_default_dns": true, - "use_default_endpoint": true, - "use_default_mtu": true, - "use_default_persistent_keepalive": true, - "user_id": "47a8eda4-433a-4ce3-a119-720b5d62ddac" - }, - { - "allowed_ips": [ - "0.0.0.0/0", - "::/0" - ], - "description": "factory description", - "dns": [ - "1.1.1.1", - "1.0.0.1" - ], - "endpoint": "localhost:51820", - "id": "93da8405-217e-40b3-a91b-45d8cd28c2d4", - "inserted_at": "2023-03-29T15:11:47.467794Z", - "ipv4": "100.70.183.42", - "ipv6": "fd00::9:a393", - "latest_handshake": null, - "mtu": 1280, - "name": "factory 1417", - "persistent_keepalive": 25, - "preshared_key": "3ipinU20+iTgqCZxSskRPRTBargqtoG73seKz8wZqiE=", - "public_key": "gzAOiYTnq+rFRBDUbRuJhKXCbe+ULB9xjpCy9l0mBCA=", - "remote_ip": null, - "rx_bytes": null, - "server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=", - "tx_bytes": null, - "updated_at": "2023-03-29T15:11:47.467794Z", - "use_default_allowed_ips": true, - "use_default_dns": true, - "use_default_endpoint": true, - "use_default_mtu": true, - "use_default_persistent_keepalive": true, - "user_id": "d8c001ca-ee0f-457f-80a6-802592a7d4ca" - }, - { - "allowed_ips": [ - "0.0.0.0/0", - "::/0" - ], - "description": "factory description", - "dns": [ - "1.1.1.1", - "1.0.0.1" - ], - "endpoint": "localhost:51820", - "id": "16b319c1-4d8a-478a-88d2-f17056bf1b66", - "inserted_at": "2023-03-29T15:11:47.473062Z", - "ipv4": "100.101.38.171", - "ipv6": "fd00::39:35af", - "latest_handshake": null, - "mtu": 1280, - "name": "factory 4485", - "persistent_keepalive": 25, - "preshared_key": "WzNqj8NEQBvYCYjWv4qhuL8sT3n0LVIH52x1xx5U6EE=", - "public_key": "eD1iqgs712xDZsplZHd7LrNs+WXYshMH99WFkJ0So8o=", - "remote_ip": null, - "rx_bytes": null, - "server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=", - "tx_bytes": null, - "updated_at": "2023-03-29T15:11:47.473062Z", - "use_default_allowed_ips": true, - "use_default_dns": true, - "use_default_endpoint": true, - "use_default_mtu": true, - "use_default_persistent_keepalive": true, - "user_id": "605c4532-d516-4b59-a7df-b0479d493cce" - } - ] -} -``` - -### POST /v0/devices - -#### Example - -```bash -$ curl -i \ - -X POST "https://{firezone_host}/v0/devices" \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {api_token}' \ - --data-binary @- << EOF -{ - "device": { - "allowed_ips": [ - "0.0.0.0/0", - "::/0", - "1.1.1.1" - ], - "description": "create-description", - "dns": [ - "9.9.9.8" - ], - "endpoint": "9.9.9.9", - "ipv4": "100.64.0.2", - "ipv6": "fd00::2", - "mtu": 999, - "name": "create-name", - "persistent_keepalive": 9, - "preshared_key": "CHqFuS+iL3FTog5F4Ceumqlk0CU4Cl/dyUP/9F9NDnI=", - "public_key": "CHqFuS+iL3FTog5F4Ceumqlk0CU4Cl/dyUP/9F9NDnI=", - "use_default_allowed_ips": false, - "use_default_dns": false, - "use_default_endpoint": false, - "use_default_mtu": false, - "use_default_persistent_keepalive": false, - "user_id": "95138a8e-c89f-41b4-b62c-a5b8c23a0b8c" - } -} -EOF - -HTTP/1.1 201 -Content-Type: application/json; charset=utf-8 -Location: /v0/devices/3aefe1b8-d98b-4725-bed3-cad021a13480 - -{ - "data": { - "allowed_ips": [ - "0.0.0.0/0", - "::/0", - "1.1.1.1" - ], - "description": "create-description", - "dns": [ - "9.9.9.8" - ], - "endpoint": "9.9.9.9", - "id": "3aefe1b8-d98b-4725-bed3-cad021a13480", - "inserted_at": "2023-03-29T15:11:47.190722Z", - "ipv4": "100.64.0.2", - "ipv6": "fd00::2", - "latest_handshake": null, - "mtu": 999, - "name": "create-name", - "persistent_keepalive": 9, - "preshared_key": "CHqFuS+iL3FTog5F4Ceumqlk0CU4Cl/dyUP/9F9NDnI=", - "public_key": "CHqFuS+iL3FTog5F4Ceumqlk0CU4Cl/dyUP/9F9NDnI=", - "remote_ip": null, - "rx_bytes": null, - "server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=", - "tx_bytes": null, - "updated_at": "2023-03-29T15:11:47.190722Z", - "use_default_allowed_ips": false, - "use_default_dns": false, - "use_default_endpoint": false, - "use_default_mtu": false, - "use_default_persistent_keepalive": false, - "user_id": "95138a8e-c89f-41b4-b62c-a5b8c23a0b8c" - } -} -``` - -### GET /v0/devices/\{id\} - -#### Example - -**URI Parameters:** - -- `id`: `f85310b7-87b5-4c89-b391-d985f7789007` - -```bash -$ curl -i \ - -X GET "https://{firezone_host}/v0/devices/{id}" \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {api_token}' \ - -HTTP/1.1 200 -Content-Type: application/json; charset=utf-8 - -{ - "data": { - "allowed_ips": [ - "0.0.0.0/0", - "::/0" - ], - "description": "factory description", - "dns": [ - "1.1.1.1", - "1.0.0.1" - ], - "endpoint": "localhost:51820", - "id": "f85310b7-87b5-4c89-b391-d985f7789007", - "inserted_at": "2023-03-29T15:11:47.299345Z", - "ipv4": "100.99.173.193", - "ipv6": "fd00::17:d1a9", - "latest_handshake": null, - "mtu": 1280, - "name": "factory 713", - "persistent_keepalive": 25, - "preshared_key": "qrcrAnUh7ryP69SwfseKdBNElOSjOC9/Wv7Z+EBxs50=", - "public_key": "mLN9py6whsGt+Lg9jP4lX+Cqqlf02plODqWg2UqOmPI=", - "remote_ip": null, - "rx_bytes": null, - "server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=", - "tx_bytes": null, - "updated_at": "2023-03-29T15:11:47.299345Z", - "use_default_allowed_ips": true, - "use_default_dns": true, - "use_default_endpoint": true, - "use_default_mtu": true, - "use_default_persistent_keepalive": true, - "user_id": "5f5b582d-9153-46ac-99e5-37a6bc93ce13" - } -} -``` - -### PATCH /v0/devices/\{id\} - -#### Example - -**URI Parameters:** - -- `id`: `01272ce2-df59-4816-9d82-44830427d757` - -```bash -$ curl -i \ - -X PUT "https://{firezone_host}/v0/devices/{id}" \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {api_token}' \ - --data-binary @- << EOF -{ - "device": { - "allowed_ips": [ - "0.0.0.0/0", - "::/0", - "1.1.1.1" - ], - "description": "create-description", - "dns": [ - "9.9.9.8" - ], - "endpoint": "9.9.9.9", - "ipv4": "100.64.0.2", - "ipv6": "fd00::2", - "mtu": 999, - "name": "create-name", - "persistent_keepalive": 9, - "preshared_key": "CHqFuS+iL3FTog5F4Ceumqlk0CU4Cl/dyUP/9F9NDnI=", - "public_key": "CHqFuS+iL3FTog5F4Ceumqlk0CU4Cl/dyUP/9F9NDnI=", - "use_default_allowed_ips": false, - "use_default_dns": false, - "use_default_endpoint": false, - "use_default_mtu": false, - "use_default_persistent_keepalive": false - } -} -EOF - -HTTP/1.1 200 -Content-Type: application/json; charset=utf-8 - -{ - "data": { - "allowed_ips": [ - "0.0.0.0/0", - "::/0", - "1.1.1.1" - ], - "description": "create-description", - "dns": [ - "9.9.9.8" - ], - "endpoint": "9.9.9.9", - "id": "01272ce2-df59-4816-9d82-44830427d757", - "inserted_at": "2023-03-29T15:11:47.264313Z", - "ipv4": "100.64.0.2", - "ipv6": "fd00::2", - "latest_handshake": null, - "mtu": 999, - "name": "create-name", - "persistent_keepalive": 9, - "preshared_key": "CHqFuS+iL3FTog5F4Ceumqlk0CU4Cl/dyUP/9F9NDnI=", - "public_key": "CHqFuS+iL3FTog5F4Ceumqlk0CU4Cl/dyUP/9F9NDnI=", - "remote_ip": null, - "rx_bytes": null, - "server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=", - "tx_bytes": null, - "updated_at": "2023-03-29T15:11:47.276849Z", - "use_default_allowed_ips": false, - "use_default_dns": false, - "use_default_endpoint": false, - "use_default_mtu": false, - "use_default_persistent_keepalive": false, - "user_id": "3f7c9d0f-fa89-4619-9237-f0215db34e58" - } -} -``` - -### DELETE /v0/devices/\{id\} - -#### Example - -**URI Parameters:** - -- `id`: `29f86ac9-82e8-4691-aa44-ea396d3af476` - -```bash -$ curl -i \ - -X DELETE "https://{firezone_host}/v0/devices/{id}" \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {api_token}' \ - -HTTP/1.1 204 -``` diff --git a/website/src/app/docs/reference/rest-api/page.tsx b/website/src/app/docs/reference/rest-api/page.tsx deleted file mode 100644 index c35e5fe64..000000000 --- a/website/src/app/docs/reference/rest-api/page.tsx +++ /dev/null @@ -1,11 +0,0 @@ -import Content from "./readme.mdx"; -import { Metadata } from "next"; - -export const metadata: Metadata = { - title: "REST API • Firezone Docs", - description: "REST API documentation for Firezone.", -}; - -export default function Page() { - return ; -} diff --git a/website/src/app/docs/reference/rest-api/readme.mdx b/website/src/app/docs/reference/rest-api/readme.mdx deleted file mode 100644 index 00f71373f..000000000 --- a/website/src/app/docs/reference/rest-api/readme.mdx +++ /dev/null @@ -1,26 +0,0 @@ -import Alert from "@/components/DocsAlert"; - -# REST API - -Welcome to Firezone's REST API v0 documentation. - -## Getting started - -To get started with the REST API, you'll first need an API token. This can be -generated in the UI at `/settings/account` or via the CLI with: - -```bash -docker compose -f $HOME/.firezone/docker-compose.yml exec firezone bin/create-api-token -``` - -**Note**: The token is written to `STDOUT` by default. You may wish to redirect -its output to a file instead: - -```bash -docker compose -f $HOME/.firezone/docker-compose.yml exec firezone bin/create-api-token > fz_token -``` - - - API tokens generated from the CLI are owned by the primary administrator - specified by the `DEFAULT_ADMIN_EMAIL` environment variable. - diff --git a/website/src/app/docs/reference/rest-api/rules/page.tsx b/website/src/app/docs/reference/rest-api/rules/page.tsx deleted file mode 100644 index 3e011f0f8..000000000 --- a/website/src/app/docs/reference/rest-api/rules/page.tsx +++ /dev/null @@ -1,11 +0,0 @@ -import Content from "./readme.mdx"; -import { Metadata } from "next"; - -export const metadata: Metadata = { - title: "REST API: Rules • Firezone Docs", - description: "REST API documentation for rules in Firezone.", -}; - -export default function Page() { - return ; -} diff --git a/website/src/app/docs/reference/rest-api/rules/readme.mdx b/website/src/app/docs/reference/rest-api/rules/readme.mdx deleted file mode 100644 index d75c2a618..000000000 --- a/website/src/app/docs/reference/rest-api/rules/readme.mdx +++ /dev/null @@ -1,202 +0,0 @@ -# REST API: Rules - -This endpoint allows an adminisrator to manage Rules. - -## API Documentation - -### GET /v0/rules - -#### Example - -```bash -$ curl -i \ - -X GET "https://{firezone_host}/v0/rules" \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {api_token}' \ - -HTTP/1.1 200 -Content-Type: application/json; charset=utf-8 - -{ - "data": [ - { - "action": "drop", - "destination": "10.3.2.1", - "id": "2a136a17-4d29-4d8b-a6d4-f35ee3051105", - "inserted_at": "2023-03-29T15:11:47.482818Z", - "port_range": null, - "port_type": null, - "updated_at": "2023-03-29T15:11:47.482818Z", - "user_id": null - }, - { - "action": "drop", - "destination": "10.3.2.2", - "id": "7a4961bf-6b2b-4217-b87b-ffd1deb448ac", - "inserted_at": "2023-03-29T15:11:47.483506Z", - "port_range": null, - "port_type": null, - "updated_at": "2023-03-29T15:11:47.483506Z", - "user_id": null - }, - { - "action": "drop", - "destination": "10.3.2.3", - "id": "6dffbc74-ec58-43ca-8700-d0c572baa198", - "inserted_at": "2023-03-29T15:11:47.484107Z", - "port_range": null, - "port_type": null, - "updated_at": "2023-03-29T15:11:47.484107Z", - "user_id": null - }, - { - "action": "drop", - "destination": "10.3.2.4", - "id": "9bba129d-cdad-4efe-8296-b78ba50f3ef4", - "inserted_at": "2023-03-29T15:11:47.484759Z", - "port_range": null, - "port_type": null, - "updated_at": "2023-03-29T15:11:47.484759Z", - "user_id": null - }, - { - "action": "drop", - "destination": "10.3.2.5", - "id": "df142fde-922c-4a6d-a8e4-0b145a875624", - "inserted_at": "2023-03-29T15:11:47.485540Z", - "port_range": null, - "port_type": null, - "updated_at": "2023-03-29T15:11:47.485540Z", - "user_id": null - } - ] -} -``` - -### POST /v0/rules - -#### Example - -```bash -$ curl -i \ - -X POST "https://{firezone_host}/v0/rules" \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {api_token}' \ - --data-binary @- << EOF -{ - "rule": { - "action": "accept", - "destination": "1.1.1.1/24", - "port_range": "1 - 2", - "port_type": "udp", - "user_id": "def4dacc-6367-4320-a0fb-4675b9b571cf" - } -} -EOF - -HTTP/1.1 201 -Content-Type: application/json; charset=utf-8 -Location: /v0/rules/c52efbe6-5ed0-4514-97df-93f6013dd52b - -{ - "data": { - "action": "accept", - "destination": "1.1.1.1/24", - "id": "c52efbe6-5ed0-4514-97df-93f6013dd52b", - "inserted_at": "2023-03-29T15:11:47.185000Z", - "port_range": "1 - 2", - "port_type": "udp", - "updated_at": "2023-03-29T15:11:47.185000Z", - "user_id": "def4dacc-6367-4320-a0fb-4675b9b571cf" - } -} -``` - -### GET /v0/rules/\{id\} - -#### Example - -**URI Parameters:** - -- `id`: `dd39b339-2ac4-4c83-96e5-9b29516dd85e` - -```bash -$ curl -i \ - -X GET "https://{firezone_host}/v0/rules/{id}" \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {api_token}' \ - -HTTP/1.1 200 -Content-Type: application/json; charset=utf-8 - -{ - "data": { - "action": "drop", - "destination": "10.10.10.0/24", - "id": "dd39b339-2ac4-4c83-96e5-9b29516dd85e", - "inserted_at": "2023-03-29T15:11:47.447659Z", - "port_range": null, - "port_type": null, - "updated_at": "2023-03-29T15:11:47.447659Z", - "user_id": null - } -} -``` - -### PATCH /v0/rules/\{id\} - -#### Example - -**URI Parameters:** - -- `id`: `720fdab6-32af-4487-bce5-e72fa76be829` - -```bash -$ curl -i \ - -X PUT "https://{firezone_host}/v0/rules/{id}" \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {api_token}' \ - --data-binary @- << EOF -{ - "rule": { - "action": "accept", - "destination": "1.1.1.1/24", - "port_range": "1 - 2", - "port_type": "udp" - } -} -EOF - -HTTP/1.1 200 -Content-Type: application/json; charset=utf-8 - -{ - "data": { - "action": "accept", - "destination": "1.1.1.1/24", - "id": "720fdab6-32af-4487-bce5-e72fa76be829", - "inserted_at": "2023-03-29T15:11:47.243306Z", - "port_range": "1 - 2", - "port_type": "udp", - "updated_at": "2023-03-29T15:11:47.251589Z", - "user_id": null - } -} -``` - -### DELETE /v0/rules/\{id\} - -#### Example - -**URI Parameters:** - -- `id`: `f5f10a6e-cfdd-47ea-ae23-264195b3503c` - -```bash -$ curl -i \ - -X DELETE "https://{firezone_host}/v0/rules/{id}" \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {api_token}' \ - -HTTP/1.1 204 -``` diff --git a/website/src/app/docs/reference/rest-api/users/page.tsx b/website/src/app/docs/reference/rest-api/users/page.tsx deleted file mode 100644 index f1f499936..000000000 --- a/website/src/app/docs/reference/rest-api/users/page.tsx +++ /dev/null @@ -1,11 +0,0 @@ -import Content from "./readme.mdx"; -import { Metadata } from "next"; - -export const metadata: Metadata = { - title: "REST API: Users • Firezone Docs", - description: "REST API documentation for users in Firezone.", -}; - -export default function Page() { - return ; -} diff --git a/website/src/app/docs/reference/rest-api/users/readme.mdx b/website/src/app/docs/reference/rest-api/users/readme.mdx deleted file mode 100644 index abac05909..000000000 --- a/website/src/app/docs/reference/rest-api/users/readme.mdx +++ /dev/null @@ -1,377 +0,0 @@ -# REST API: Users - -This endpoint allows an administrator to manage Users. - -## Auto-Create Users from OpenID or SAML providers - -You can set Configuration option `auto_create_users` to `true` to automatically -create users from OpenID or SAML providers. Use it with care as anyone with -access to the provider will be able to log-in to Firezone. - -If `auto_create_users` is `false`, then you need to provision users with -`password` attribute, otherwise they will have no means to log in. - -## Disabling users - -Even though API returns `disabled_at` attribute, currently, it's not possible to -disable users via API, since this field is only for internal use by automatic -user disabling mechanism on OIDC/SAML errors. - -## API Documentation - -### List all Users [`GET /v0/users`] - -#### Example - -```bash -$ curl -i \ - -X GET "https://{firezone_host}/v0/users" \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {api_token}' \ - -HTTP/1.1 200 -Content-Type: application/json; charset=utf-8 - -{ - "data": [ - { - "disabled_at": null, - "email": "test-5094@test", - "id": "4963a5f0-dbb5-424a-8859-8032209eeaef", - "inserted_at": "2023-03-29T15:11:47.363517Z", - "last_signed_in_at": null, - "last_signed_in_method": null, - "role": "admin", - "updated_at": "2023-03-29T15:11:47.363517Z" - }, - { - "disabled_at": null, - "email": "test-5634@test", - "id": "e904d9ae-c358-4ab4-9bfd-44b4bf942a15", - "inserted_at": "2023-03-29T15:11:47.364938Z", - "last_signed_in_at": null, - "last_signed_in_method": null, - "role": "admin", - "updated_at": "2023-03-29T15:11:47.364938Z" - }, - { - "disabled_at": null, - "email": "test-5666@test", - "id": "e7decf88-4abb-45df-9dd0-35e3587dfb59", - "inserted_at": "2023-03-29T15:11:47.366068Z", - "last_signed_in_at": null, - "last_signed_in_method": null, - "role": "admin", - "updated_at": "2023-03-29T15:11:47.366068Z" - }, - { - "disabled_at": null, - "email": "test-5190@test", - "id": "457aeee0-13aa-44b3-9057-181cc206edcb", - "inserted_at": "2023-03-29T15:11:47.367568Z", - "last_signed_in_at": null, - "last_signed_in_method": null, - "role": "admin", - "updated_at": "2023-03-29T15:11:47.367568Z" - } - ] -} -``` - -### Create a User [`POST /v0/users`] - -Create a new User. - -This endpoint is useful in two cases: - -1. When [Local Authentication](/docs/authenticate/local-auth) is enabled - (discouraged in production deployments), it allows an administrator to - provision users with their passwords; -2. When `auto_create_users` in the associated OpenID or SAML configuration is - disabled, it allows an administrator to provision users with their emails - beforehand, effectively whitelisting specific users for authentication. - -If `auto_create_users` is `true` in the associated OpenID or SAML configuration, -there is no need to provision users; they will be created automatically when -they log in for the first time using the associated OpenID or SAML provider. - -#### User Attributes - -| Attribute | Type | Required | Description | -| ----------------------- | ----------------------------------- | -------- | -------------------------------------------------------------- | -| `role` | `admin` or `unprivileged` (default) | No | User role. | -| `email` | `string` | Yes | Email which will be used to identify the user. | -| `password` | `string` | No | A password that can be used for login-password authentication. | -| `password_confirmation` | `string` | -> | Is required when the `password` is set. | - -#### Example - -```bash -$ curl -i \ - -X POST "https://{firezone_host}/v0/users" \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {api_token}' \ - --data-binary @- << EOF -{ - "user": { - "email": "new-user@test", - "password": "test1234test", - "password_confirmation": "test1234test", - "role": "unprivileged" - } -} -EOF - -HTTP/1.1 201 -Content-Type: application/json; charset=utf-8 -Location: /v0/users/2b7128fb-4a30-472d-9f45-d2a5063ba5db - -{ - "data": { - "disabled_at": null, - "email": "new-user@test", - "id": "2b7128fb-4a30-472d-9f45-d2a5063ba5db", - "inserted_at": "2023-03-29T15:11:47.178709Z", - "last_signed_in_at": null, - "last_signed_in_method": null, - "role": "unprivileged", - "updated_at": "2023-03-29T15:11:47.178709Z" - } -} -``` - -#### Provision an unprivileged OpenID User - -```bash -$ curl -i \ - -X POST "https://{firezone_host}/v0/users" \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {api_token}' \ - --data-binary @- << EOF -{ - "user": { - "email": "new-user@test", - "role": "unprivileged" - } -} -EOF - -HTTP/1.1 201 -Content-Type: application/json; charset=utf-8 -Location: /v0/users/e4796108-f4d8-4a11-9860-d07b92b08d93 - -{ - "data": { - "disabled_at": null, - "email": "new-user@test", - "id": "e4796108-f4d8-4a11-9860-d07b92b08d93", - "inserted_at": "2023-03-29T15:11:47.192265Z", - "last_signed_in_at": null, - "last_signed_in_method": null, - "role": "unprivileged", - "updated_at": "2023-03-29T15:11:47.192265Z" - } -} -``` - -#### Provision an admin OpenID User - -```bash -$ curl -i \ - -X POST "https://{firezone_host}/v0/users" \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {api_token}' \ - --data-binary @- << EOF -{ - "user": { - "email": "new-user@test", - "role": "admin" - } -} -EOF - -HTTP/1.1 201 -Content-Type: application/json; charset=utf-8 -Location: /v0/users/479ed1cb-1657-4c82-bc32-2200f6cc82e9 - -{ - "data": { - "disabled_at": null, - "email": "new-user@test", - "id": "479ed1cb-1657-4c82-bc32-2200f6cc82e9", - "inserted_at": "2023-03-29T15:11:47.460359Z", - "last_signed_in_at": null, - "last_signed_in_method": null, - "role": "admin", - "updated_at": "2023-03-29T15:11:47.460359Z" - } -} -``` - -#### Error due to invalid parameters - -```bash -$ curl -i \ - -X POST "https://{firezone_host}/v0/users" \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {api_token}' \ - --data-binary @- << EOF -{ - "user": { - "email": "test@test.com", - "password": "test1234" - } -} -EOF - -HTTP/1.1 422 -Content-Type: application/json; charset=utf-8 - -{ - "errors": { - "password": [ - "should be at least 12 character(s)" - ], - "password_confirmation": [ - "can't be blank" - ] - } -} -``` - -### GET /v0/users/\{id\} - -#### An email can be used instead of ID - -**URI Parameters:** - -- `id`: `test-905@test` - -```bash -$ curl -i \ - -X GET "https://{firezone_host}/v0/users/{id}" \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {api_token}' \ - -HTTP/1.1 200 -Content-Type: application/json; charset=utf-8 - -{ - "data": { - "disabled_at": null, - "email": "test-905@test", - "id": "d43dae29-0687-456c-a3a4-a461eb744cf5", - "inserted_at": "2023-03-29T15:11:47.340583Z", - "last_signed_in_at": null, - "last_signed_in_method": null, - "role": "admin", - "updated_at": "2023-03-29T15:11:47.340583Z" - } -} -``` - -### Update a User [`PATCH /v0/users/{id}`] - -For details please see [Create a User](#create-a-user-post-v0users) section. - -#### Update by email - -**URI Parameters:** - -- `id`: `test-1960@test` - -```bash -$ curl -i \ - -X PUT "https://{firezone_host}/v0/users/{id}" \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {api_token}' \ - --data-binary @- << EOF -{ - "user": {} -} -EOF - -HTTP/1.1 200 -Content-Type: application/json; charset=utf-8 - -{ - "data": { - "disabled_at": null, - "email": "test-1960@test", - "id": "8830b359-2368-4f55-9879-1cb04ee0cbbf", - "inserted_at": "2023-03-29T15:11:47.391921Z", - "last_signed_in_at": null, - "last_signed_in_method": null, - "role": "unprivileged", - "updated_at": "2023-03-29T15:11:47.391921Z" - } -} -``` - -#### Update by ID - -**URI Parameters:** - -- `id`: `d542e1bc-25b2-453d-ae14-41f8f81605ee` - -```bash -$ curl -i \ - -X PUT "https://{firezone_host}/v0/users/{id}" \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {api_token}' \ - --data-binary @- << EOF -{ - "user": {} -} -EOF - -HTTP/1.1 200 -Content-Type: application/json; charset=utf-8 - -{ - "data": { - "disabled_at": null, - "email": "test-1513@test", - "id": "d542e1bc-25b2-453d-ae14-41f8f81605ee", - "inserted_at": "2023-03-29T15:11:47.475440Z", - "last_signed_in_at": null, - "last_signed_in_method": null, - "role": "unprivileged", - "updated_at": "2023-03-29T15:11:47.475440Z" - } -} -``` - -### DELETE /v0/users/\{id\} - -#### Example - -**URI Parameters:** - -- `id`: `31156bf6-73de-4d9b-aa1e-2e419a45dd25` - -```bash -$ curl -i \ - -X DELETE "https://{firezone_host}/v0/users/{id}" \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {api_token}' \ - -HTTP/1.1 204 -Content-Type: application/json; charset=utf-8 -``` - -#### An email can be used instead of ID - -**URI Parameters:** - -- `id`: `test-4996@test` - -```bash -$ curl -i \ - -X DELETE "https://{firezone_host}/v0/users/{id}" \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {api_token}' \ - -HTTP/1.1 204 -Content-Type: application/json; charset=utf-8 -``` diff --git a/website/src/app/docs/reference/reverse-proxy-templates/apache/page.tsx b/website/src/app/docs/reference/reverse-proxy-templates/apache/page.tsx deleted file mode 100644 index 4c18bbe43..000000000 --- a/website/src/app/docs/reference/reverse-proxy-templates/apache/page.tsx +++ /dev/null @@ -1,11 +0,0 @@ -import Content from "./readme.mdx"; -import { Metadata } from "next"; - -export const metadata: Metadata = { - title: "Reverse Proxy Templates: Apache • Firezone Docs", - description: "Apache Reverse Proxy Templates for Firezone.", -}; - -export default function Page() { - return ; -} diff --git a/website/src/app/docs/reference/reverse-proxy-templates/apache/readme.mdx b/website/src/app/docs/reference/reverse-proxy-templates/apache/readme.mdx deleted file mode 100644 index 9bd599981..000000000 --- a/website/src/app/docs/reference/reverse-proxy-templates/apache/readme.mdx +++ /dev/null @@ -1,63 +0,0 @@ -# Reverse Proxy Template: Apache - -The following are example [apache](https://httpd.apache.org) configurations with -and without SSL termination. - -These expect the apache to be running on the same host as Firezone and -`default['firezone']['phoenix']['port']` to be `13000`. - -## Without SSL termination - -Since Firezone requires HTTPS for the web portal, please bear in mind a -downstream proxy will need to terminate SSL connections in this scenario. - -`` needs to be replaced with your domain name. - -This configuration needs to be placed in -`/etc/sites-available/.conf` - -and activated with `a2ensite ` - -```text -LoadModule rewrite_module /usr/lib/apache2/modules/mod_rewrite.so -LoadModule proxy_module /usr/lib/apache2/modules/mod_proxy.so -LoadModule proxy_http_module /usr/lib/apache2/modules/mod_proxy_http.so -LoadModule proxy_wstunnel_module /usr/lib/apache2/modules/mod_proxy_wstunnel.so - - ServerName - ProxyPassReverse "/" "http://127.0.0.1:13000/" - ProxyPass "/" "http://127.0.0.1:13000/" - RewriteEngine on - RewriteCond %{HTTP:Upgrade} websocket [NC] - RewriteCond %{HTTP:Connection} upgrade [NC] - RewriteRule ^/?(.*) "ws://127.0.0.1:13000/$1" [P,L] - -``` - -## With SSL termination - -This configuration builds on the one above and uses Firezone's auto-generated -self-signed certificates. - -```text -LoadModule rewrite_module /usr/lib/apache2/modules/mod_rewrite.so -LoadModule proxy_module /usr/lib/apache2/modules/mod_proxy.so -LoadModule proxy_http_module /usr/lib/apache2/modules/mod_proxy_http.so -LoadModule proxy_wstunnel_module /usr/lib/apache2/modules/mod_proxy_wstunnel.so -LoadModule ssl_module /usr/lib/apache2/modules/mod_ssl.so -LoadModule headers_module /usr/lib/apache2/modules/mod_headers.so -Listen 443 - - ServerName - RequestHeader set X-Forwarded-Proto "https" - ProxyPassReverse "/" "http://127.0.0.1:13000/" - ProxyPass "/" "http://127.0.0.1:13000/" - RewriteEngine on - RewriteCond %{HTTP:Upgrade} websocket [NC] - RewriteCond %{HTTP:Connection} upgrade [NC] - RewriteRule ^/?(.*) "ws://127.0.0.1:13000/$1" [P,L] - SSLEngine On - SSLCertificateFile "/var/opt/firezone/ssl/ca/acme-test.firez.one.crt" - SSLCertificateKeyFile "/var/opt/firezone/ssl/ca/acme-test.firez.one.key" - -``` diff --git a/website/src/app/docs/reference/reverse-proxy-templates/haproxy/page.tsx b/website/src/app/docs/reference/reverse-proxy-templates/haproxy/page.tsx deleted file mode 100644 index 04189b5cc..000000000 --- a/website/src/app/docs/reference/reverse-proxy-templates/haproxy/page.tsx +++ /dev/null @@ -1,11 +0,0 @@ -import Content from "./readme.mdx"; -import { Metadata } from "next"; - -export const metadata: Metadata = { - title: "Reverse Proxy Templates: HAProxy • Firezone Docs", - description: "HAProxy Reverse Proxy Templates for Firezone.", -}; - -export default function Page() { - return ; -} diff --git a/website/src/app/docs/reference/reverse-proxy-templates/haproxy/readme.mdx b/website/src/app/docs/reference/reverse-proxy-templates/haproxy/readme.mdx deleted file mode 100644 index 382ec5d76..000000000 --- a/website/src/app/docs/reference/reverse-proxy-templates/haproxy/readme.mdx +++ /dev/null @@ -1,29 +0,0 @@ -# Reverse Proxy Templates: HAProxy - -The following is an example reverse proxy configuration for -[HAProxy](https://www.haproxy.org/) proxy. We assume -`default['firezone']['phoenix']['port']` to be `13000` and the proxy running on -the same host as the Firezone app. - -Since Firezone requires HTTPS for the web portal, please bear in mind a -downstream proxy will need to terminate SSL connections in this scenario. - -You can also configure HAProxy to handle the SSL termination as explained -[here](https://www.haproxy.com/blog/haproxy-ssl-termination/) but take into -account that the `pem` file expected by `ssl crt` option needs to contain both -the `crt` and `key` file. - -`/etc/haproxy/haproxy.cfg`: - -```text -defaults - mode http - -frontend app1 - bind *:80 - option forwardfor - default_backend backend_app1 - -backend backend_app1 - server mybackendserver 127.0.0.1:13000 -``` diff --git a/website/src/app/docs/reference/reverse-proxy-templates/traefik/page.tsx b/website/src/app/docs/reference/reverse-proxy-templates/traefik/page.tsx deleted file mode 100644 index 8dca64b68..000000000 --- a/website/src/app/docs/reference/reverse-proxy-templates/traefik/page.tsx +++ /dev/null @@ -1,11 +0,0 @@ -import Content from "./readme.mdx"; -import { Metadata } from "next"; - -export const metadata: Metadata = { - title: "Reverse Proxy Templates: Traefik • Firezone Docs", - description: "Traefik Reverse Proxy Templates for Firezone.", -}; - -export default function Page() { - return ; -} diff --git a/website/src/app/docs/reference/reverse-proxy-templates/traefik/readme.mdx b/website/src/app/docs/reference/reverse-proxy-templates/traefik/readme.mdx deleted file mode 100644 index 9b24d5bfe..000000000 --- a/website/src/app/docs/reference/reverse-proxy-templates/traefik/readme.mdx +++ /dev/null @@ -1,272 +0,0 @@ -# Reverse Proxy Templates: Traefik - -The following are examples for configuring the [Traefik](https://traefik.io) -proxy as a reverse proxy for Firezone. - -In these examples, we assume Traefik is deployed using Docker on the same host -as Firezone. For this to work, you'll need to make sure -`PHOENIX_EXTERNAL_TRUSTED_PROXIES` is set to include the Docker address of the -Traefik service. - -## Without SSL termination - -Since Firezone requires HTTPS for the web portal, please bear in mind a -downstream proxy will need to terminate SSL connections in this scenario. - -Use the following `docker-compose.yml` and `rules.yml` files as a starting point -for your own Firezone config: - -### `docker-compose.yml` - -```yaml -version: '3' - -x-deploy: &default-deploy - restart_policy: - condition: on-failure - delay: 5s - max_attempts: 3 - window: 120s - update_config: - order: start-first - -networks: - firezone-network: - enable_ipv6: true - ipam: - config: - - subnet: 172.25.0.0/16 - - subnet: fcff:3990:3990::/64 - -services: - traefik: - deploy: - <<: *default-deploy - # The official v2 Traefik docker image - image: traefik:v2.8 - # Enables the web UI and tells Traefik to listen to docker - command: - - "--providers.docker" - - "--providers.file.filename=rules.yml" - - "--entrypoints.web.address=:80" - - "--entrypoints.web.forwardedHeaders.insecure" - - "--log.level=DEBUG" - extra_hosts: - - "host.docker.internal:host-gateway" - ports: - # The HTTP port - - "80:80" - volumes: - # So that Traefik can listen to the Docker events - - /var/run/docker.sock:/var/run/docker.sock - - ./rules.yml:/rules.yml - # make the IP of this service deterministic - networks: - firezone-network: - ipv4_address: 172.25.0.99 - ipv6_address: fcff:3990:3990::99 - - firezone: - image: firezone/firezone - ports: - - 51820:51820/udp - env_file: - # This should contain a list of env vars for configuring Firezone. - # See https://www.firezone.dev/docs/reference/env-vars for more info. - - ${FZ_INSTALL_DIR:-.}/.env - volumes: - # IMPORTANT: Persists WireGuard private key and other data. If - # /var/firezone/private_key exists when Firezone starts, it is - # used as the WireGuard private. Otherwise, one is generated. - - ${FZ_INSTALL_DIR:-.}/firezone:/var/firezone - cap_add: - # Needed for WireGuard and firewall support. - - NET_ADMIN - - SYS_MODULE - sysctls: - # Needed for masquerading and NAT. - - net.ipv6.conf.all.disable_ipv6=0 - - net.ipv4.ip_forward=1 - - net.ipv6.conf.all.forwarding=1 - depends_on: - - postgres - networks: - firezone-network: - ipv4_address: 172.25.0.100 - deploy: - <<: *default-deploy - - postgres: - image: postgres:15 - volumes: - - postgres-data:/var/lib/postgresql/data - environment: - POSTGRES_DB: ${DATABASE_NAME:-firezone} - POSTGRES_USER: ${DATABASE_USER:-postgres} - POSTGRES_PASSWORD: ${DATABASE_PASSWORD:?err} - networks: - - firezone-network - deploy: - <<: *default-deploy - update_config: - order: stop-first - -# Postgres needs a named volume to prevent perms issues on non-linux platforms -volumes: - postgres-data: - -networks: - firezone-network: - driver: bridge - ipam: - config: - - subnet: 172.25.0.0/16 -``` - -### `rules.yml` - -```yaml -http: - routers: - test: - entryPoints: - - "web" - service: test - rule: "Host(`44.200.42.78`)" - services: - test: - loadBalancer: - servers: - - url: "http://firezone:13000" -``` - -Now you should be able to start the Traefik proxy with `docker compose up`. - -## With SSL termination - -This configuration uses Firezone's auto-generated self-signed certificates. - -### SSL `docker-compose.yml` - -```yaml -version: "3" - -x-deploy: &default-deploy - restart_policy: - condition: on-failure - delay: 5s - max_attempts: 3 - window: 120s - update_config: - order: start-first - -networks: - app: - enable_ipv6: true - ipam: - config: - - subnet: 172.28.0.0/16 - - subnet: fcff:3990:3990::/64 - -services: - firezone: - image: firezone/firezone - ports: - - 51820:51820/udp - volumes: - # IMPORTANT: Persists WireGuard private key and other data. If - # /var/firezone/private_key exists when Firezone starts, it is - # used as the WireGuard private. Otherwise, one is generated. - - ${HOME}/.firezone/firezone:/var/firezone - environment: - EXTERNAL_URL: ${EXTERNAL_URL:?err} - DEFAULT_ADMIN_EMAIL: ${DEFAULT_ADMIN_EMAIL:?err} - DEFAULT_ADMIN_PASSWORD: ${DEFAULT_ADMIN_PASSWORD:?err} - GUARDIAN_SECRET_KEY: ${GUARDIAN_SECRET_KEY:?err} - SECRET_KEY_BASE: ${SECRET_KEY_BASE:?err} - LIVE_VIEW_SIGNING_SALT: ${LIVE_VIEW_SIGNING_SALT:?err} - COOKIE_SIGNING_SALT: ${COOKIE_SIGNING_SALT:?err} - COOKIE_ENCRYPTION_SALT: ${COOKIE_ENCRYPTION_SALT:?err} - DATABASE_ENCRYPTION_KEY: ${DATABASE_ENCRYPTION_KEY:?err} - - # Ensure this includes the traefik service IP. - PHOENIX_EXTERNAL_TRUSTED_PROXIES: [""] - networks: - - app - cap_add: - - NET_ADMIN - - SYS_MODULE - sysctls: - - net.ipv6.conf.all.disable_ipv6=0 - - net.ipv4.ip_forward=1 - - net.ipv6.conf.all.forwarding=1 - depends_on: - - postgres - traefik: - deploy: - <<: *default-deploy - # The official v2 Traefik docker image - image: traefik:v2.8 - # Enables the web UI and tells Traefik to listen to docker - command: - - "--providers.docker" - - "--providers.file.filename=rules.yml" - - "--entrypoints.web.address=:443" - - "--entrypoints.web.forwardedHeaders.insecure" - - "--log.level=DEBUG" - extra_hosts: - - "host.docker.internal:host-gateway" - ports: - # The HTTP port - - "443:443" - volumes: - # So that Traefik can listen to the Docker events - - /var/run/docker.sock:/var/run/docker.sock - - ./rules.yml:/rules.yml - # make the IP of this service deterministic - networks: - app: - ipv4_address: 172.28.0.99 - ipv6_address: fcff:3990:3990::99 - postgres: - image: postgres:15 - volumes: - - postgres-data:/var/lib/postgresql/data - environment: - # same value as ## DB section above - POSTGRES_DB: ${DATABASE_NAME:-firezone} - POSTGRES_USER: ${DATABASE_USER:-postgres} - POSTGRES_PASSWORD: ${DATABASE_PASSWORD:?err} - deploy: - <<: *default-deploy - update_config: - order: stop-first - -# Postgres needs a named volume to prevent perms issues on non-linux platforms -volumes: - postgres-data: -``` - -### SSL `rules.yml` - -```yaml -http: - routers: - test: - entryPoints: - - "web" - service: test - rule: "Host(`44.200.42.78`)" - tls: {} - services: - test: - loadBalancer: - servers: - - url: "http://firezone:13000" -tls: - stores: - default: - defaultCertificate: - certFile: /path/to/your/cert.crt - keyFile: /path/to/your/key.key -``` diff --git a/website/src/app/docs/reference/security-controls/page.tsx b/website/src/app/docs/reference/security-controls/page.tsx deleted file mode 100644 index 3fdf4bdc3..000000000 --- a/website/src/app/docs/reference/security-controls/page.tsx +++ /dev/null @@ -1,11 +0,0 @@ -import Content from "./readme.mdx"; -import { Metadata } from "next"; - -export const metadata: Metadata = { - title: "Security Controls • Firezone Docs", - description: "Firezone's security controls.", -}; - -export default function Page() { - return ; -} diff --git a/website/src/app/docs/reference/security-controls/readme.mdx b/website/src/app/docs/reference/security-controls/readme.mdx deleted file mode 100644 index 9f9be1686..000000000 --- a/website/src/app/docs/reference/security-controls/readme.mdx +++ /dev/null @@ -1,72 +0,0 @@ -# Security Controls - -Firezone employs a few different security controls to keep data secure in -transit and at rest. - -## Overview of Cryptography Used - -Below is a table of cryptography used and to which contexts they apply. - -| Cryptography | Context | Notes | -| -------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| AES-GCM | Data at rest | Used to encrypt sensitive database fields such as device preshared keys and multi-factor authentication secrets. | -| Argon2 | Data at rest | Used to hash user passwords for the local authentication method. | -| TLSv1.2/TLSv1.3 | Data in transit | Used by the Caddy server to encrypt HTTP connections to the portal. Read more at https://caddyserver.com/docs/caddyfile/directives/tls. SSL certificates are provisioned automatically with the ACME protocol by Let's Encrypt by default. | -| ChaCha20, Poly1305, Curve25519, BLAKE2s, SipHash24, HKDF | Data in transit | Used by WireGuard® for VPN tunnels. Read more at https://wireguard.com/protocol. Firezone uses Linux kernel WireGuard without modification. | - -## Security policy - -We take security issues very seriously and strive to fix all security issues as -soon as they're reported. - -### Announcements - -We'll announce major security issues on our security mailing list located at: - -https://discourse.firez.one/?utm_source=docs.firezone.dev - -### Supported Versions - -We release security patches for supported versions of Firezone. We recommend -running the latest version of Firezone at all times. - -### Reporting a Vulnerability - -Please **do not** open a Github Issue for security issues you encounter. -Instead, please send an email to `security AT firezone.dev` describing the issue -and we'll respond as soon as possible. - -### PGP Key - -You may use the public key below to encrypt emails to -`security AT firezone.dev`. You can also find this key at: - -https://keys.openpgp.org/vks/v1/by-fingerprint/250F8B56804107042DFC6A7345113BA04AD83D8A - -```text ------BEGIN PGP PUBLIC KEY BLOCK----- -Comment: 250F 8B56 8041 0704 2DFC 6A73 4511 3BA0 4AD8 3D8A -Comment: Firezone Security - -xjMEYYwK5BYJKwYBBAHaRw8BAQdA4ooDpwDy3V0wHCftM/LHD5e713LSr0SQy49j -oUMgHoTNKUZpcmV6b25lIFNlY3VyaXR5IDxzZWN1cml0eUBmaXJlem9uZS5kZXY+ -wpkEExYKAEECGwMFCwkIBwICIgIGFQoJCAsCBBYCAwECHgcCF4AWIQQlD4tWgEEH -BC38anNFETugStg9igUCZeCcnAUJCfgsNwAKCRBFETugStg9ikL1AQD/+saUW/kO -nKGEIRtUywFCTB2WYw8qMPuKeNs8Seg2OwEA5r4/dk1imdO0PEUFW+K8c5iI7erH -dgVdBasVaZstFgTCmQQTFgoAQQIbAwULCQgHAgIiAgYVCgkICwIEFgIDAQIeBwIX -gBYhBCUPi1aAQQcELfxqc0URO6BK2D2KBQJl3lQ0BQkIFLBQAAoJEEURO6BK2D2K -llgA/1RNbEtoTA+sd9l9YXLVu9nFgKUBbs9kZbjyWn3nZL0+AQDQ/j+RzxvSDYHw -u/ZGZukV99xywEeRugnQGJYaExZKC8KZBBMWCgBBAhsDBQsJCAcCAiICBhUKCQgL -AgQWAgMBAh4HAheAFiEEJQ+LVoBBBwQt/GpzRRE7oErYPYoFAmRrk3gFCQah75QA -CgkQRRE7oErYPYrr9AD/ecxrjiqXKiBSqvpjTQAS62C793OH5+BCD77HIJx53QMA -/04ToQzx3eAiD/xTc1sWixIq2ZYj+Xb+zLXlUx8AugEAzjgEYYwK5BIKKwYBBAGX -VQEFAQEHQPLzia/me7FOsFfAJKWm0X1qC5byv2GWn6LZPV013AdoAwEIB8J+BBgW -CgAmAhsMFiEEJQ+LVoBBBwQt/GpzRRE7oErYPYoFAmXgnM8FCQn4LGsACgkQRRE7 -oErYPYrmagD8Drfj3tTJE1b7+kIjID0TMpTqB4/ghRHCxDs8t7uK/LAA/j1g/mbX -VpPejvDUfq4BBmKlqgQIoGsQuDt2TyYC8lQCwn4EGBYKACYCGwwWIQQlD4tWgEEH -BC38anNFETugStg9igUCZGuTYgUJBqHvfgAKCRBFETugStg9imPkAQCLuuSRgRul -WoYfGafZJeVv3s8hkvZH+EEhqOrUYtkm5QD9EXaELFVgOBmv0Ax4WUGfjnL6h4CP -IAuYUQ+MqN4MOQM= -=HwvF ------END PGP PUBLIC KEY BLOCK----- -``` diff --git a/website/src/app/docs/reference/telemetry/page.tsx b/website/src/app/docs/reference/telemetry/page.tsx deleted file mode 100644 index 5233c625d..000000000 --- a/website/src/app/docs/reference/telemetry/page.tsx +++ /dev/null @@ -1,11 +0,0 @@ -import Content from "./readme.mdx"; -import { Metadata } from "next"; - -export const metadata: Metadata = { - title: "Telemetry • Firezone Docs", - description: "Information on what telemetry Firezone collects.", -}; - -export default function Page() { - return ; -} diff --git a/website/src/app/docs/reference/telemetry/readme.mdx b/website/src/app/docs/reference/telemetry/readme.mdx deleted file mode 100644 index 701504f7c..000000000 --- a/website/src/app/docs/reference/telemetry/readme.mdx +++ /dev/null @@ -1,100 +0,0 @@ -import { TabsGroup, TabsItem } from "@/components/Tabs"; -import Alert from "@/components/DocsAlert"; - -# Telemetry - -This document presents an overview of the telemetry Firezone collects from your -self-hosted instance and how to disable it. - -## Why Firezone collects telemetry - -We _rely_ on telemetry to prioritize our roadmap and optimize the engineering -resources we have to make Firezone better for everyone. - -The telemetry we collect aims to answer the following questions: - -- How many people install, use, and stop using Firezone? -- What features are most valuable, and which ones don’t see any use? -- What functionality needs the most improvement? -- When something breaks, why did it break, and how can we prevent it from - happening in the future? - -## How we collect telemetry - -There are three main places where telemetry is collected in Firezone: - -1. Package telemetry. Includes events such as install, uninstall, and upgrade. -2. CLI telemetry from `firezone-ctl` commands. -3. Product telemetry associated with the Web portal. - -In each of these three contexts, we capture the minimum amount of data necessary -to answer the questions in the section above. - -Admin emails are collected **only if** you explicitly opt-in to product updates. -Otherwise, personally-identifiable information is **_never_** collected. - -We store telemetry in [PostHog](https://posthog.com) only accessible by the -Firezone team. Here is an example of a telemetry event that is sent from your -instance of Firezone to our telemetry server: - -```json -{ - "id": "0182272d-0b88-0000-d419-7b9a413713f1", - "timestamp": "2022-07-22T18:30:39.748000+00:00", - "event": "fz_http_started", - "distinct_id": "1ec2e794-1c3e-43fc-a78f-1db6d1a37f54", - "properties": { - "$geoip_city_name": "Ashburn", - "$geoip_continent_code": "NA", - "$geoip_continent_name": "North America", - "$geoip_country_code": "US", - "$geoip_country_name": "United States", - "$geoip_latitude": 39.0469, - "$geoip_longitude": -77.4903, - "$geoip_postal_code": "20149", - "$geoip_subdivision_1_code": "VA", - "$geoip_subdivision_1_name": "Virginia", - "$geoip_time_zone": "America/New_York", - "$ip": "52.200.241.107", - "$plugins_deferred": [], - "$plugins_failed": [], - "$plugins_succeeded": ["GeoIP (3)"], - "distinct_id": "1zc2e794-1c3e-43fc-a78f-1db6d1a37f54", - "fqdn": "awsdemo.firezone.dev", - "kernel_version": "linux 5.13.0", - "version": "0.4.6" - }, - "elements_chain": "" -} -``` - -## How to disable telemetry - - - We _rely_ on product analytics to make Firezone better for everyone. Leaving - telemetry enabled is the **single most valuable contribution** you can make to - Firezone’s development. That said, we understand some users have higher - privacy or security requirements and would prefer to disable telemetry - altogether. If that’s you, keep reading. - - -Telemetry is enabled by default. To completely disable product telemetry: - - - - -Set the `TELEMETRY_ENABLED` environment variable to `false` and restart the -`firezone` container. - - - - -Set the following configuration option to `false` in `/etc/firezone/firezone.rb` -and run `sudo firezone-ctl reconfigure` to pick up the changes. - -```ruby -default['firezone']['telemetry']['enabled'] = false -``` - - - diff --git a/website/src/app/docs/user-guides/add-devices/_page.tsx b/website/src/app/docs/user-guides/add-devices/_page.tsx deleted file mode 100644 index 5b854431b..000000000 --- a/website/src/app/docs/user-guides/add-devices/_page.tsx +++ /dev/null @@ -1,7 +0,0 @@ -"use client"; - -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/user-guides/add-devices/page.tsx b/website/src/app/docs/user-guides/add-devices/page.tsx deleted file mode 100644 index 3ec9152a7..000000000 --- a/website/src/app/docs/user-guides/add-devices/page.tsx +++ /dev/null @@ -1,11 +0,0 @@ -import { Metadata } from "next"; -import _Page from "./_page"; - -export const metadata: Metadata = { - title: "User Guides: Add Devices • Firezone Docs", - description: "Instructions for adding devices to Firezone.", -}; - -export default function Page() { - return <_Page />; -} diff --git a/website/src/app/docs/user-guides/add-devices/readme.mdx b/website/src/app/docs/user-guides/add-devices/readme.mdx deleted file mode 100644 index 93aaf1733..000000000 --- a/website/src/app/docs/user-guides/add-devices/readme.mdx +++ /dev/null @@ -1,35 +0,0 @@ -import Image from "next/image"; - -# Add or Remove Devices - -When a device is created, Firezone generates the WireGuard private key -ephemerally in the user's browser. This key is **never saved**, and cannot be -shown again once it is no longer displayed. - -**We recommend asking end users to generate their own device configs so the -WireGuard private key is not exposed.** Users can follow instructions on the -[Client Instructions](/docs/user-guides/client-instructions) page to generate -their own WireGuard configs. - -## Admin device config generation - -Firezone admins can generate device configs for all users. This can be done by -clicking the "Add Device" button on the user profile page found in `/users`. - -add device under user - -Once the device profile is created, the admin can download and send the -WireGuard configuration file to the user over a secure channel. - -See [Add Users](/docs/user-guides/add-users) for more information on how to add -a user. - -## Related guides - -- [Client Instructions](/docs/user-guides/client-instructions) diff --git a/website/src/app/docs/user-guides/add-users/_page.tsx b/website/src/app/docs/user-guides/add-users/_page.tsx deleted file mode 100644 index 5b854431b..000000000 --- a/website/src/app/docs/user-guides/add-users/_page.tsx +++ /dev/null @@ -1,7 +0,0 @@ -"use client"; - -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/user-guides/add-users/page.tsx b/website/src/app/docs/user-guides/add-users/page.tsx deleted file mode 100644 index 926097328..000000000 --- a/website/src/app/docs/user-guides/add-users/page.tsx +++ /dev/null @@ -1,11 +0,0 @@ -import _Page from "./_page"; -import { Metadata } from "next"; - -export const metadata: Metadata = { - title: "User Guides: Add Users • Firezone Docs", - description: "Instructions for adding devices to Firezone.", -}; - -export default function Page() { - return <_Page />; -} diff --git a/website/src/app/docs/user-guides/add-users/readme.mdx b/website/src/app/docs/user-guides/add-users/readme.mdx deleted file mode 100644 index d7d12ce1f..000000000 --- a/website/src/app/docs/user-guides/add-users/readme.mdx +++ /dev/null @@ -1,26 +0,0 @@ -import Image from "next/image"; - -# Add or remove users - -Once you have successfully installed Firezone you'll need to add users to grant -them access to your network. This can be done through the Web UI or the -[REST API](/docs/reference/rest-api/users). - -## Web UI - -Add a user by clicking the "Add User" button under `/users`. You will be asked -to specify an email and a password for the user. Firezone can also integrate and -sync with an identity provider to automatically grant access to users in your -organization. See [Authenticate](/docs/authenticate) for more information. - -add user - -## Related guides - -- [Authenticate](/docs/authenticate) diff --git a/website/src/app/docs/user-guides/client-instructions/_page.tsx b/website/src/app/docs/user-guides/client-instructions/_page.tsx deleted file mode 100644 index 5b854431b..000000000 --- a/website/src/app/docs/user-guides/client-instructions/_page.tsx +++ /dev/null @@ -1,7 +0,0 @@ -"use client"; - -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/user-guides/client-instructions/page.tsx b/website/src/app/docs/user-guides/client-instructions/page.tsx deleted file mode 100644 index 468adf582..000000000 --- a/website/src/app/docs/user-guides/client-instructions/page.tsx +++ /dev/null @@ -1,11 +0,0 @@ -import { Metadata } from "next"; -import _Page from "./_page"; - -export const metadata: Metadata = { - title: "User Guides: Client Instructions • Firezone Docs", - description: "Instructions for connecting clients to Firezone.", -}; - -export default function Page() { - return <_Page />; -} diff --git a/website/src/app/docs/user-guides/client-instructions/readme.mdx b/website/src/app/docs/user-guides/client-instructions/readme.mdx deleted file mode 100644 index a32742a93..000000000 --- a/website/src/app/docs/user-guides/client-instructions/readme.mdx +++ /dev/null @@ -1,207 +0,0 @@ -import Image from "next/image"; -import Alert from "@/components/DocsAlert"; - -# End-user Client Instructions - -Follow these instructions if you're an end-user trying to set up your WireGuard -client to work with Firezone. - -## Install and setup - -Follow this guide to establish a VPN session through the WireGuard native -client. - -### Step 1: Install the native WireGuard client - -Firezone is compatible with the official WireGuard clients found here: - -- [macOS](https://itunes.apple.com/us/app/wireguard/id1451685025) -- [Windows](https://download.wireguard.com/windows-client/wireguard-installer.exe) -- [iOS](https://itunes.apple.com/us/app/wireguard/id1441195209) -- [Android](https://play.google.com/store/apps/details?id=com.wireguard.android) - -For operating systems not listed above see the Official WireGuard site: -[ https://www.wireguard.com/install/](https://www.wireguard.com/install). - -### Step 2: Download the device config file - -The device config file can either be obtained from your Firezone administrator -or self-generated via the Firezone portal. - -To self generate a device config file, visit the domain provided by your -Firezone administrator. This URL will be specific to your company (in this -example it is `https://firezone.example.com`) - -firezone okta sso login - -### Step 3 (optional): Enable on boot - -Open the WireGuard client and import the `.conf` file. Activate the VPN session -by toggling the `Activate` switch. - -activate tunnel - -## Re-authenticating your session - -If your network admin has required periodic authentication to maintain your VPN -session, follow the steps below. You will need: - -- **URL of the Firezone portal**: Ask your Network Admin for the link. -- **Credentials**: Your username and password should be provided by your Network - Admin. If your company is using a Single Sign On provider (like Google or - Okta), the Firezone portal will prompt you to authenticate via that provider. - -### Step 1: Deactivate VPN session - -wireguard deactivate - -### Step 2: Re-authenticate - -Visit the URL of your Firezone portal and sign in using credentials provided by -your network admin. If you are already logged into the portal, click the -`Reauthenticate` button, then sign in again. - -re-authenticate - -### Step 3: Activate VPN session - -activate session - -## Linux: Network Manager - -The following steps can be used on Linux devices to import the WireGuard -configuration profile using Network Manager CLI (`nmcli`). - - - Importing the configuration file using the Network Manager GUI may fail with - the following error if the profile has IPv6 support enabled: `ipv6.method: - method "auto" is not supported for WireGuard` - - -### Step 1: Install the WireGuard tools - -The WireGuard userspace tools need to be installed. For most Linux distributions -this will be a package named `wireguard` or `wireguard-tools`. - -For Debian/Ubuntu: - -```bash -sudo apt install wireguard -``` - -For Fedora: - -```bash -sudo dnf install wireguard-tools -``` - -For Arch Linux: - -```bash -sudo pacman -S wireguard-tools -``` - -For distributions not listed above see the Official WireGuard site: -[ https://www.wireguard.com/install/](https://www.wireguard.com/install). - -### Step 2: Download configuration - -The device config file can either be obtained from your Firezone administrator -or self-generated via the Firezone portal. - -To self generate a device config file, visit the domain provided by your -Firezone administrator. This URL will be specific to your company (in this -example it is `https://firezone.example.com`) - -firezone okta sso login - -### Step 3: Import configuration - -Using `nmcli`, import the downloaded configuration file: - -```bash -sudo nmcli connection import type wireguard file /path/to/configuration.conf -``` - - - The WireGuard connection/interface will match the name of the configuration - file. If required, the connection can be renamed after import: `nmcli - connection modify [old name] connection.id [new name]` - - -### Step 4: Connect/disconnect - -To connect to the VPN via the command line: - -```bash -nmcli connection up [vpn name] -``` - -To disconnect: - -```bash -nmcli connection down [vpn name] -``` - -If using a GUI, the relevant Network Manager applet can also be used to control -the connection. - -### Auto connection - -The VPN connection can be set to automatically connect by setting the -`autoconnect` option to `yes`: - -```bash -nmcli connection modify [vpn name] connection.autoconnect yes -``` - -To disable the automatic connection set it back to `no`: - -```bash -nmcli connection modify [vpn name] connection.autoconnect no -``` - -## Enable multi-factor authentication - -To enable MFA navigate to `/user_account/register_mfa` in the Firezone portal. -After generating the QR code, scan using your authenticator app and input the 6 -digit code. - -If you lose your authenticator app, contact your Admin to reset access to your -account. diff --git a/website/src/app/docs/user-guides/egress-rules/_page.tsx b/website/src/app/docs/user-guides/egress-rules/_page.tsx deleted file mode 100644 index 5b854431b..000000000 --- a/website/src/app/docs/user-guides/egress-rules/_page.tsx +++ /dev/null @@ -1,7 +0,0 @@ -"use client"; - -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/user-guides/egress-rules/page.tsx b/website/src/app/docs/user-guides/egress-rules/page.tsx deleted file mode 100644 index 768c2827a..000000000 --- a/website/src/app/docs/user-guides/egress-rules/page.tsx +++ /dev/null @@ -1,11 +0,0 @@ -import _Page from "./_page"; -import { Metadata } from "next"; - -export const metadata: Metadata = { - title: "User Guides: Egress Rules • Firezone Docs", - description: "User Guides: Egress Rules", -}; - -export default function Page() { - return <_Page />; -} diff --git a/website/src/app/docs/user-guides/egress-rules/readme.mdx b/website/src/app/docs/user-guides/egress-rules/readme.mdx deleted file mode 100644 index 0572810f6..000000000 --- a/website/src/app/docs/user-guides/egress-rules/readme.mdx +++ /dev/null @@ -1,18 +0,0 @@ -import Image from "next/image"; - -# Network Access Control: Egress Rules - -Firezone supports egress filtering controls to explicitly DROP or ACCEPT packets -via the kernel's netfilter system. By default, all traffic is allowed. - -The Allowlist and Denylist support both IPv4 and IPv6 CIDRs and IP addresses. -When adding a rule, you may optionally scope it to a user which applies the rule -to all their devices. - -firewall rules diff --git a/website/src/app/docs/user-guides/page.tsx b/website/src/app/docs/user-guides/page.tsx deleted file mode 100644 index 90b794fc5..000000000 --- a/website/src/app/docs/user-guides/page.tsx +++ /dev/null @@ -1,11 +0,0 @@ -import Content from "./readme.mdx"; -import { Metadata } from "next"; - -export const metadata: Metadata = { - title: "Firezone Docs • User Guides", - description: "Firezone Documentation", -}; - -export default function Page() { - return ; -} diff --git a/website/src/app/docs/user-guides/readme.mdx b/website/src/app/docs/user-guides/readme.mdx deleted file mode 100644 index 34a359f9e..000000000 --- a/website/src/app/docs/user-guides/readme.mdx +++ /dev/null @@ -1,9 +0,0 @@ -# User Guides - -Guides for common workflows your end users will undertake. - -1. [Add Devices](/docs/user-guides/add-devices) -1. [Add Users](/docs/user-guides/add-users) -1. [Client Instructions](/docs/user-guides/client-instructions) -1. [Egress Rules](/docs/user-guides/egress-rules) -1. [Use Cases](/docs/user-guides/use-cases) diff --git a/website/src/app/docs/user-guides/use-cases/nat-gateway/_page.tsx b/website/src/app/docs/user-guides/use-cases/nat-gateway/_page.tsx deleted file mode 100644 index 5b854431b..000000000 --- a/website/src/app/docs/user-guides/use-cases/nat-gateway/_page.tsx +++ /dev/null @@ -1,7 +0,0 @@ -"use client"; - -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/user-guides/use-cases/nat-gateway/page.tsx b/website/src/app/docs/user-guides/use-cases/nat-gateway/page.tsx deleted file mode 100644 index 971ea13d6..000000000 --- a/website/src/app/docs/user-guides/use-cases/nat-gateway/page.tsx +++ /dev/null @@ -1,11 +0,0 @@ -import { Metadata } from "next"; -import _Page from "./_page"; - -export const metadata: Metadata = { - title: "Use Cases: Nat Gateway • Firezone Docs", - description: "Use Cases: Nat Gateway", -}; - -export default function Page() { - return <_Page />; -} diff --git a/website/src/app/docs/user-guides/use-cases/nat-gateway/readme.mdx b/website/src/app/docs/user-guides/use-cases/nat-gateway/readme.mdx deleted file mode 100644 index 99efe016d..000000000 --- a/website/src/app/docs/user-guides/use-cases/nat-gateway/readme.mdx +++ /dev/null @@ -1,84 +0,0 @@ -import Image from "next/image"; - -# Static Egress IP with a NAT Gateway - -Firezone can be used as NAT gateway in order to provide a single, static egress -IP for all of your team's traffic to flow out of. This is commonly used in the -following scenarios: - -- Consulting engagements: Ask your client to whitelist a single static IP - address associated with your engagement instead of your employees' individual - device IPs. -- Masking your device IP or proxying your source IP for privacy or security - reasons. - -This guide will walk through a simple example restricting access for a -self-hosted web app to a single whitelisted static IP running Firezone. - -This is commonly done in place of maintaining an IP whitelist for multiple team -members, which becomes impossible to manage as the access list grows and team -members' IP addresses change. - -nat gateway - -## AWS example - -Our goal is to configure VPN traffic to the restricted resource to be routed -through a Firezone server on an EC2 instance. In this case Firezone is acting as -a network proxy or NAT gateway to provide a single public egress IP for all the -devices connected to it. - -In this example the protected resource and Firezone are in separate VPC regions. - -### Step 1: Deploy Firezone server - -In this example, a Firezone instance has been set up on a `tc2.micro` EC2 -instance. See the [Deployment Guide](/docs/deploy) for details on deploying -Firezone. Specific to AWS, ensure: - -1. The security group of the Firezone EC2 instance allows outbound traffic to - the IP of the protected resource. -1. An Elastic IP is associated with the Firezone instance. This will be the - source IP address of traffic routed through the Firezone instance to external - destinations. In this case, the IP is `52.202.88.54`. - -allocate elastic ip - -### Step 2: Restrict access to the protected resource - -In this example, the protected resource is a self-hosted web app. Access to the -web app is restricted to only requests from `52.202.88.54`. Depending on the -resource, inbound traffic on different ports and traffic types may need to be -allowed. This is outside the scope of this guide. - -configure security group - -If the protected resource is controlled by a 3rd party, please inform the 3rd -party to allow traffic from the static IP set in Step 1 (in this case -`52.202.88.54`). - -### Step 3: Route traffic to the protected resource through the VPN server - -By default, all traffic from team members will be routed through Firezone and -will originate from the static IP set in Step 1 (in this case `52.202.88.54`). -However, if [split tunneling](/docs/user-guides/use-cases/split-tunnel) has been -enabled, configuration may be required to ensure the destination IP of the -protected resource is included in the `Allowed IPs`. diff --git a/website/src/app/docs/user-guides/use-cases/page.tsx b/website/src/app/docs/user-guides/use-cases/page.tsx deleted file mode 100644 index 90b794fc5..000000000 --- a/website/src/app/docs/user-guides/use-cases/page.tsx +++ /dev/null @@ -1,11 +0,0 @@ -import Content from "./readme.mdx"; -import { Metadata } from "next"; - -export const metadata: Metadata = { - title: "Firezone Docs • User Guides", - description: "Firezone Documentation", -}; - -export default function Page() { - return ; -} diff --git a/website/src/app/docs/user-guides/use-cases/readme.mdx b/website/src/app/docs/user-guides/use-cases/readme.mdx deleted file mode 100644 index bb45c51ec..000000000 --- a/website/src/app/docs/user-guides/use-cases/readme.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# Use Cases - -Guides for common use cases our users typically encounter. - -1. [NAT Gateway](/docs/user-guides/use-cases/nat-gateway) -1. [Add Users](/docs/user-guides/use-cases/reverse-tunnel) -1. [Client Instructions](/docs/user-guides/use-cases/split-tunnel) diff --git a/website/src/app/docs/user-guides/use-cases/reverse-tunnel/_page.tsx b/website/src/app/docs/user-guides/use-cases/reverse-tunnel/_page.tsx deleted file mode 100644 index 5b854431b..000000000 --- a/website/src/app/docs/user-guides/use-cases/reverse-tunnel/_page.tsx +++ /dev/null @@ -1,7 +0,0 @@ -"use client"; - -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/user-guides/use-cases/reverse-tunnel/page.tsx b/website/src/app/docs/user-guides/use-cases/reverse-tunnel/page.tsx deleted file mode 100644 index 7ef6b71cf..000000000 --- a/website/src/app/docs/user-guides/use-cases/reverse-tunnel/page.tsx +++ /dev/null @@ -1,11 +0,0 @@ -import _Page from "./_page"; -import { Metadata } from "next"; - -export const metadata: Metadata = { - title: "Use Cases: Reverse Tunnel • Firezone Docs", - description: "Use Cases: Reverse Tunnel", -}; - -export default function Page() { - return <_Page />; -} diff --git a/website/src/app/docs/user-guides/use-cases/reverse-tunnel/readme.mdx b/website/src/app/docs/user-guides/use-cases/reverse-tunnel/readme.mdx deleted file mode 100644 index e50ef2ed6..000000000 --- a/website/src/app/docs/user-guides/use-cases/reverse-tunnel/readme.mdx +++ /dev/null @@ -1,92 +0,0 @@ -import Image from "next/image"; - -# Reverse Tunneling with Firezone - -This guide will walk through using Firezone as a relay to connect two devices. A -typical use case for this configuration is to enable an administrator to access -a server, container, or machine that is normally behind a NAT or firewall. - -## General case: node to node - -This example demonstrates a simple scenario where a tunnel is established -between Device A and Device B. - -node to node - -Start by creating Device A and Device B by navigating to -`/users/[user_id]/new_device`. In the settings for each device, ensure the -following parameters are set to the values listed below. You can set device -settings when creating the device config (see -[Add Devices](/docs/user-guides/add-devices)). If you need to update settings on -an existing device, you can do so by generating a new device config. - -Note `PersistentKeepalive` can also be set in on the `/settings/defaults` page -for all devices. - -Device A - -- `AllowedIPs = 10.3.2.3/32`: This is the IP or range of IPs of Device B -- `PersistentKeepalive = 25` If the device is behind a NAT, this ensures the - device is able to keep the tunnel alive and continue to receive packets from - the WireGuard interface. Usually a value of `25` is sufficient, but you may - need to decrease this value depending on your environment. - -Device B - -- `AllowedIPs = 10.3.2.2/32`: This is the IP or range of IPs of Device A -- `PersistentKeepalive = 25` - -## Admin case: one to many nodes - -This example demonstrates a scenario where Device A can communicate -bi-directionally with Devices B through D. This configuration could represent an -administrator or engineer accessing multiple resources (servers, containers, or -machines) in different networks. - -node to multiple nodes - -In the settings for each device, ensure the following parameters are set to the -values listed below. You can set device settings when creating the device config -(see [Add Devices](/docs/user-guides/add-devices)). If you need to update -settings on an existing device, you can do so by generating a new device config. - -Device A (Administrator Node) - -- `AllowedIPs = 10.3.2.3/32, 10.3.2.4/32, 10.3.2.5/32`: This is the IP of - devices B through D. Optionally you could set a range of IPs as long as it - includes the IPs of Devices B through D. -- `PersistentKeepalive = 25` If the device is behind a NAT, this ensures the - device is able to keep the tunnel alive and continue to receive packets from - the WireGuard interface. Usually a value of `25` is sufficient, but you may - need to decrease this value depending on your environment. - -Device B - -- `AllowedIPs = 10.3.2.2/32`: This is the IP or range of IPs of Device A -- `PersistentKeepalive = 25` - -Device C - -- `AllowedIPs = 10.3.2.2/32`: This is the IP or range of IPs of Device A -- `PersistentKeepalive = 25` - -Device D - -- `AllowedIPs = 10.3.2.2/32`: This is the IP or range of IPs of Device A -- `PersistentKeepalive = 25` - -## Related guides - -- [NAT Gateway](/docs/user-guides/use-cases/nat-gateway) diff --git a/website/src/app/docs/user-guides/use-cases/split-tunnel/_page.tsx b/website/src/app/docs/user-guides/use-cases/split-tunnel/_page.tsx deleted file mode 100644 index 5b854431b..000000000 --- a/website/src/app/docs/user-guides/use-cases/split-tunnel/_page.tsx +++ /dev/null @@ -1,7 +0,0 @@ -"use client"; - -import Content from "./readme.mdx"; - -export default function _Page() { - return ; -} diff --git a/website/src/app/docs/user-guides/use-cases/split-tunnel/page.tsx b/website/src/app/docs/user-guides/use-cases/split-tunnel/page.tsx deleted file mode 100644 index 956820cfb..000000000 --- a/website/src/app/docs/user-guides/use-cases/split-tunnel/page.tsx +++ /dev/null @@ -1,11 +0,0 @@ -import { Metadata } from "next"; -import _Page from "./_page"; - -export const metadata: Metadata = { - title: "Use Cases: Split Tunnel • Firezone Docs", - description: "Use Cases: Split Tunnel", -}; - -export default function Page() { - return <_Page />; -} diff --git a/website/src/app/docs/user-guides/use-cases/split-tunnel/readme.mdx b/website/src/app/docs/user-guides/use-cases/split-tunnel/readme.mdx deleted file mode 100644 index 276b3d1f8..000000000 --- a/website/src/app/docs/user-guides/use-cases/split-tunnel/readme.mdx +++ /dev/null @@ -1,64 +0,0 @@ -import Alert from "@/components/DocsAlert"; -import Image from "next/image"; - -# Set Up IP-based Split Tunneling with Firezone - -This guide will describe the steps required to enable split tunneling with -WireGuard using Firezone so only traffic to defined IP ranges will be routed -through the VPN. - -Firezone sets the `Allowed IPs` field so traffic destined for specific IPs are -encrypted and routed through the gateway. - -## Step 1: Set AllowedIPs - -AllowedIPs can be set globally on the `/settings/default` page or individually -for each device during creation. Changes will only apply to new WireGuard tunnel -configurations generated by Firezone. - -set split tunneling defaults - -Some examples of values in this field are: - -- `0.0.0.0/0, ::/0` - all network traffic will be routed to the VPN server. -- `192.0.2.3/32` - only traffic to a single IP address will be routed to the VPN - server. -- `3.5.140.0/22` - only traffic to IPs in the `3.5.140.1 - 3.5.143.254` range - will be routed to the VPN server. In this example, the CIDR range for the - `ap-northeast-2` AWS region was used. - - - When deciding where to route a packet, Firezone chooses the egress interface - corresponding to the most specific route first. - - -## Step 2 (optional): Set the DNS server(s) - -You can define the DNS server(s) used by devices when the WireGuard tunnel is -active. By default, it uses Cloudflare's DNS servers (`1.1.1.1, 1.0.0.1`). Visit -the `/settings/default` page to override this value. - -For split tunneling, this may be desired if you run a DNS server that resolves -internal hosts to private IPs reachable via Firezone. - - - If you wish to resolve DNS queries over the encrypted VPN tunnel - (recommended), ensure the DNS IPs are included in `AllowedIPs`. - - -## Step 3: Regenerate the device configurations - -Changes made to global settings in the **Defaults** tab are only applied to -future device configurations generated by Firezone. - -Users need to regenerate device configurations to update existing devices for -the updated configuration changes to `AllowedIPs`, `DNS`, `PersistentKeepalive`, -`MTU`, and `Endpoint`. - -See [add device](/docs/user-guides/add-devices) for instructions. diff --git a/website/src/components/DocCards/index.tsx b/website/src/components/DocCards/index.tsx deleted file mode 100644 index e69de29bb..000000000 diff --git a/website/src/components/DocsSidebar/index.tsx b/website/src/components/DocsSidebar/index.tsx deleted file mode 100644 index f9484dcff..000000000 --- a/website/src/components/DocsSidebar/index.tsx +++ /dev/null @@ -1,185 +0,0 @@ -"use client"; -import { - Sidebar, - SidebarItem, - SidebarItems, - SidebarItemGroup, - SidebarCollapse, -} from "@/components/Sidebar"; -import KbSearch from "@/components/KbSearch"; - -export default function DocsSidebar() { - return ( - - - - - - - Overview - - Overview - Docker - - Supported Platforms - - Omnibus - - Supported Platforms - - Configure - - Security Considerations - - - Advanced: Build from Source - - - Advanced: External Database - - - Advanced: Custom Reverse Proxy - - - - Overview - - Local Auth - - - Multi-Factor Auth - - - OIDC Overview - - - OIDC: Auth0 - - - OIDC: Azure AD - - - OIDC: Google Workspace - - - OIDC: Keycloak - - - OIDC: Okta - - - OIDC: Onelogin - - - OIDC: Zitadel - - - SAML Overview - - - SAML: Google - - - SAML: Okta - - - SAML: Onelogin - - - SAML: Jumpcloud - - - - Overview - - Migrate to Docker - - Upgrade - Backup - - Uninstall - - - Troubleshoot - - - Regenerate Secret Keys - - - Debug Logs - - - - Overview - - Add Users - - - Add Devices - - - Egress Rules - - - Client Instructions - - - Use Cases - - - Use Cases: Split Tunnel - - - Use Cases: Reverse Tunnel - - - Use Cases: NAT Gateway - - - - - Environment Variables - - - Configuration File - - - File and Directory Locations - - - Telemetry - - - Reverse Proxy Templates: Apache - - - Reverse Proxy Templates: Traefik - - - Reverse Proxy Templates: HAProxy - - - Firewall Templates: nftables - - REST API - - REST API: Users - - - REST API: Configurations - - - REST API: Devices - - - REST API: Rules - - - Security Controls - - - - - - ); -}