mirror of
https://github.com/outbackdingo/firezone.git
synced 2026-01-27 10:18:54 +00:00
Remove docs.firezone.dev CNAME (#1418)
This corresponds to step (1) of #1417
This commit is contained in:
Jamil
23
docs/.gitignore
vendored
23
docs/.gitignore
vendored
@@ -1,23 +0,0 @@
|
||||
# Dependencies
|
||||
/node_modules
|
||||
|
||||
# Generated OpenAPI docs
|
||||
/docs/reference/REST\ API/
|
||||
|
||||
# Production
|
||||
/build
|
||||
|
||||
# Generated files
|
||||
.docusaurus
|
||||
.cache-loader
|
||||
|
||||
# Misc
|
||||
.DS_Store
|
||||
.env.local
|
||||
.env.development.local
|
||||
.env.test.local
|
||||
.env.production.local
|
||||
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
@@ -1 +0,0 @@
|
||||
docs.firezone.dev
|
||||
@@ -1,33 +0,0 @@
|
||||
# Website
|
||||
|
||||
This website is built using [Docusaurus 2](https://docusaurus.io/), a modern
|
||||
static website generator.
|
||||
|
||||
## Installation
|
||||
|
||||
```shell
|
||||
yarn
|
||||
```
|
||||
|
||||
## Local Development
|
||||
|
||||
```shell
|
||||
yarn run start
|
||||
```
|
||||
|
||||
This command starts a local development server and opens up a browser window.
|
||||
Most changes are reflected live without having to restart the server.
|
||||
|
||||
## Build
|
||||
|
||||
```shell
|
||||
yarn run build
|
||||
```
|
||||
|
||||
This command generates static content into the `build` directory and can be
|
||||
served using any static contents hosting service.
|
||||
|
||||
## Deployment
|
||||
|
||||
Deployment happens automatically when a new version is published. See the
|
||||
`publish_docs` CI workflow.
|
||||
@@ -1,3 +0,0 @@
|
||||
module.exports = {
|
||||
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
|
||||
};
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
title: Overview
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
[Firezone](https://www.firezone.dev/?utm_source=docs.firezone.dev) 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.
|
||||
|
||||
|
||||
|
||||
These docs explain how to deploy, configure, and use Firezone.
|
||||
|
||||
## Quick start
|
||||
|
||||
1. [Deploy](deploy): A step-by-step walk-through setting up Firezone.
|
||||
Start here if you are new.
|
||||
1. [Authenticate](authenticate): Set up authentication using local
|
||||
email/password, OpenID Connect, or SAML 2.0 and optionally enable
|
||||
TOTP-based MFA.
|
||||
1. [Administer](administer): Day to day administration of the Firezone
|
||||
server.
|
||||
1. [User Guides](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](./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](./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](./user-guides/use-cases/reverse-tunnel):
|
||||
Establish tunnels between multiple peers.
|
||||
|
||||
import SupportOptions from '@site/src/partials/_support_options.mdx';
|
||||
<SupportOptions />
|
||||
|
||||
## Contribute to firezone
|
||||
|
||||
We deeply appreciate any and all contributions to the project and do our best to
|
||||
ensure your contribution is included. To get started, see [CONTRIBUTING.md
|
||||
](https://github.com/firezone/firezone/blob/master/CONTRIBUTING.md).
|
||||
|
||||
<!-- Leaving these disabled until they're ready -->
|
||||
<!-- <feedback /> -->
|
||||
<!-- <newsletter /> -->
|
||||
@@ -1,11 +0,0 @@
|
||||
---
|
||||
title: Administer
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
```mdx-code-block
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
|
||||
|
||||
<DocCardList items={useCurrentSidebarCategory().items}/>
|
||||
```
|
||||
@@ -1,89 +0,0 @@
|
||||
---
|
||||
title: Backup and Restore
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
Firezone can be safely backed up and restored in a couple of minutes under
|
||||
most circumstances.
|
||||
|
||||
:::info
|
||||
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](/reference/file-and-directory-locations/) to a location of your
|
||||
choosing.
|
||||
|
||||
See the steps below for specific examples for Docker and Omnibus.
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="Docker" value="docker" default>
|
||||
|
||||
### 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):
|
||||
```
|
||||
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.
|
||||
```
|
||||
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:
|
||||
```
|
||||
tar -zxvfp /path/to/firezone-back.tgz -C / --numeric-owner
|
||||
```
|
||||
2. Optionally, enable Docker to boot on startup:
|
||||
```
|
||||
systemctl enable docker
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Omnibus" value="omnibus">
|
||||
|
||||
### Backup
|
||||
|
||||
1. Stop Firezone (warning: this **will** disconnect any users connected to the VPN):
|
||||
```
|
||||
firezone-ctl stop
|
||||
```
|
||||
2. Copy relevant files and folders:
|
||||
```
|
||||
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:
|
||||
```
|
||||
tar -zxvfp /path/to/firezone-back.tgz -C / --numeric-owner
|
||||
```
|
||||
2. Reconfigure Firezone to ensure configuration is applied to the host system:
|
||||
```
|
||||
firezone-ctl reconfigure
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
import SupportOptions from '@site/src/partials/_support_options.mdx';
|
||||
<SupportOptions />
|
||||
@@ -1,61 +0,0 @@
|
||||
---
|
||||
title: Debug Logs
|
||||
sidebar_position: 8
|
||||
description:
|
||||
Docker deployments of Firezone generate and store debug logs to a JSON
|
||||
file on the host machine.
|
||||
---
|
||||
|
||||
:::note
|
||||
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/).
|
||||
|
||||
:::note
|
||||
Audit logs are in early Beta on the Enterprise plan. These track configuration
|
||||
changes by admins and network activity by users.
|
||||
[Contact us](https://www.firezone.dev/contact/sales?utm_source=docs.firezone.dev)
|
||||
to learn more.
|
||||
:::
|
||||
|
||||
## 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.
|
||||
@@ -1,73 +0,0 @@
|
||||
---
|
||||
title: Migrate to Docker
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# 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/master/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
|
||||
](/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
|
||||
](/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/master/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.
|
||||
|
||||
import SupportOptions from '@site/src/partials/_support_options.mdx';
|
||||
<SupportOptions />
|
||||
@@ -1,84 +0,0 @@
|
||||
---
|
||||
title: Regenerate Secret Keys
|
||||
sidebar_position: 7
|
||||
---
|
||||
|
||||
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
|
||||
|
||||
:::warning
|
||||
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.
|
||||
:::
|
||||
|
||||
:::caution
|
||||
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:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="docker" label="Docker" default>
|
||||
|
||||
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.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="omnibus" label="Omnibus">
|
||||
|
||||
```bash
|
||||
mv /etc/firezone/secrets.json /etc/firezone/secrets.bak.json
|
||||
sudo firezone-ctl reconfigure
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Regenerate WireGuard private key
|
||||
|
||||
:::warning
|
||||
Replacing the WireGuard private key will render all existing device configs
|
||||
invalid. Only do so if you're prepared to also regenerate device configs
|
||||
after regenerating the WireGuard private key.
|
||||
:::
|
||||
|
||||
To regenerate WireGuard private key, simply move or rename the private key file.
|
||||
Firezone will generate a new one on next start.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="docker" label="Docker" default>
|
||||
|
||||
```bash
|
||||
cd $HOME/.firezone
|
||||
docker-compose stop firezone
|
||||
sudo mv firezone/private_key firezone/private_key.bak
|
||||
docker-compose start firezone
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="omnibus" label="Omnibus">
|
||||
|
||||
```bash
|
||||
sudo firezone-ctl stop phoenix
|
||||
sudo mv /var/opt/firezone/cache/wg_private_key /var/opt/firezone/cache/wg_private_key.bak
|
||||
sudo firezone-ctl start phoenix
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
@@ -1,205 +0,0 @@
|
||||
---
|
||||
title: Troubleshoot
|
||||
sidebar_position: 6
|
||||
description: Troubleshoot common connectivity and configuration issues with Firezone's WireGuard®-based secure access platform.
|
||||
---
|
||||
|
||||
This guide documents common configuration and connectivity issues. For
|
||||
any problems that arise, a good first bet is to check the Firezone logs.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="docker" label="Docker" default>
|
||||
|
||||
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](../debug-logs) for additional details.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="omnibus" label="Omnibus">
|
||||
|
||||
Firezone logs are stored in `/var/log/firezone` and can be viewed with
|
||||
`sudo firezone-ctl tail`.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## 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:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="docker" label="Docker" default>
|
||||
|
||||
```text
|
||||
psql -d firezone -h 127.0.0.1 -U postgres -c "UPDATE configurations SET openid_connect_providers = '[]'"
|
||||
```
|
||||
|
||||
Similarly, to clear SAML configs:
|
||||
|
||||
```text
|
||||
psql -d firezone -h 127.0.0.1 -U postgres -c "UPDATE configurations SET saml_identity_providers = '[]'"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="omnibus" label="Omnibus">
|
||||
|
||||
```text
|
||||
/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:
|
||||
|
||||
```text
|
||||
/opt/firezone/embedded/bin/psql -d $DATABASE_NAME -h $DATABASE_HOST -U $DATABASE_USER -c "UPDATE configurations SET saml_identity_providers = '[]'"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## 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:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="omnibus" label="Omnibus">
|
||||
|
||||
* Your browser's developer tool logs, specifically the `Network` tab.
|
||||
* `sudo firezone-ctl tail nginx`
|
||||
* `sudo firezone-ctl tail phoenix`
|
||||
|
||||
If the websocket connection is successful, you should see output in the
|
||||
`phoenix` service logs similar the following:
|
||||
|
||||
```text
|
||||
2022-09-23_15:05:47.29158 15:05:47.291 [info] CONNECTED TO Phoenix.LiveView.Socket in 24µs
|
||||
2022-09-23_15:05:47.29160 Transport: :websocket
|
||||
2022-09-23_15:05:47.29160 Serializer: Phoenix.Socket.V2.JSONSerializer
|
||||
2022-09-23_15:05:47.29161 Parameters: %{"_csrf_token" => "XFEFCHQ2fRQABQwtKQdCJDlFAzEcCCJvn7LqDsMXE4eGZtsBzuwVRCJ6", "_mounts" => "0", "_track_static" => %{"0" => "https://demo.firez.one/dist/admin-02fabe0f543c64122dbf5bc5b3451e51.css?vsn=d", "1" => "https://demo.firez.one/dist/admin-04e75c78295062c2c07af61be50248b0.js?vsn=d"}, "vsn" => "2.0.0"}
|
||||
2022-09-23_15:05:47.33655 15:05:47.336 [info] CONNECTED TO FzHttpWeb.UserSocket in 430µs
|
||||
2022-09-23_15:05:47.33657 Transport: :websocket
|
||||
2022-09-23_15:05:47.33658 Serializer: Phoenix.Socket.V2.JSONSerializer
|
||||
2022-09-23_15:05:47.33658 Parameters: %{"token" => "SFMyNTY.g2gDYQFuBgB6HeJqgwFiAAFRgA.qKoC2bi9DubPkE0tfaRSPERWUFyQQPQV5n4nFKVppxc", "vsn" => "2.0.0"}
|
||||
2022-09-23_15:05:47.35063 15:05:47.350 [info] JOINED notification:session in 636µs
|
||||
2022-09-23_15:05:47.35065 Parameters: %{"token" => "SFMyNTY.g2gDYQFuBgB6HeJqgwFiAAFRgA.zSG7pefm-Vgf_zvduxa5E9VK4s8PKqzc0xBDGNx5FQE", "user_agent" => "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:106.0) Gecko/20100101 Firefox/106.0"}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## 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 `ADMIN_EMAIL` isn't working, you can
|
||||
reset it using the process below.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="docker" label="Docker" default>
|
||||
|
||||
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
|
||||
`ADMIN_EMAIL`
|
||||
in `$HOME/.firezone/.env` will be reset to the `DEFAULT_ADMIN_PASSWORD` variable.
|
||||
|
||||
```shell
|
||||
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.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="omnibus" label="Omnibus">
|
||||
|
||||
Run the following command to reset the password on the default admin user.
|
||||
|
||||
```shell
|
||||
sudo firezone-ctl create-or-reset-admin
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Re-enable local authentication via CLI
|
||||
|
||||
If you've configured an [OIDC](/authenticate/oidc/) or [SAML](/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](/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:
|
||||
|
||||
```shell
|
||||
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'"
|
||||
```
|
||||
|
||||
import SupportOptions from '@site/src/partials/_support_options.mdx';
|
||||
<SupportOptions />
|
||||
@@ -1,37 +0,0 @@
|
||||
---
|
||||
title: Uninstall
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
Firezone can be uninstalled using the steps below.
|
||||
|
||||
:::warning
|
||||
This will irreversibly destroy ALL Firezone data and can't be undone.
|
||||
:::
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="Docker" value="docker" default>
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Omnibus" value="omnibus">
|
||||
|
||||
To completely remove Omnibus-based deployments of Firezone run the [uninstall.sh
|
||||
script](https://github.com/firezone/firezone/blob/master/scripts/omnibus-uninstall.sh):
|
||||
|
||||
```bash
|
||||
sudo /bin/bash -c "$(curl -fsSL https://github.com/firezone/firezone/raw/master/scripts/omnibus-uninstall.sh)"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
@@ -1,277 +0,0 @@
|
||||
---
|
||||
title: Upgrade
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
Upgrading Firezone will pause all VPN sessions and temporarily bring
|
||||
down the web UI.
|
||||
|
||||
:::info
|
||||
Automatic rollbacks are still under development. We recommend backing up
|
||||
relevant [files and folders](/reference/file-and-directory-locations/)
|
||||
before upgrading in case anything goes wrong.
|
||||
:::
|
||||
|
||||
Follow the steps below to upgrade Firezone:
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="Docker" value="docker" default>
|
||||
|
||||
1. Change to your Firezone installation directory, by default `$HOME/.firezone`:
|
||||
```
|
||||
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:
|
||||
```
|
||||
docker compose pull
|
||||
```
|
||||
1. Re-up the services (**warning: this will restart updated services**):
|
||||
```
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Omnibus" value="omnibus">
|
||||
|
||||
1. If not setup already, install our package repository based on your distro's
|
||||
package format:
|
||||
- [deb packages](https://cloudsmith.io/~firezone/repos/firezone/setup/#formats-deb)
|
||||
- [rpm packages](https://cloudsmith.io/~firezone/repos/firezone/setup/#formats-rpm)
|
||||
1. Upgrade the `firezone` package using your distro's package manager.
|
||||
1. Run `firezone-ctl reconfigure` to pick up the new changes.
|
||||
1. Run `firezone-ctl restart` to restart services.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
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](/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](/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](/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: 2001:3990:3990::99
|
||||
|
||||
# ...
|
||||
networks:
|
||||
firezone-network:
|
||||
ipam:
|
||||
config:
|
||||
- subnet: 2001:3990:3990::/64
|
||||
- gateway: 2001:3990:3990::1
|
||||
```
|
||||
|
||||
You also need to update the Docker daemon to enable IPv6. See our [IPv6 guide](
|
||||
https://docs.firezone.dev/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](/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](/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](/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`
|
||||
|
||||
```rb
|
||||
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](/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`
|
||||
|
||||
```rb
|
||||
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](/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.
|
||||
|
||||
|
||||
|
||||
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](/authenticate/oidc/) .
|
||||
|
||||
### I have an existing OAuth integration
|
||||
|
||||
Prior to 0.3.11, Firezone used pre-configured OAuth2 providers. Follow the
|
||||
instructions [here](/authenticate/oidc/) to migrate to OIDC.
|
||||
|
||||
### I have not integrated an identity provider
|
||||
|
||||
No action needed. You can follow the instructions
|
||||
[here](/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](/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
|
||||
```
|
||||
@@ -1,89 +0,0 @@
|
||||
---
|
||||
title: Authenticate
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
Firezone supports the following authentication methods:
|
||||
|
||||
1. [Local email/password (default)](local-auth)
|
||||
1. [SSO authentication via OpenID Connect](oidc)
|
||||
1. [SSO authentication via SAML 2.0](saml)
|
||||
|
||||
:::note
|
||||
If your Identity Provider doesn't work with the methods listed above,
|
||||
[contact us](https://www.firezone.dev/contact/sales?utm_source=docs.firezone.dev) about custom integrations.
|
||||
:::
|
||||
|
||||
## 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](oidc/okta)
|
||||
* [Azure Active Directory](oidc/azuread)
|
||||
* [Google](oidc/google)
|
||||
* [Onelogin](oidc/onelogin)
|
||||
* [JumpCloud](saml/jumpcloud)
|
||||
* [Keycloak](oidc/keycloak)
|
||||
* [Zitadel](oidc/zitadel)
|
||||
* [Auth0](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](oidc).
|
||||
|
||||
Open a [Github issue](https://github.com/firezone/firezone/issues)
|
||||
to request documentation or submit a pull request to add documentation for your
|
||||
provider.
|
||||
|
||||
### The OIDC redirect URI
|
||||
|
||||
For each OIDC provider a corresponding URL is created for redirecting to
|
||||
the configured provider's sign-in URL. The URL format is `https://firezone.example.com/auth/oidc/CONFIG_ID`
|
||||
where `CONFIG_ID` is the OIDC Config ID for that particular provider.
|
||||
|
||||
For example, the OIDC config below:
|
||||
|
||||
<center>
|
||||
<img width="509" alt="config-oidc" src="https://user-images.githubusercontent.com/167144/216438674-a2b64b3b-2ed6-43dc-b554-de9c055dc741.png"/>
|
||||
</center>
|
||||
|
||||
would generate the following OIDC login URL:
|
||||
|
||||
* `https://firezone.example.com/auth/oidc/google`
|
||||
|
||||
This URL could then be distributed to end users for direct navigation to
|
||||
the identity provider's login portal for authentication to Firezone.
|
||||
|
||||
## Enforce periodic re-authentication
|
||||
|
||||
Periodic re-authentication can be enforced by changing the setting in
|
||||
`settings/security`. This can be used to ensure a user must sign in to Firezone
|
||||
periodically in order to maintain their VPN session.
|
||||
|
||||
You can set the session length to a minimum of **1 hour** and maximum of **90 days**.
|
||||
Setting this to Never disables this setting, allowing VPN sessions indefinitely.
|
||||
This is the default.
|
||||
|
||||
### Re-authentication
|
||||
|
||||
To re-authenticate an expired VPN session, a user will need to turn off their
|
||||
VPN session and sign in to the Firezone portal (URL specified during
|
||||
[deployment](../deploy#prepare-to-deploy)).
|
||||
|
||||
See detailed Client Instructions on how to re-authenticate your session
|
||||
[here](../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.
|
||||
|
||||
import SupportOptions from '@site/src/partials/_support_options.mdx';
|
||||
<SupportOptions />
|
||||
@@ -1,30 +0,0 @@
|
||||
---
|
||||
title: Local Authentication
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Local authentication (email & password)
|
||||
|
||||
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](/user-guides/add-users/) for more details.
|
||||
|
||||
:::caution
|
||||
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](/authenticate/oidc/) or [SAML](/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
|
||||
](/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](/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
|
||||
](/administer/troubleshoot#re-enable-local-authentication-via-cli) for re-enabling
|
||||
local authentication from the CLI.
|
||||
@@ -1,40 +0,0 @@
|
||||
---
|
||||
title: Multi-Factor Authentication
|
||||
sidebar_position: 2
|
||||
description:
|
||||
Enforce multi-factor authentication with Firezone's WireGuard®-based
|
||||
secure access platform.
|
||||
---
|
||||
|
||||
# Multi-factor authentication (MFA)
|
||||
|
||||
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
|
||||
](../#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)
|
||||
@@ -1,67 +0,0 @@
|
||||
---
|
||||
title: OpenID Connect
|
||||
sidebar_position: 10
|
||||
description:
|
||||
Setup single sign-on with your identity provider. Integrate
|
||||
providers like Okta, Google, Azure, and JumpCloud using Firezone's
|
||||
OpenID Connect (OIDC) connector.
|
||||
---
|
||||
|
||||
# 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
|
||||
](https://www.firezone.dev/contact/sales?utm_source=docs.firezone.dev) about a custom integration.
|
||||
|
||||
The following OIDC providers are known to work well with Firezone:
|
||||
|
||||
| Provider | Support Status | Notes |
|
||||
| --- | --- | --- |
|
||||
| [Azure Active Directory](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](okta) | **Fully tested and supported** | |
|
||||
| [Onelogin](onelogin) | **Fully tested and supported** | |
|
||||
| [Keycloak](https://www.keycloak.org/) | **Fully tested and supported** | |
|
||||
| [Auth0](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](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](zitadel) | Untested but known to work | |
|
||||
| [Authentik](https://goauthentik.io/) | Untested but known to work | |
|
||||
|
||||
## General setup guide
|
||||
|
||||
If you're using an OIDC provider not listed above, the following OIDC attributes
|
||||
are required for setting up an OIDC provider in Firezone:
|
||||
|
||||
1. `discovery_document_uri`: The
|
||||
[OpenID Connect provider configuration URI](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig)
|
||||
which returns a JSON document used to construct subsequent requests to this
|
||||
OIDC provider. Some providers refer to this as the "well-known URL".
|
||||
1. `client_id`: The client ID of the application.
|
||||
1. `client_secret`: The client secret of the application.
|
||||
1. `redirect_uri`: Instructs OIDC provider where to redirect after authentication.
|
||||
This should be your Firezone `EXTERNAL_URL + /auth/oidc/<provider_key>/callback/`
|
||||
(e.g. `https://firezone.example.com/auth/oidc/google/callback/`).
|
||||
1. `response_type`: Set to `code`.
|
||||
1. `scope`: [OIDC scopes](https://openid.net/specs/openid-connect-basic-1_0.html#Scopes)
|
||||
to obtain from your OIDC provider. At a minimum, Firezone requires the `openid`
|
||||
and `email` scopes.
|
||||
1. `label`: The button label text displayed on the Firezone portal login page.
|
||||
|
||||
### PKCE
|
||||
|
||||
Firezone supports Proof Key for Code Exchange (PKCE) for increased login security.
|
||||
We recommend you enable PKCE in your IdP's settings whenever available. [Read more
|
||||
about PKCE here](https://oauth.net/2/pkce/).
|
||||
|
||||
### OIDC logout URI
|
||||
|
||||
The OpenID Connect standard [defines a mechanism](https://openid.net/specs/openid-connect-rpinitiated-1_0.html)
|
||||
for a Relying Party (RP) to request that an OpenID Provider log out the End-User.
|
||||
|
||||
Unfortunately, not all IdPs support this (e.g. Google, Auth0). For the providers
|
||||
that do support this mechanism, Firezone automatically detects the `end_session_uri`
|
||||
found in the provider's discovery document and uses that to log out the End-User.
|
||||
@@ -1,69 +0,0 @@
|
||||
---
|
||||
title: Auth0
|
||||
sidebar_position: 1
|
||||
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).
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
|
||||
|
||||
Next, visit the settings tab on the application details page. Take note and
|
||||
modify the following parameters:
|
||||
|
||||
1. **Name**: `Firezone`
|
||||
1. **Domain**: The domain will be used to construct
|
||||
the url to retrieve the OIDC discovery document - `https://<AUTH0_DOMAIN>/.well-known/openid-configuration`
|
||||
1. **Icon**:
|
||||
[Firezone icon](https://user-images.githubusercontent.com/52545545/156854754-da66a9e1-33d5-47f5-877f-eff8b330ab2b.png)
|
||||
(save link as).
|
||||
1. Set **Allowed Callback URLs** to `EXTERNAL_URL + /auth/oidc/<Config ID>/callback/`
|
||||
(e.g. `https://firezone.example.com/auth/oidc/auth0/callback/`).
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
@@ -1,84 +0,0 @@
|
||||
---
|
||||
title: Azure Active Directory
|
||||
sidebar_position: 2
|
||||
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).
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
|
||||
|
||||
## Step 1: Obtain configuration parameters
|
||||
|
||||
_This guide is adapted from the [Azure Active Directory documentation](https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/auth-oidc)._
|
||||
|
||||
Navigate to the Azure Active Directory page on the Azure portal.
|
||||
Select the App registrations link under the Manage menu, click
|
||||
`New Registration`, and register after entering the following:
|
||||
|
||||
1. **Name**: `Firezone`
|
||||
1. **Supported account types**: `(Default Directory only - Single tenant)`
|
||||
1. **Redirect URI**: This should be your Firezone `EXTERNAL_URL + /auth/oidc/<Config ID>/callback/`
|
||||
(e.g. `https://firezone.example.com/auth/oidc/azure/callback/`).
|
||||
Make sure you include the trailing slash.
|
||||
**This will be the `redirect_uri` value**.
|
||||
|
||||
|
||||
|
||||
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**.
|
||||
|
||||
|
||||
|
||||
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**.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
@@ -1,92 +0,0 @@
|
||||
---
|
||||
title: Google Workspace
|
||||
sidebar_position: 3
|
||||
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).
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
On the App information screen:
|
||||
|
||||
1. **App name**: `Firezone`
|
||||
1. **App logo**: [Firezone logo](https://user-images.githubusercontent.com/52545545/156854754-da66a9e1-33d5-47f5-877f-eff8b330ab2b.png)
|
||||
(save link as).
|
||||
1. **Application home page**: the URL of your Firezone instance.
|
||||
1. **Authorized domains**: the top level domain of your Firezone instance.
|
||||
|
||||
|
||||
|
||||
On the next step add the following 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`.
|
||||
|
||||
|
||||
|
||||
On the OAuth client ID creation screen:
|
||||
|
||||
1. Set `Application Type` to `Web application`
|
||||
1. Add your Firezone `EXTERNAL_URL + /auth/oidc/<Config ID>/callback/`
|
||||
(e.g. `https://firezone.example.com/auth/oidc/google/callback/`) as an entry to
|
||||
Authorized redirect URIs.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
@@ -1,80 +0,0 @@
|
||||
---
|
||||
title: Keycloak
|
||||
sidebar_position: 4
|
||||
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).
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
|
||||
|
||||
### 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**.
|
||||
|
||||
|
||||
|
||||
1. Toggle **Client authentication** to `On` to generate the client secret.
|
||||
1. Click **Save**.
|
||||
|
||||
|
||||
|
||||
Click **Access settings** to jump to that section and configure the valid redirect URI:
|
||||
|
||||
1. **Valid Redirect URIs**: This should be your Firezone `EXTERNAL_URL + /auth/oidc/<Config ID>/callback/`
|
||||
(e.g. `https://firezone.example.com/auth/oidc/keycloak/callback/`).
|
||||
1. Click **Add valid redirect URIs**
|
||||
|
||||
|
||||
|
||||
Click the **Credentials** tab and copy the 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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
@@ -1,83 +0,0 @@
|
||||
---
|
||||
title: Okta
|
||||
sidebar_position: 5
|
||||
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).
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
|
||||
|
||||
## 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**.
|
||||
|
||||
|
||||
|
||||
On the following screen, configure the following settings:
|
||||
|
||||
1. **App Name**: `Firezone`
|
||||
1. **App logo**:
|
||||
[Firezone logo](https://user-images.githubusercontent.com/52545545/155907625-a4f6c8c2-3952-488d-b244-3c37400846cf.png)
|
||||
(save link as).
|
||||
1. **Proof Key for Code Exchange (PKCE)**: Check `Require PKCE as additional verification` if you're running Firezone
|
||||
0.6.8 or higher. [PKCE](https://oauth.net/2/pkce/) is recommended for increased security whenever possible.
|
||||
1. **Grant Type**: Check the **Refresh Token** box. This ensures Firezone syncs
|
||||
with the identity provider and VPN access is terminated once the user is removed.
|
||||
1. **Sign-in redirect URIs**: Add your Firezone `EXTERNAL_URL + /auth/oidc/<Config ID>/callback/`
|
||||
(e.g. `https://firezone.example.com/auth/oidc/okta/callback/`) as an entry to
|
||||
Authorized redirect URIs.
|
||||
1. **Assignments**:
|
||||
Limit to the groups you wish to provide access to your Firezone instance.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
@@ -1,65 +0,0 @@
|
||||
---
|
||||
title: OneLogin
|
||||
sidebar_position: 6
|
||||
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).
|
||||
---
|
||||
|
||||
# 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**: [Firezone logo](https://user-images.githubusercontent.com/52545545/156854754-da66a9e1-33d5-47f5-877f-eff8b330ab2b.png)
|
||||
or
|
||||
[Firezone icon](https://user-images.githubusercontent.com/52545545/156854754-da66a9e1-33d5-47f5-877f-eff8b330ab2b.png)
|
||||
(save link as).
|
||||
1. **Sign on method**: select **OpenID Connect**
|
||||
1. **Redirect URI**: Add your Firezone `<EXTERNAL_URL> + /auth/oidc/<Config ID>/callback/`
|
||||
(e.g. `https://firezone.example.com/auth/oidc/onelogin/callback/`).
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
@@ -1,103 +0,0 @@
|
||||
---
|
||||
title: Zitadel
|
||||
sidebar_position: 7
|
||||
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).
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
|
||||
|
||||
## Requirements
|
||||
|
||||
* Setup your own [Zitadel Cloud](https://zitadel.cloud/) account.
|
||||
* Create your first Zitadel instance in the
|
||||
[Zitadel Customer portal](https://zitadel.cloud/admin/instances)
|
||||
* 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://docs.zitadel.com/docs/guides/start/quickstart#try-out-zitadel-cloud).
|
||||
|
||||
## Create Zitadel Application
|
||||
|
||||
In the Instance Console, go to **Projects** and select the project you want,
|
||||
then click **New**.
|
||||
|
||||
|
||||
|
||||
Give the application a name (e.g. "Firezone") and select **WEB**
|
||||
for the application type.
|
||||
|
||||
|
||||
|
||||
Select **CODE** for the authentication method.
|
||||
|
||||
|
||||
|
||||
Specify the redirect URI and post logout URI.
|
||||
|
||||
1. **Redirect URIs**: `EXTERNAL_URL + /auth/oidc/<Config ID>/callback/`
|
||||
(e.g. `https://vpn.example.com/auth/oidc/zitadel/callback/`)
|
||||
1. **Post Logout URIs**: `EXTERNAL_URL` (e.g. `https://vpn.example.com`)
|
||||
|
||||
|
||||
|
||||
Double-check the configuration, then click **Create**.
|
||||
|
||||
|
||||
|
||||
Copy the **ClientId** and **ClientSecret** as it will be used for the Firezone
|
||||
configuration.
|
||||
|
||||
|
||||
|
||||
In the application **Configuration** click **Refresh Token** and then on
|
||||
**Save**. The refresh token is optional for some features of Firezone.
|
||||
|
||||
|
||||
|
||||
In the application **Token Settings** select **User roles inside ID Token** and
|
||||
**User Info inside ID Token**. Save it with a click on **Save**.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
@@ -1,94 +0,0 @@
|
||||
---
|
||||
title: SAML 2.0
|
||||
sidebar_position: 11
|
||||
description:
|
||||
Enforce single sign-on with your identity provider. Integrate
|
||||
providers like Okta, Google, OneLogin, and JumpCloud using Firezone's
|
||||
SAML 2.0 connector.
|
||||
---
|
||||
|
||||
# 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](okta) | **Tested and supported** | |
|
||||
| [Google Workspace](google) | **Tested and supported** | Uncheck `Require signed envelopes` |
|
||||
| [OneLogin](onelogin) | **Tested and supported** | |
|
||||
| [JumpCloud](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](
|
||||
https://www.firezone.dev/contact/sales?utm_source=docs.firezone.dev) 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`:
|
||||
|
||||
```
|
||||
openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout saml.key -out saml.crt
|
||||
```
|
||||
|
||||
Then use them with your Firezone installation:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="docker" label="Docker" default>
|
||||
|
||||
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/master/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.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="omnibus" label="Omnibus">
|
||||
|
||||
Set the following attributes in your `/etc/firezone/firezone.rb` configuration file:
|
||||
|
||||
```ruby
|
||||
default['firezone']['authentication']['saml']['key'] = '/path/to/your/saml.key'
|
||||
default['firezone']['authentication']['saml']['cert'] = '/path/to/your/saml.crt'
|
||||
```
|
||||
|
||||
and run `firezone-ctl reconfigure` to pick up the changes.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## 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](/reference/env-vars) for more information.
|
||||
@@ -1,54 +0,0 @@
|
||||
---
|
||||
title: Google Workspace
|
||||
sidebar_position: 2
|
||||
description:
|
||||
Enforce 2FA/MFA using Google Workspace 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.
|
||||
---
|
||||
|
||||
# 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](https://user-images.githubusercontent.com/52545545/202567638-513dba14-ea8c-4da8-8f75-341310f1e456.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 |
|
||||
|
||||
|
||||
|
||||
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. | |
|
||||
| Required 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. |
|
||||
|
||||
|
||||
|
||||
After saving the SAML config, you should see a `Sign in with Google` button
|
||||
on your Firezone portal sign-in page.
|
||||
@@ -1,71 +0,0 @@
|
||||
---
|
||||
title: JumpCloud
|
||||
sidebar_position: 4
|
||||
description:
|
||||
Enforce 2FA/MFA using JumpCloud 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.
|
||||
---
|
||||
|
||||
# Enable SSO with JumpCloud (SAML 2.0)
|
||||
|
||||
:::note
|
||||
This guide assumes you have completed the prerequisite steps
|
||||
(e.g. generate self-signed X.509 certificates) outlined [here](/authenticate/saml#prerequisites).
|
||||
:::
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
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. | |
|
||||
| Required 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:
|
||||
|
||||
|
||||
|
||||
After saving the SAML config, you should see a `Sign in with JumpCloud` button
|
||||
on your Firezone portal sign-in page.
|
||||
@@ -1,63 +0,0 @@
|
||||
---
|
||||
title: Okta
|
||||
sidebar_position: 1
|
||||
description:
|
||||
Enforce 2FA/MFA using Okta 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.
|
||||
---
|
||||
|
||||
# Enable SSO with Okta (SAML 2.0)
|
||||
|
||||
:::note
|
||||
This guide assumes you have completed the prerequisite steps
|
||||
(e.g. generate self-signed X.509 certificates) outlined [here](/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](https://user-images.githubusercontent.com/52545545/155907625-a4f6c8c2-3952-488d-b244-3c37400846cf.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.
|
||||
|
||||
|
||||
|
||||
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. | |
|
||||
| Required 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. |
|
||||
|
||||
|
||||
|
||||
After saving the SAML config, you should see a `Sign in with Okta` button
|
||||
on your Firezone portal sign-in page.
|
||||
@@ -1,67 +0,0 @@
|
||||
---
|
||||
title: OneLogin
|
||||
sidebar_position: 3
|
||||
description:
|
||||
Enforce 2FA/MFA using Onelogin 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.
|
||||
---
|
||||
|
||||
# Enable SSO with OneLogin (SAML 2.0)
|
||||
|
||||
:::note
|
||||
This guide assumes you have completed the prerequisite steps
|
||||
(e.g. generate self-signed X.509 certificates) outlined [here](/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.
|
||||
|
||||
|
||||
|
||||
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. | |
|
||||
| Required 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. |
|
||||
|
||||
|
||||
|
||||
After saving the SAML config, you should see a `Sign in with OneLogin` button
|
||||
on your Firezone portal sign-in page.
|
||||
@@ -1,107 +0,0 @@
|
||||
---
|
||||
title: Deploy
|
||||
sidebar_position: 2
|
||||
description:
|
||||
Install Firezone's WireGuard®-based secure access platform on a support
|
||||
host using our Docker (recommended) or Omnibus deployment methods.
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="docker" label="Docker" default>
|
||||
|
||||
#### 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](docker) for more info.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="omnibus" label="Omnibus">
|
||||
|
||||
For Omnibus-based deployments, ACME is disabled by default to maintain
|
||||
compatibility with existing installations.
|
||||
|
||||
To enable ACME, ensure the following conditions are met:
|
||||
|
||||
* `80/tcp` is allow inbound
|
||||
* The bundled Firezone `nginx` service is enabled and functioning
|
||||
* You have a valid DNS record assigned to this instance's public IP
|
||||
* The following 3 settings are configured in the [configuration file](../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.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### 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](../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](docker) (recommended)
|
||||
1. [Omnibus](omnibus)
|
||||
|
||||
Docker is the easiest way to install, manage, and upgrade Firezone and is the
|
||||
preferred method of deployment.
|
||||
|
||||
:::warning
|
||||
Chef Infra Client, the configuration system Chef Omnibus relies on, has been
|
||||
[scheduled for End-of-Life in 2024](https://docs.chef.io/versions/). As such,
|
||||
support for Omnibus-based deployments will be removed starting with Firezone 0.8.
|
||||
Firezone. To transition to Docker from Omnibus today, follow our [migration guide
|
||||
](../administer/migrate).
|
||||
:::
|
||||
@@ -1,11 +0,0 @@
|
||||
---
|
||||
title: Advanced
|
||||
sidebar_position: 8
|
||||
---
|
||||
|
||||
```mdx-code-block
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
|
||||
|
||||
<DocCardList items={useCurrentSidebarCategory().items}/>
|
||||
```
|
||||
@@ -1,91 +0,0 @@
|
||||
---
|
||||
title: Build From Source
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
Building from source allows you to bring Firezone to unsupported platforms.
|
||||
|
||||
:::warning
|
||||
You're entering unsupported territory. This is not for the faint of heart and
|
||||
will require being able to figure out snags you may hit on your own.
|
||||
|
||||
If you're very comfortable with your environment of choice, then read on to
|
||||
learn how to build Firezone from source.
|
||||
:::
|
||||
|
||||
:::info
|
||||
You will need to setup your own service management for Firezone (eg. `runit`,
|
||||
`systemd`, shell scripts). You will also need to install and configure your
|
||||
own database (eg. `postgres`) and reverse proxy (eg. `caddy`, `nginx`).
|
||||
|
||||
Info about database configuration is [here](../external-database/#configure-firezone-to-connect),
|
||||
and info about configuring a reverse proxy is [here](../reverse-proxy/#proxy-requirements).
|
||||
:::
|
||||
|
||||
# Prerequisites
|
||||
|
||||
:::info
|
||||
Check the `.tool-versions` file [here](https://github.com/firezone/firezone/blob/master/.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
|
||||
`<CURRENT_DIR>/_build/dev/rel/firezone`. In the `bin` folder, the `firezone` binary
|
||||
can be used to start up Firezone. If you run it without any arguments you should see
|
||||
a list of available commands like this:
|
||||
|
||||
```bash
|
||||
Usage: firezone COMMAND [ARGS]
|
||||
|
||||
The known commands are:
|
||||
|
||||
start Starts the system
|
||||
start_iex Starts the system with IEx attached
|
||||
daemon Starts the system as a daemon
|
||||
daemon_iex Starts the system as a daemon with IEx attached
|
||||
eval "EXPR" Executes the given expression on a new, non-booted system
|
||||
rpc "EXPR" Executes the given expression remotely on the running system
|
||||
remote Connects to the running system via a remote shell
|
||||
restart Restarts the running system via a remote command
|
||||
stop Stops the running system via a remote command
|
||||
pid Prints the operating system PID of the running system via a remote command
|
||||
version Prints the release name and version to be booted
|
||||
```
|
||||
|
||||
Most deployment-related configuration is handled with environment variables.
|
||||
You'll probably want to at least set variables related to your reverse proxy
|
||||
and database. See the [ENV var reference](/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 :)
|
||||
|
||||
:::info
|
||||
As mentioned at the top, it's recommended to use some sort of service management
|
||||
to start and stop Firezone easily without having to manually do it using the
|
||||
`firezone` binary directly. But the choice is yours, since you're in control!
|
||||
:::
|
||||
@@ -1,86 +0,0 @@
|
||||
---
|
||||
title: Custom External Database
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
:::warning
|
||||
Configuring Firezone to use an external database can be complicated and
|
||||
error-prone. We recommend using the bundled Postgres for Omnibus-based
|
||||
deployments or the official Postgres Docker image for Docker-based deployments
|
||||
if possible.
|
||||
:::
|
||||
|
||||
:::info
|
||||
Need help deploying or maintaining Firezone with an external database? Consider
|
||||
[contacting us about our Enterprise Plan](https://www.firezone.dev/contact/sales?utm_source=docs.firezone.dev) for
|
||||
recommended configurations, white-glove deployment assistance, and more.
|
||||
:::
|
||||
|
||||
## Configure Firezone to Connect
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="docker" label="Docker" default>
|
||||
|
||||
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
|
||||
](/reference/env-vars/).
|
||||
|
||||
:::note
|
||||
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.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="omnibus" label="Omnibus">
|
||||
|
||||
The following configuration options are used to configure the bundled Postgres
|
||||
for Omnibus-based deployments:
|
||||
|
||||
| Config Key | Description | Default |
|
||||
| --- | --- | --- |
|
||||
| `default['firezone']['database']['user']` | Specifies the username Firezone will use to connect to the DB. | `node['firezone']['postgresql']['username']` |
|
||||
| `default['firezone']['database']['password']` | If using an external DB, specifies the password Firezone will use to connect to the DB. | `'change_me'` |
|
||||
| `default['firezone']['database']['name']` | Database that Firezone will use. Will be created if it doesn't exist. | `'firezone'` |
|
||||
| `default['firezone']['database']['host']` | Database host that Firezone will connect to. | `node['firezone']['postgresql']['listen_address']` |
|
||||
| `default['firezone']['database']['port']` | Database port that Firezone will connect to. | `node['firezone']['postgresql']['port']` |
|
||||
| `default['firezone']['database']['pool']` | Database pool size Firezone will use. | `[10, Etc.nprocessors].max` |
|
||||
| `default['firezone']['database']['ssl']` | Whether to connect to the database over SSL. | `false` |
|
||||
| `default['firezone']['database']['ssl_opts']` | Hash of options to send to the `:ssl_opts` option when connecting over SSL. See [Ecto.Adapters.Postgres documentation](https://hexdocs.pm/ecto_sql/Ecto.Adapters.Postgres.html#module-connection-options). | `{}` |
|
||||
| `default['firezone']['database']['parameters']` | Hash of parameters to send to the `:parameters` option when connecting to the database. See [Ecto.Adapters.Postgres documentation](https://hexdocs.pm/ecto_sql/Ecto.Adapters.Postgres.html#module-connection-options). | `{}` |
|
||||
| `default['firezone']['database']['extensions']` | Database extensions to enable. | `{ 'plpgsql' => true, 'pg_trgm' => true }` |
|
||||
|
||||
For more details, see the [configuration file reference
|
||||
](/reference/configuration-file/).
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
@@ -1,111 +0,0 @@
|
||||
---
|
||||
title: Custom Reverse Proxy
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
:::warning
|
||||
Using a custom reverse proxy is an advanced configuration. The default bundled
|
||||
Nginx proxy (Omnibus-based deployments) and Caddy (Docker-based deployments) is
|
||||
suitable for the vast majority of use cases and is recommended for most users.
|
||||
There are important security risks if the reverse proxy is not set up correctly.
|
||||
:::
|
||||
|
||||
For help deploying Firezone with a custom reverse proxy, consider [contacting us
|
||||
for support](https://www.firezone.dev/contact/sales?utm_source=docs.firezone.dev).
|
||||
|
||||
## 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.
|
||||
|
||||
:::note
|
||||
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](/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](/reference/reverse-proxy-templates/apache/)
|
||||
* [Traefik](/reference/reverse-proxy-templates/traefik/)
|
||||
* [HAProxy](/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.
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
title: Configure
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# 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](/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.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="docker" label="Docker" default>
|
||||
|
||||
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](../../reference/env-vars)
|
||||
for a complete listing.
|
||||
|
||||
See [Docker's documentation
|
||||
](https://docs.docker.com/compose/envvars-precedence/) for more information.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="omnibus" label="Omnibus">
|
||||
|
||||
For Omnibus-based deployments, Firezone leverages [Chef Omnibus
|
||||
](https://github.com/chef/omnibus) to handle release packaging, process
|
||||
supervision, log management, and more.
|
||||
|
||||
The main configuration file is written in [Ruby](https://ruby-lang.org) and can
|
||||
be found at `/etc/firezone/firezone.rb` on a default installation.
|
||||
Changing this file **requires re-running** `sudo firezone-ctl reconfigure`
|
||||
which triggers Chef to pick up the changes and apply them to the running
|
||||
system.
|
||||
|
||||
For an exhaustive list of Omnibus configuration variables and their
|
||||
descriptions, see the [configuration file reference
|
||||
](../../reference/configuration-file).
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
@@ -1,165 +0,0 @@
|
||||
---
|
||||
title: Docker
|
||||
sidebar_position: 2
|
||||
description:
|
||||
Install Firezone via Docker to manage secure remote
|
||||
access to private networks and resources.
|
||||
---
|
||||
|
||||
# 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](../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](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.
|
||||
|
||||
:::caution
|
||||
Before deploying Firezone in **production**, you'll need a valid DNS record
|
||||
pointing to this instance. See [Prepare to 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:
|
||||
|
||||
<InstallBlock />
|
||||
|
||||
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**:
|
||||
```
|
||||
curl -fsSL https://raw.githubusercontent.com/firezone/firezone/master/docker-compose.prod.yml -o docker-compose.yml
|
||||
```
|
||||
**For macOS, Windows (non-production only)**:
|
||||
```
|
||||
curl -fsSL https://raw.githubusercontent.com/firezone/firezone/master/docker-compose.desktop.yml -o docker-compose.yml
|
||||
```
|
||||
1. Generate required secrets:
|
||||
```
|
||||
docker run --rm firezone/firezone bin/gen-env > .env
|
||||
```
|
||||
1. At a minimum, change the `ADMIN_EMAIL` and `EXTERNAL_URL` variables.
|
||||
Optionally modify other secrets as needed.
|
||||
1. Migrate the database:
|
||||
```
|
||||
docker compose run --rm firezone bin/migrate
|
||||
```
|
||||
1. Create the first admin:
|
||||
```
|
||||
docker compose run --rm firezone bin/create-or-reset-admin
|
||||
```
|
||||
1. 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:
|
||||
|
||||
```
|
||||
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": "2001: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:
|
||||
```
|
||||
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"
|
||||
```
|
||||
1. Reboot
|
||||
|
||||
You should now be able to ping google from within a docker container:
|
||||
```
|
||||
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
|
||||
|
||||
:::note
|
||||
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](../../user-guides/add-users):
|
||||
Add users to grant them access to your network.
|
||||
* [Client Instructions](../../user-guides/client-instructions):
|
||||
Instructions to establish a VPN session.
|
||||
|
||||
import SupportOptions from '@site/src/partials/_support_options.mdx';
|
||||
<SupportOptions />
|
||||
|
||||
## Post Setup
|
||||
|
||||
Congrats! You have completed the setup, but there's a lot more you can do with
|
||||
Firezone:
|
||||
|
||||
* [Integrate your identity provider](../../authenticate/)
|
||||
for authenticating clients
|
||||
* Using Firezone as a NAT gateway to
|
||||
[establish a static IP for your team](../../user-guides/use-cases/nat-gateway)
|
||||
* Create tunnels between multiple peers with
|
||||
[reverse tunnels](../../user-guides/use-cases/reverse-tunnel)
|
||||
* Only route certain traffic through Firezone with
|
||||
[split tunneling](../../user-guides/use-cases/split-tunnel)
|
||||
@@ -1,33 +0,0 @@
|
||||
---
|
||||
title: Supported Platforms
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
Firezone currently supports the following platforms for Docker-based
|
||||
deployments.
|
||||
|
||||
| OS | Architecture(s) | Runtime | Status | Notes |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Linux | `amd64` `arm64` | Docker Server | **Fully-supported** | `wireguard` kernel module needed for kernels < `5.6`. |
|
||||
| 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.
|
||||
@@ -1,195 +0,0 @@
|
||||
---
|
||||
title: Omnibus
|
||||
sidebar_position: 3
|
||||
description:
|
||||
Install Firezone via our Omnibus deployment option to manage
|
||||
secure access to private networks and resources.
|
||||
---
|
||||
|
||||
# Install Firezone with Omnibus
|
||||
|
||||
:::caution
|
||||
Due to Omnibus being EOL'd by Chef in 2024, Docker is now the preferred method
|
||||
of deploying Firezone. See the [Docker deployment guide](../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
|
||||
](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](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.
|
||||
|
||||
:::caution
|
||||
Before deploying Firezone in **production**, you'll need a valid DNS record
|
||||
pointing to this instance. See [Prepare to Deploy](../#prepare-to-deploy)
|
||||
if you haven't done this already.
|
||||
:::
|
||||
|
||||
:::note
|
||||
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](../../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/master/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.
|
||||
|
||||
|
||||
|
||||
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
|
||||
](../../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
|
||||
](../../administer/troubleshoot).
|
||||
|
||||
## Step 3: Install client apps
|
||||
|
||||
Once successfully deployed, users and devices can be added to
|
||||
connect to the VPN server:
|
||||
|
||||
* [Add Users](../../user-guides/add-users):
|
||||
Add users to grant them access to your network.
|
||||
* [Client Instructions](../../user-guides/client-instructions):
|
||||
Instructions to establish a VPN session.
|
||||
|
||||
import SupportOptions from '@site/src/partials/_support_options.mdx';
|
||||
<SupportOptions />
|
||||
|
||||
## Post setup
|
||||
|
||||
Congrats! You have completed the setup, but there's a lot more you can do with
|
||||
Firezone:
|
||||
|
||||
* [Integrate your identity provider](../../authenticate/)
|
||||
for authenticating clients
|
||||
* Using Firezone to
|
||||
[establish a static IP](../../user-guides/use-cases/nat-gateway)
|
||||
* Create tunnels between multiple peers with
|
||||
[reverse tunnels](../../user-guides/use-cases/reverse-tunnel)
|
||||
* Only route certain traffic through Firezone with
|
||||
[split tunneling](../../user-guides/use-cases/split-tunnel)
|
||||
|
||||
Support us by:
|
||||
|
||||
* Starring our repo on [Github](https://github.com/firezone/firezone)
|
||||
* Following us on Twitter at [@firezonehq](https://twitter.com/firezonehq)
|
||||
* Following us on LinkedIn at [@firezonehq](https://www.linkedin.com/company/firezonehq)
|
||||
@@ -1,121 +0,0 @@
|
||||
---
|
||||
title: Supported Platforms
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
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:
|
||||
|
||||
```shell
|
||||
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:
|
||||
|
||||
```shell
|
||||
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:
|
||||
|
||||
```shell
|
||||
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.
|
||||
|
||||
```shell
|
||||
yum install cronie-anacron
|
||||
```
|
||||
|
||||
## Ubuntu 18.04 notes
|
||||
|
||||
Kernel upgrade to 5.4+ required:
|
||||
|
||||
```shell
|
||||
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:
|
||||
|
||||
```shell
|
||||
sudo zypper install libcap-progs
|
||||
```
|
||||
@@ -1,57 +0,0 @@
|
||||
---
|
||||
title: Security Considerations
|
||||
sidebar_position: 6
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="Docker" value="docker" default>
|
||||
|
||||
| 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. |
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Omnibus" value="omnibus">
|
||||
|
||||
| Service | Port | Listen address | Description |
|
||||
| ------ | --------- | ------- | --------- |
|
||||
| Nginx | `443/tcp` | `all` | Public HTTPS port for administering Firezone and facilitating authentication. |
|
||||
| Nginx | `80/tcp` | `all` | Public HTTP port used for ACME. Disabled when ACME is disabled. |
|
||||
| WireGuard | `51820/udp` | `all` | Public WireGuard port used for VPN sessions. |
|
||||
| Postgresql | `15432/tcp` | `127.0.0.1` | Local-only port used for bundled Postgresql server. |
|
||||
| Phoenix | `13000/tcp` | `127.0.0.1` | Local-only port used by upstream elixir app server. |
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## 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.
|
||||
|
||||
:::caution
|
||||
Ensure you've set up a working [OIDC](/authenticate/oidc/) or [SAML](/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/master/SECURITY.md).
|
||||
@@ -1,11 +0,0 @@
|
||||
---
|
||||
title: Reference
|
||||
sidebar_position: 6
|
||||
---
|
||||
|
||||
```mdx-code-block
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
|
||||
|
||||
<DocCardList items={useCurrentSidebarCategory().items}/>
|
||||
```
|
||||
@@ -1,23 +0,0 @@
|
||||
---
|
||||
title: Audit Logs
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Audit logs
|
||||
|
||||
:::note
|
||||
Audit logs are in early Beta on the Enterprise plan.
|
||||
[Contact us](https://www.firezone.dev/contact/sales?utm_source=docs.firezone.dev)
|
||||
to learn more.
|
||||
:::
|
||||
|
||||
Firezone maintains two types of logs tied to user identity: configuration logs
|
||||
and network activity logs.
|
||||
|
||||
Configuration logs track events related to the configuration of Firezone
|
||||
itself, either by admins or users. Network activity logs track connections to
|
||||
protected resources made by users of your network.
|
||||
|
||||
Logged events are recorded as JSON objects and stored in the database. These
|
||||
are accessible via a REST API or the Firezone portal, and exportable to CSV
|
||||
format.
|
||||
@@ -1,186 +0,0 @@
|
||||
---
|
||||
title: Configuration File
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Omnibus configuration options
|
||||
|
||||
:::warning
|
||||
This reference is written for Omnibus-based deployments of Firezone. For
|
||||
Docker-based deployments visit the [Environment Variables](../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](/deploy/configure).
|
||||
|
||||
## Configuration file reference
|
||||
|
||||
Shown below is a complete listing of the configuration options available in
|
||||
`/etc/firezone/firezone.rb`.
|
||||
|
||||
<!-- markdownlint-disable MD033 -->
|
||||
<!-- markdownlint-disable MD034 -->
|
||||
|
||||
| Option | Description | Default Value |
|
||||
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
|
||||
| `default['firezone']['external_url']` | URL used to access the web portal of this Firezone instance. | <code>"https://#{node['fqdn'] || node['hostname']}"</code> |
|
||||
| `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` |
|
||||
|
||||
<!-- markdownlint-enable MD033 -->
|
||||
<!-- markdownlint-enable MD034 -->
|
||||
@@ -1,64 +0,0 @@
|
||||
---
|
||||
title: Environment Variables
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Docker environment variables
|
||||
|
||||
Most day-to-day config of Firezone can (and should) be done via the
|
||||
Firezone Web UI.
|
||||
|
||||
For Docker-based deployments, deployment-related or infrastructure-related
|
||||
config of Firezone is done through environment variables passed to the
|
||||
Firezone image upon launch.
|
||||
|
||||
Read more about configuring Firezone in our [configure guide](/deploy/configure).
|
||||
|
||||
## Environment Variable Listing
|
||||
|
||||
We recommend setting these in your Docker ENV file (`$HOME/.firezone/.env` by
|
||||
default). Required fields in **bold**.
|
||||
|
||||
| Name | Description | Format | Default |
|
||||
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
|
||||
| **`EXTERNAL_URL`** | The external URL the web UI will be accessible at. Must be a valid FQDN for ACME SSL issuance to function. | String | |
|
||||
| **`ADMIN_EMAIL`** | Primary administrator email. | String | |
|
||||
| **`DEFAULT_ADMIN_PASSWORD`** | Default password that will be used for creating or resetting the primary administrator account. | String | Randomly generated upon install with `docker run firezone/firezone bin/gen-env`. |
|
||||
| **`DATABASE_PASSWORD`** | Password used to connect to the DB. | String | Randomly generated upon install with `docker run firezone/firezone bin/gen-env`. |
|
||||
| **`DATABASE_ENCRYPTION_KEY`** | The base64-encoded symmetric encryption key used to encrypt and decrypt sensitive fields. | base64-encoded String | Randomly generated upon install with `docker run firezone/firezone bin/gen-env`. |
|
||||
| **`GUARDIAN_SECRET_KEY`** | Secret key used for signing JWTs. | base64-encoded String | Randomly generated upon install with `docker run firezone/firezone bin/gen-env`. |
|
||||
| **`COOKIE_ENCRYPTION_SALT`** | Encryption salt for cookies issued by the Phoenix web application. | base64-encoded String | Randomly generated upon install with `docker run firezone/firezone bin/gen-env`. |
|
||||
| **`COOKIE_SIGNING_SALT`** | Signing salt for cookies issued by the Phoenix web application. | base64-encoded String | Randomly generated upon install with `docker run firezone/firezone bin/gen-env`. |
|
||||
| **`LIVE_VIEW_SIGNING_SALT`** | Signing salt for Phoenix LiveView connection tokens. | base64-encoded String | Randomly generated upon install with `docker run firezone/firezone bin/gen-env`. |
|
||||
| **`SECRET_KEY_BASE`** | Primary secret key base for the Phoenix application. | base64-encoded String | Randomly generated upon install with `docker run firezone/firezone bin/gen-env`. |
|
||||
| `RESET_ADMIN_ON_BOOT` | Set this variable to `true` to create or reset the admin with email specified by `ADMIM_EMAIL` to password `DEFAULT_ADMIN_PASSWORD` on boot. Note: This **will not** change the status of local authentication. | Boolean | |
|
||||
| `LOCAL_AUTH_ENABLED` | Enable or disable the local authentication method for all users. | Boolean | `true` |
|
||||
| `SAML_ENTITY_ID` | SAML Entity ID. | String | `urn:firezone.dev:firezone-app` |
|
||||
| `SAML_KEYFILE_PATH` | Path to the SAML keyfile inside the container. | String | `/var/firezone/saml.key` |
|
||||
| `SAML_CERTFILE_PATH` | Path to the SAML certificate file inside the container. | String | `/var/firezone/saml.crt` |
|
||||
| `DATABASE_HOST` | Database host. | IP or hostname | `postgres` |
|
||||
| `DATABASE_PORT` | Database port. | Integer | `5432` |
|
||||
| `DATABASE_NAME` | Name of database. | String | `firezone` |
|
||||
| `DATABASE_USER` | Database user. | 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 | `{}` |
|
||||
| `HTTP_CLIENT_SSL_OPTS` | Map of options to use for outbound SSL connections for OIDC document retrieval and Connectivity Checks. | JSON-encoded String, e.g. `{"verify": "verify_none", "cacertfile": "/etc/ssl/cacerts.pem"}`. See [Erlang's SSL options](https://www.erlang.org/doc/man/ssl.html#type-client_option) for a full list of client options. | |
|
||||
| `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 | `3600` |
|
||||
| `EXTERNAL_TRUSTED_PROXIES` | List of trusted reverse proxies. | JSON-encoded array | `[]` |
|
||||
| `MAX_DEVICES_PER_USER` | Maximum number of devices to allow per user. | Integer | `10` |
|
||||
| `OUTBOUND_EMAIL_FROM` | From address to use for sending outbound emails. If not set, sending email will be disabled (default). | String | |
|
||||
| `OUTBOUND_EMAIL_PROVIDER` | Method to use for sending outbound email. If not set, will default to `sendmail`. See the list of [Swoosh Adapters](https://github.com/swoosh/swoosh#adapters). | String | |
|
||||
| `OUTBOUND_EMAIL_CONFIGS` | Email provider-specific config. | JSON-encoded String E.g. `{"gmail": {"access_token": "..."}, "smtp": {"relay": "smtp.example.com"}}`. See the [swoosh docs](https://hexdocs.pm/swoosh/). | `{}` |
|
||||
| `PHOENIX_PORT` | Internal port to listen on for the Phoenix web server. | Integer | `13000` |
|
||||
| `PRIVATE_CLIENTS` | List of IPs / CIDRs to consider trusted for purposes of correctly parsing the `X-Forwarded-For` header. | JSON-encoded list of IPs / CIDRs. | `[]` |
|
||||
| `WIREGUARD_IPV4_ENABLED` | Enable / disable tunnel-side IPv4 connectivity. | Boolean | `true` |
|
||||
| `WIREGUARD_IPV4_MASQUERADE` | Enable / disable IPv4 masquerade. | String | `true` |
|
||||
| `WIREGUARD_IPV6_ENABLED` | Enable / disable tunnel IPv6 addresses. | Boolean | `true` |
|
||||
| `WIREGUARD_IPV6_MASQUERADE` | Enable / disable IPv6 masquerade. | Boolean | `true` |
|
||||
| `WIREGUARD_MTU` | MTU to use for the server-side WireGuard MTU interface. | String | `1280` |
|
||||
| `WIREGUARD_PORT` | Port to listen on for WireGuard connections. | Integer | `51820` |
|
||||
| `SECURE_COOKIES` | Enable or disable requiring secure cookies. Required for HTTPS. | Boolean | `true` |
|
||||
| `TELEMETRY_ENABLED` | Enable / disable product telemetry. Read more about [what that means here](/reference/telemetry). | Boolean | `true` |
|
||||
@@ -1,37 +0,0 @@
|
||||
---
|
||||
title: File and Directory Locations
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="Docker" value="docker" default>
|
||||
|
||||
| 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. |
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Omnibus" value="omnibus">
|
||||
|
||||
| Path | Description |
|
||||
| --- | --- |
|
||||
| `/var/opt/firezone` | Top-level directory containing data and generated configuration for Firezone bundled services. |
|
||||
| `/opt/firezone` | Top-level directory containing built libraries, binaries and runtime files needed by Firezone. |
|
||||
| `/usr/bin/firezone-ctl` | `firezone-ctl` utility for managing your Firezone installation. |
|
||||
| `/etc/systemd/system/firezone-runsvdir-start.service` | systemd unit file for starting the Firezone runsvdir supervisor process. |
|
||||
| `/etc/firezone` | Firezone configuration files. |
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Backup and restore
|
||||
|
||||
See our [backup guide](/administer/backup).
|
||||
@@ -1,15 +0,0 @@
|
||||
---
|
||||
title: Firewall Templates
|
||||
sidebar_position: 9
|
||||
---
|
||||
|
||||
Firewall templates to secure the Firezone server itself are available from here.
|
||||
If the server is not running any services other than Firezone, the firewall
|
||||
template should work as-is.
|
||||
|
||||
```mdx-code-block
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
|
||||
|
||||
<DocCardList items={useCurrentSidebarCategory().items}/>
|
||||
```
|
||||
@@ -1,339 +0,0 @@
|
||||
---
|
||||
title: nftables Firewall Template
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
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:
|
||||
|
||||
```shell
|
||||
firezone-ctl restart phoenix
|
||||
```
|
||||
|
||||
## Base firewall template
|
||||
|
||||
```shell
|
||||
#!/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:
|
||||
|
||||
```shell
|
||||
systemctl enable nftables.service
|
||||
```
|
||||
|
||||
If making any changes to the firewall template the syntax can be validated by running
|
||||
the check command:
|
||||
|
||||
```shell
|
||||
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.
|
||||
@@ -1,35 +0,0 @@
|
||||
---
|
||||
title: REST API
|
||||
sidebar_position: 10
|
||||
---
|
||||
|
||||
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:
|
||||
|
||||
```shell
|
||||
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:
|
||||
|
||||
```shell
|
||||
docker compose -f $HOME/.firezone/docker-compose.yml exec firezone bin/create-api-token > fz_token
|
||||
```
|
||||
|
||||
:::caution
|
||||
API tokens generated from the CLI are owned by the primary administrator specified by
|
||||
the `ADMIN_EMAIL` environment variable.
|
||||
:::
|
||||
|
||||
```mdx-code-block
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
|
||||
|
||||
<DocCardList items={useCurrentSidebarCategory().items}/>
|
||||
```
|
||||
@@ -1,145 +0,0 @@
|
||||
---
|
||||
title: Configurations
|
||||
group: Configuration
|
||||
---
|
||||
|
||||
|
||||
This endpoint allows an administrator to manage Configurations.
|
||||
|
||||
## 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": "8f17e873-de8a-4264-8567-39e450870306",
|
||||
"inserted_at": "2023-01-13T06:00:43.178729Z",
|
||||
"local_auth_enabled": true,
|
||||
"logo": null,
|
||||
"openid_connect_providers": [],
|
||||
"saml_identity_providers": [],
|
||||
"updated_at": "2023-01-13T06:00:43.178729Z",
|
||||
"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": "response-type",
|
||||
"scope": "test-scope"
|
||||
}
|
||||
],
|
||||
"saml_identity_providers": [
|
||||
{
|
||||
"auto_create_users": false,
|
||||
"base_url": "https://saml",
|
||||
"id": "okta",
|
||||
"label": "okta",
|
||||
"metadata": "<?xml version=\"1.0\"?>\n<md:EntityDescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" xmlns:md=\"urn:oasis:names:tc:SAML:2.0:metadata\" xmlns:saml=\"urn:oasis:names:tc:SAML:2.0:assertion\" xmlns:ds=\"http://www.w3.org/2000/09/xmldsig#\" entityID=\"http://localhost:8080/realms/firezone\">\n <md:IDPSSODescriptor WantAuthnRequestsSigned=\"true\" protocolSupportEnumeration=\"urn:oasis:names:tc:SAML:2.0:protocol\">\n <md:KeyDescriptor use=\"signing\">\n <ds:KeyInfo>\n <ds:KeyName>pdSMtx2s3RVVhxg_qJOjHhlZhwZk6JiBMiSm5PEgjkA</ds:KeyName>\n <ds:X509Data>\n <ds:X509Certificate>MIICnzCCAYcCBgGD18ZU8TANBgkqhkiG9w0BAQsFADATMREwDwYDVQQDDAhmaXJlem9uZTAeFw0yMjEwMTQxODMyMjJaFw0zMjEwMTQxODM0MDJaMBMxETAPBgNVBAMMCGZpcmV6b25lMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAur5Cb0jrDJbMwr96WWE+z9CjDg0A/uRkaB4loRqkmu3A2fQGsS6CP7F7lQWMJmpzvBgkNtB69toO2sgx1u1fhpIJBZ0uSHF5gnzQAivgVxInvkMKRTRSkpMbhObiDHZnEGI2+Ly+8iV8IvprdrbDgm52u4conam0H1PewUKkHulrVQ+ImFuEWAjKCRSqpUG2F1eRkA0YpqB09x0CZAOOoucwTsBYj/ZAz3dUXhYIENAF7v0ykvzGOCAyOZIn1uYQc7jvWpwoI8qQdL45phj2FLoFlght3tlZV8IG5hsXrE6rg7Ufqvv8xyGltrOMKj/jEFEunagZOUjkypDp36b8cwIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQBEZKLLr66GB3NxqXGTMl0PvTDNB9GdyShQHaJYjeeUQnEXixjlAVrOq/txEBKjhGUcqyFELoNuwcxxV1iHA5oXhCoqYmnp9T/ftmXPDT3c49PBABHgLJaFOKYTpVx1YjP7mA44X1ijLZmgboIeeFNerVNHIzR9BsxcloQlB0r9QfC14rsuXo6QD3QnaVI8wDgWXQHqpcwLFqvehXdNvMFniRvX2qBNU8E0FPoMaZ1C3n2nssLcVZ+C4ghq6YoAG+wLGY7XE8+v5rnYGDpGpfgr2wdefn6tryFq3PyGqA8ThjARESRRQG9kI/RlNX7qCnP/8/7JQ4wLdfz5C25uhakP</ds:X509Certificate>\n </ds:X509Data>\n </ds:KeyInfo>\n </md:KeyDescriptor>\n <md:ArtifactResolutionService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:SOAP\" Location=\"http://localhost:8080/realms/firezone/protocol/saml/resolve\" index=\"0\"/>\n <md:SingleLogoutService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\" Location=\"http://localhost:8080/realms/firezone/protocol/saml\"/>\n <md:SingleLogoutService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\" Location=\"http://localhost:8080/realms/firezone/protocol/saml\"/>\n <md:SingleLogoutService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact\" Location=\"http://localhost:8080/realms/firezone/protocol/saml\"/>\n <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat>\n <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>\n <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>\n <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>\n <md:SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\" Location=\"http://localhost:8080/realms/firezone/protocol/saml\"/>\n <md:SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\" Location=\"http://localhost:8080/realms/firezone/protocol/saml\"/>\n <md:SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:SOAP\" Location=\"http://localhost:8080/realms/firezone/protocol/saml\"/>\n <md:SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact\" Location=\"http://localhost:8080/realms/firezone/protocol/saml\"/>\n </md:IDPSSODescriptor>\n</md:EntityDescriptor>\n",
|
||||
"sign_metadata": false,
|
||||
"sign_requests": false,
|
||||
"signed_assertion_in_resp": false,
|
||||
"signed_envelopes_in_resp": false
|
||||
}
|
||||
],
|
||||
"vpn_session_duration": 100
|
||||
}
|
||||
}'
|
||||
EOF
|
||||
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json; charset=utf-8
|
||||
|
||||
{
|
||||
"data": {
|
||||
"allow_unprivileged_device_configuration": false,
|
||||
"allow_unprivileged_device_management": false,
|
||||
"default_client_allowed_ips": "1.1.1.1,2.2.2.2",
|
||||
"default_client_dns": "1.1.1.1",
|
||||
"default_client_endpoint": "new-endpoint",
|
||||
"default_client_mtu": 1100,
|
||||
"default_client_persistent_keepalive": 1,
|
||||
"disable_vpn_on_oidc_error": true,
|
||||
"id": "8f17e873-de8a-4264-8567-39e450870306",
|
||||
"inserted_at": "2023-01-13T06:00:43.178729Z",
|
||||
"local_auth_enabled": false,
|
||||
"logo": null,
|
||||
"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": "response-type",
|
||||
"scope": "test-scope"
|
||||
}
|
||||
],
|
||||
"saml_identity_providers": [
|
||||
{
|
||||
"auto_create_users": false,
|
||||
"base_url": "https://saml",
|
||||
"id": "okta",
|
||||
"label": "okta",
|
||||
"metadata": "<?xml version=\"1.0\"?>\n<md:EntityDescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" xmlns:md=\"urn:oasis:names:tc:SAML:2.0:metadata\" xmlns:saml=\"urn:oasis:names:tc:SAML:2.0:assertion\" xmlns:ds=\"http://www.w3.org/2000/09/xmldsig#\" entityID=\"http://localhost:8080/realms/firezone\">\n <md:IDPSSODescriptor WantAuthnRequestsSigned=\"true\" protocolSupportEnumeration=\"urn:oasis:names:tc:SAML:2.0:protocol\">\n <md:KeyDescriptor use=\"signing\">\n <ds:KeyInfo>\n <ds:KeyName>pdSMtx2s3RVVhxg_qJOjHhlZhwZk6JiBMiSm5PEgjkA</ds:KeyName>\n <ds:X509Data>\n <ds:X509Certificate>MIICnzCCAYcCBgGD18ZU8TANBgkqhkiG9w0BAQsFADATMREwDwYDVQQDDAhmaXJlem9uZTAeFw0yMjEwMTQxODMyMjJaFw0zMjEwMTQxODM0MDJaMBMxETAPBgNVBAMMCGZpcmV6b25lMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAur5Cb0jrDJbMwr96WWE+z9CjDg0A/uRkaB4loRqkmu3A2fQGsS6CP7F7lQWMJmpzvBgkNtB69toO2sgx1u1fhpIJBZ0uSHF5gnzQAivgVxInvkMKRTRSkpMbhObiDHZnEGI2+Ly+8iV8IvprdrbDgm52u4conam0H1PewUKkHulrVQ+ImFuEWAjKCRSqpUG2F1eRkA0YpqB09x0CZAOOoucwTsBYj/ZAz3dUXhYIENAF7v0ykvzGOCAyOZIn1uYQc7jvWpwoI8qQdL45phj2FLoFlght3tlZV8IG5hsXrE6rg7Ufqvv8xyGltrOMKj/jEFEunagZOUjkypDp36b8cwIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQBEZKLLr66GB3NxqXGTMl0PvTDNB9GdyShQHaJYjeeUQnEXixjlAVrOq/txEBKjhGUcqyFELoNuwcxxV1iHA5oXhCoqYmnp9T/ftmXPDT3c49PBABHgLJaFOKYTpVx1YjP7mA44X1ijLZmgboIeeFNerVNHIzR9BsxcloQlB0r9QfC14rsuXo6QD3QnaVI8wDgWXQHqpcwLFqvehXdNvMFniRvX2qBNU8E0FPoMaZ1C3n2nssLcVZ+C4ghq6YoAG+wLGY7XE8+v5rnYGDpGpfgr2wdefn6tryFq3PyGqA8ThjARESRRQG9kI/RlNX7qCnP/8/7JQ4wLdfz5C25uhakP</ds:X509Certificate>\n </ds:X509Data>\n </ds:KeyInfo>\n </md:KeyDescriptor>\n <md:ArtifactResolutionService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:SOAP\" Location=\"http://localhost:8080/realms/firezone/protocol/saml/resolve\" index=\"0\"/>\n <md:SingleLogoutService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\" Location=\"http://localhost:8080/realms/firezone/protocol/saml\"/>\n <md:SingleLogoutService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\" Location=\"http://localhost:8080/realms/firezone/protocol/saml\"/>\n <md:SingleLogoutService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact\" Location=\"http://localhost:8080/realms/firezone/protocol/saml\"/>\n <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat>\n <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>\n <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>\n <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>\n <md:SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\" Location=\"http://localhost:8080/realms/firezone/protocol/saml\"/>\n <md:SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\" Location=\"http://localhost:8080/realms/firezone/protocol/saml\"/>\n <md:SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:SOAP\" Location=\"http://localhost:8080/realms/firezone/protocol/saml\"/>\n <md:SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact\" Location=\"http://localhost:8080/realms/firezone/protocol/saml\"/>\n </md:IDPSSODescriptor>\n</md:EntityDescriptor>\n",
|
||||
"sign_metadata": false,
|
||||
"sign_requests": false,
|
||||
"signed_assertion_in_resp": false,
|
||||
"signed_envelopes_in_resp": false
|
||||
}
|
||||
],
|
||||
"updated_at": "2023-01-13T06:30:47.529652Z",
|
||||
"vpn_session_duration": 100
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -1,363 +0,0 @@
|
||||
---
|
||||
title: Devices
|
||||
group: 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": "9fc9b189-b740-4676-a7c2-c135b97d951d",
|
||||
"inserted_at": "2023-01-13T06:30:47.092141Z",
|
||||
"ipv4": "100.99.95.137",
|
||||
"ipv6": "fd00::2a:3f6d",
|
||||
"latest_handshake": null,
|
||||
"mtu": 1280,
|
||||
"name": "factory 3175",
|
||||
"persistent_keepalive": 25,
|
||||
"preshared_key": "Fj2iQKy5R5lLi8GIMI96FIfgWs/8saEYj4q6mLtgpg8=",
|
||||
"public_key": "cVAdAno+PbyPBg5ubwxPe86QahSZ3AwhsKHfkFNw0nc=",
|
||||
"remote_ip": null,
|
||||
"rx_bytes": null,
|
||||
"server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=",
|
||||
"tx_bytes": null,
|
||||
"updated_at": "2023-01-13T06:30:47.092141Z",
|
||||
"use_default_allowed_ips": true,
|
||||
"use_default_dns": true,
|
||||
"use_default_endpoint": true,
|
||||
"use_default_mtu": true,
|
||||
"use_default_persistent_keepalive": true,
|
||||
"user_id": "4b195eb9-d675-4143-8de0-64e68c5a6d86"
|
||||
},
|
||||
{
|
||||
"allowed_ips": "0.0.0.0/0,::/0",
|
||||
"description": "factory description",
|
||||
"dns": "1.1.1.1,1.0.0.1",
|
||||
"endpoint": "localhost:51820",
|
||||
"id": "85243eb4-8c30-4bce-bb40-b4b9650e7ffa",
|
||||
"inserted_at": "2023-01-13T06:30:47.101527Z",
|
||||
"ipv4": "100.106.156.151",
|
||||
"ipv6": "fd00::3e:876d",
|
||||
"latest_handshake": null,
|
||||
"mtu": 1280,
|
||||
"name": "factory 2820",
|
||||
"persistent_keepalive": 25,
|
||||
"preshared_key": "NXiX1/xSyDfEl+S3O7VaaVTJKUu2kZo91pCycuZG3mk=",
|
||||
"public_key": "e8e8+NBCAyHPycu2VJIRK9NQCR5Bz5Oo6aFbuOmUMhc=",
|
||||
"remote_ip": null,
|
||||
"rx_bytes": null,
|
||||
"server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=",
|
||||
"tx_bytes": null,
|
||||
"updated_at": "2023-01-13T06:30:47.101527Z",
|
||||
"use_default_allowed_ips": true,
|
||||
"use_default_dns": true,
|
||||
"use_default_endpoint": true,
|
||||
"use_default_mtu": true,
|
||||
"use_default_persistent_keepalive": true,
|
||||
"user_id": "1949803a-bb74-429c-ac99-fae4ce09ca08"
|
||||
},
|
||||
{
|
||||
"allowed_ips": "0.0.0.0/0,::/0",
|
||||
"description": "factory description",
|
||||
"dns": "1.1.1.1,1.0.0.1",
|
||||
"endpoint": "localhost:51820",
|
||||
"id": "7898b569-7c59-4596-b002-e1717c6fe5df",
|
||||
"inserted_at": "2023-01-13T06:30:47.108829Z",
|
||||
"ipv4": "100.120.62.86",
|
||||
"ipv6": "fd00::38:7ee5",
|
||||
"latest_handshake": null,
|
||||
"mtu": 1280,
|
||||
"name": "factory 2978",
|
||||
"persistent_keepalive": 25,
|
||||
"preshared_key": "i6kyqjysbWGEWMO9FNUDMxE1OhrYJsgjuIfgnJNApyE=",
|
||||
"public_key": "ulryM87WfDob8foWZtIiaW+cH+ugh4t/31vSO2YNRtA=",
|
||||
"remote_ip": null,
|
||||
"rx_bytes": null,
|
||||
"server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=",
|
||||
"tx_bytes": null,
|
||||
"updated_at": "2023-01-13T06:30:47.108829Z",
|
||||
"use_default_allowed_ips": true,
|
||||
"use_default_dns": true,
|
||||
"use_default_endpoint": true,
|
||||
"use_default_mtu": true,
|
||||
"use_default_persistent_keepalive": true,
|
||||
"user_id": "a1ebe3b2-3843-47ee-baf4-077740bfcd35"
|
||||
},
|
||||
{
|
||||
"allowed_ips": "0.0.0.0/0,::/0",
|
||||
"description": "factory description",
|
||||
"dns": "1.1.1.1,1.0.0.1",
|
||||
"endpoint": "localhost:51820",
|
||||
"id": "3113df9e-29a4-4062-8a7d-7bf67612c61c",
|
||||
"inserted_at": "2023-01-13T06:30:47.115812Z",
|
||||
"ipv4": "100.64.196.12",
|
||||
"ipv6": "fd00::1e:b441",
|
||||
"latest_handshake": null,
|
||||
"mtu": 1280,
|
||||
"name": "factory 1577",
|
||||
"persistent_keepalive": 25,
|
||||
"preshared_key": "oZsi27RP/myoPFDTdxv29KVAxb2D1PTN+ojhUHsuM9I=",
|
||||
"public_key": "ZZrmY3JKOLJc9JZO+JTBJ9toM+x3hZBikcEAAxhdnWY=",
|
||||
"remote_ip": null,
|
||||
"rx_bytes": null,
|
||||
"server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=",
|
||||
"tx_bytes": null,
|
||||
"updated_at": "2023-01-13T06:30:47.115812Z",
|
||||
"use_default_allowed_ips": true,
|
||||
"use_default_dns": true,
|
||||
"use_default_endpoint": true,
|
||||
"use_default_mtu": true,
|
||||
"use_default_persistent_keepalive": true,
|
||||
"user_id": "634c7a8b-95c3-4c2f-9566-78be4d768cde"
|
||||
},
|
||||
{
|
||||
"allowed_ips": "0.0.0.0/0,::/0",
|
||||
"description": "factory description",
|
||||
"dns": "1.1.1.1,1.0.0.1",
|
||||
"endpoint": "localhost:51820",
|
||||
"id": "44c8dd33-ad63-47cf-93ae-ff5ffcb16f52",
|
||||
"inserted_at": "2023-01-13T06:30:47.123039Z",
|
||||
"ipv4": "100.93.227.124",
|
||||
"ipv6": "fd00::3:b1dd",
|
||||
"latest_handshake": null,
|
||||
"mtu": 1280,
|
||||
"name": "factory 1673",
|
||||
"persistent_keepalive": 25,
|
||||
"preshared_key": "G0XAE7HCOArcB+RH09g/HIsDJM3SfYk9WKa1WYo6hv4=",
|
||||
"public_key": "RBr9GYzFGuoltoIt2iTeqSb0CHaiPAcwxxxxSYlX4tg=",
|
||||
"remote_ip": null,
|
||||
"rx_bytes": null,
|
||||
"server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=",
|
||||
"tx_bytes": null,
|
||||
"updated_at": "2023-01-13T06:30:47.123039Z",
|
||||
"use_default_allowed_ips": true,
|
||||
"use_default_dns": true,
|
||||
"use_default_endpoint": true,
|
||||
"use_default_mtu": true,
|
||||
"use_default_persistent_keepalive": true,
|
||||
"user_id": "b61a4d7a-34a6-4d37-9871-a024fb97fe60"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
### 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": "57afecab-c92c-45b8-8764-017a7cb5276b"
|
||||
}
|
||||
}'
|
||||
EOF
|
||||
|
||||
HTTP/1.1 201
|
||||
Content-Type: application/json; charset=utf-8
|
||||
Location: /v0/devices/0f71030e-b872-494f-af2b-c31730f119e0
|
||||
|
||||
{
|
||||
"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": "0f71030e-b872-494f-af2b-c31730f119e0",
|
||||
"inserted_at": "2023-01-13T06:30:47.204640Z",
|
||||
"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-01-13T06:30:47.204640Z",
|
||||
"use_default_allowed_ips": false,
|
||||
"use_default_dns": false,
|
||||
"use_default_endpoint": false,
|
||||
"use_default_mtu": false,
|
||||
"use_default_persistent_keepalive": false,
|
||||
"user_id": "57afecab-c92c-45b8-8764-017a7cb5276b"
|
||||
}
|
||||
}
|
||||
```
|
||||
### GET /v0/devices/{id}
|
||||
|
||||
|
||||
|
||||
#### Example
|
||||
**URI Parameters:**
|
||||
|
||||
- `id`: `904fbe05-86a5-4edb-afb2-6b728755a210`
|
||||
```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": "904fbe05-86a5-4edb-afb2-6b728755a210",
|
||||
"inserted_at": "2023-01-13T06:30:47.048145Z",
|
||||
"ipv4": "100.74.213.26",
|
||||
"ipv6": "fd00::5:110a",
|
||||
"latest_handshake": null,
|
||||
"mtu": 1280,
|
||||
"name": "factory 2403",
|
||||
"persistent_keepalive": 25,
|
||||
"preshared_key": "fue0i7cIahPPlWr6UCSerJNu3NRDrETv3YW+Xjc3qU4=",
|
||||
"public_key": "6KYOCkP8off66kidQOXpwQlwKix8ELfXm/kR5cwsnug=",
|
||||
"remote_ip": null,
|
||||
"rx_bytes": null,
|
||||
"server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=",
|
||||
"tx_bytes": null,
|
||||
"updated_at": "2023-01-13T06:30:47.048145Z",
|
||||
"use_default_allowed_ips": true,
|
||||
"use_default_dns": true,
|
||||
"use_default_endpoint": true,
|
||||
"use_default_mtu": true,
|
||||
"use_default_persistent_keepalive": true,
|
||||
"user_id": "bc22e5c4-853c-4e0d-bf93-85111707e66f"
|
||||
}
|
||||
}
|
||||
```
|
||||
### PATCH /v0/devices/{id}
|
||||
|
||||
|
||||
|
||||
#### Example
|
||||
**URI Parameters:**
|
||||
|
||||
- `id`: `ef1da923-caf4-47f3-ab6a-7ab0908d7f0e`
|
||||
```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": "ef1da923-caf4-47f3-ab6a-7ab0908d7f0e",
|
||||
"inserted_at": "2023-01-13T06:30:47.264719Z",
|
||||
"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-01-13T06:30:47.279141Z",
|
||||
"use_default_allowed_ips": false,
|
||||
"use_default_dns": false,
|
||||
"use_default_endpoint": false,
|
||||
"use_default_mtu": false,
|
||||
"use_default_persistent_keepalive": false,
|
||||
"user_id": "ae05e328-3a67-4101-9d6b-48dcd9cdddf8"
|
||||
}
|
||||
}
|
||||
```
|
||||
### DELETE /v0/devices/{id}
|
||||
|
||||
|
||||
|
||||
#### Example
|
||||
**URI Parameters:**
|
||||
|
||||
- `id`: `5b8cf677-ae60-4eca-b038-9abcd410904f`
|
||||
```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
|
||||
```
|
||||
@@ -1,203 +0,0 @@
|
||||
---
|
||||
title: Rules
|
||||
group: 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": "fdcf2ca8-1871-4aac-bc01-591b3e18578e",
|
||||
"inserted_at": "2023-01-13T06:30:46.079209Z",
|
||||
"port_range": null,
|
||||
"port_type": null,
|
||||
"updated_at": "2023-01-13T06:30:46.079209Z",
|
||||
"user_id": null
|
||||
},
|
||||
{
|
||||
"action": "drop",
|
||||
"destination": "10.3.2.2",
|
||||
"id": "2e544ab0-0ca5-432e-9a31-b5feb982f50a",
|
||||
"inserted_at": "2023-01-13T06:30:46.087033Z",
|
||||
"port_range": null,
|
||||
"port_type": null,
|
||||
"updated_at": "2023-01-13T06:30:46.087033Z",
|
||||
"user_id": null
|
||||
},
|
||||
{
|
||||
"action": "drop",
|
||||
"destination": "10.3.2.3",
|
||||
"id": "02df6455-65f1-406b-a3dd-7c223af04f9b",
|
||||
"inserted_at": "2023-01-13T06:30:46.088443Z",
|
||||
"port_range": null,
|
||||
"port_type": null,
|
||||
"updated_at": "2023-01-13T06:30:46.088443Z",
|
||||
"user_id": null
|
||||
},
|
||||
{
|
||||
"action": "drop",
|
||||
"destination": "10.3.2.4",
|
||||
"id": "e0c4e652-e3a2-4a69-a8f3-265e07515938",
|
||||
"inserted_at": "2023-01-13T06:30:46.090111Z",
|
||||
"port_range": null,
|
||||
"port_type": null,
|
||||
"updated_at": "2023-01-13T06:30:46.090111Z",
|
||||
"user_id": null
|
||||
},
|
||||
{
|
||||
"action": "drop",
|
||||
"destination": "10.3.2.5",
|
||||
"id": "a7c2bfb2-3e09-48d8-b038-c69c84b777b1",
|
||||
"inserted_at": "2023-01-13T06:30:46.091623Z",
|
||||
"port_range": null,
|
||||
"port_type": null,
|
||||
"updated_at": "2023-01-13T06:30:46.091623Z",
|
||||
"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": "9f4d207a-90d8-4cc9-800c-accefe9f90cf"
|
||||
}
|
||||
}'
|
||||
EOF
|
||||
|
||||
HTTP/1.1 201
|
||||
Content-Type: application/json; charset=utf-8
|
||||
Location: /v0/rules/cc374f84-b003-4858-8772-516ea3f098a1
|
||||
|
||||
{
|
||||
"data": {
|
||||
"action": "accept",
|
||||
"destination": "1.1.1.1/24",
|
||||
"id": "cc374f84-b003-4858-8772-516ea3f098a1",
|
||||
"inserted_at": "2023-01-13T06:30:47.193190Z",
|
||||
"port_range": "1 - 2",
|
||||
"port_type": "udp",
|
||||
"updated_at": "2023-01-13T06:30:47.193190Z",
|
||||
"user_id": "9f4d207a-90d8-4cc9-800c-accefe9f90cf"
|
||||
}
|
||||
}
|
||||
```
|
||||
### GET /v0/rules/{id}
|
||||
|
||||
|
||||
|
||||
#### Example
|
||||
**URI Parameters:**
|
||||
|
||||
- `id`: `49a9ae27-74f2-45dd-a324-d47a7581205c`
|
||||
```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": "49a9ae27-74f2-45dd-a324-d47a7581205c",
|
||||
"inserted_at": "2023-01-13T06:30:46.993421Z",
|
||||
"port_range": null,
|
||||
"port_type": null,
|
||||
"updated_at": "2023-01-13T06:30:46.993421Z",
|
||||
"user_id": null
|
||||
}
|
||||
}
|
||||
```
|
||||
### PATCH /v0/rules/{id}
|
||||
|
||||
|
||||
|
||||
#### Example
|
||||
**URI Parameters:**
|
||||
|
||||
- `id`: `b8231fa6-1df2-4b1b-8687-61a72a8031b1`
|
||||
```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": "b8231fa6-1df2-4b1b-8687-61a72a8031b1",
|
||||
"inserted_at": "2023-01-13T06:30:47.244050Z",
|
||||
"port_range": "1 - 2",
|
||||
"port_type": "udp",
|
||||
"updated_at": "2023-01-13T06:30:47.254788Z",
|
||||
"user_id": null
|
||||
}
|
||||
}
|
||||
```
|
||||
### DELETE /v0/rules/{id}
|
||||
|
||||
|
||||
|
||||
#### Example
|
||||
**URI Parameters:**
|
||||
|
||||
- `id`: `05c0342c-984c-43df-855b-32e88ea8ee08`
|
||||
```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
|
||||
```
|
||||
@@ -1,354 +0,0 @@
|
||||
---
|
||||
title: Users
|
||||
sidebar_position: 2
|
||||
toc_max_heading_level: 4
|
||||
---
|
||||
|
||||
|
||||
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.
|
||||
|
||||
## 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-2886@test",
|
||||
"id": "9f0ce70d-d9e6-4610-ad3b-e5758318c016",
|
||||
"inserted_at": "2023-01-13T06:30:47.076850Z",
|
||||
"last_signed_in_at": null,
|
||||
"last_signed_in_method": null,
|
||||
"role": "admin",
|
||||
"updated_at": "2023-01-13T06:30:47.076850Z"
|
||||
},
|
||||
{
|
||||
"disabled_at": null,
|
||||
"email": "test-2918@test",
|
||||
"id": "36479416-7099-46f9-b9b9-3ad4411eef7d",
|
||||
"inserted_at": "2023-01-13T06:30:47.079115Z",
|
||||
"last_signed_in_at": null,
|
||||
"last_signed_in_method": null,
|
||||
"role": "admin",
|
||||
"updated_at": "2023-01-13T06:30:47.079115Z"
|
||||
},
|
||||
{
|
||||
"disabled_at": null,
|
||||
"email": "test-3045@test",
|
||||
"id": "232c2358-5132-4fc7-8e42-cd8464fcae02",
|
||||
"inserted_at": "2023-01-13T06:30:47.081138Z",
|
||||
"last_signed_in_at": null,
|
||||
"last_signed_in_method": null,
|
||||
"role": "admin",
|
||||
"updated_at": "2023-01-13T06:30:47.081138Z"
|
||||
},
|
||||
{
|
||||
"disabled_at": null,
|
||||
"email": "test-2950@test",
|
||||
"id": "b15b274b-751e-4ca6-9c3e-3a798299ec86",
|
||||
"inserted_at": "2023-01-13T06:30:47.083059Z",
|
||||
"last_signed_in_at": null,
|
||||
"last_signed_in_method": null,
|
||||
"role": "admin",
|
||||
"updated_at": "2023-01-13T06:30:47.083059Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
### Create a User [`POST /v0/users`]
|
||||
|
||||
|
||||
Create a new User.
|
||||
|
||||
This endpoint is useful in two cases:
|
||||
|
||||
1. When [Local Authentication](/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/86616e3e-13f0-4177-bc8e-1a0e588f0be8
|
||||
|
||||
{
|
||||
"data": {
|
||||
"disabled_at": null,
|
||||
"email": "new-user@test",
|
||||
"id": "86616e3e-13f0-4177-bc8e-1a0e588f0be8",
|
||||
"inserted_at": "2023-01-13T06:30:47.047550Z",
|
||||
"last_signed_in_at": null,
|
||||
"last_signed_in_method": null,
|
||||
"role": "unprivileged",
|
||||
"updated_at": "2023-01-13T06:30:47.047550Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
#### 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/6e7962a7-c183-4afb-8569-9001bdfd0d87
|
||||
|
||||
{
|
||||
"data": {
|
||||
"disabled_at": null,
|
||||
"email": "new-user@test",
|
||||
"id": "6e7962a7-c183-4afb-8569-9001bdfd0d87",
|
||||
"inserted_at": "2023-01-13T06:30:47.282412Z",
|
||||
"last_signed_in_at": null,
|
||||
"last_signed_in_method": null,
|
||||
"role": "unprivileged",
|
||||
"updated_at": "2023-01-13T06:30:47.282412Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
#### 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/dedc4dcc-0f65-4110-ad7f-9c354e36e5e5
|
||||
|
||||
{
|
||||
"data": {
|
||||
"disabled_at": null,
|
||||
"email": "new-user@test",
|
||||
"id": "dedc4dcc-0f65-4110-ad7f-9c354e36e5e5",
|
||||
"inserted_at": "2023-01-13T06:30:47.166645Z",
|
||||
"last_signed_in_at": null,
|
||||
"last_signed_in_method": null,
|
||||
"role": "admin",
|
||||
"updated_at": "2023-01-13T06:30:47.166645Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
#### 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)",
|
||||
"does not match password confirmation."
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
### GET /v0/users/{id}
|
||||
|
||||
|
||||
|
||||
#### An email can be used instead of ID.
|
||||
**URI Parameters:**
|
||||
|
||||
- `id`: `test-1481@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-1481@test",
|
||||
"id": "b19a929d-fd84-4f11-a799-23416c8efaf8",
|
||||
"inserted_at": "2023-01-13T06:30:47.050304Z",
|
||||
"last_signed_in_at": null,
|
||||
"last_signed_in_method": null,
|
||||
"role": "admin",
|
||||
"updated_at": "2023-01-13T06:30:47.050304Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
### 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-3618@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-3618@test",
|
||||
"id": "54d4de57-21f3-4adc-a9a9-a3ee642da76e",
|
||||
"inserted_at": "2023-01-13T06:30:47.285730Z",
|
||||
"last_signed_in_at": null,
|
||||
"last_signed_in_method": null,
|
||||
"role": "unprivileged",
|
||||
"updated_at": "2023-01-13T06:30:47.285730Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
#### Update by ID
|
||||
**URI Parameters:**
|
||||
|
||||
- `id`: `8dd4eff5-3d2f-4868-94cd-73abb6f130dc`
|
||||
```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-3235@test",
|
||||
"id": "8dd4eff5-3d2f-4868-94cd-73abb6f130dc",
|
||||
"inserted_at": "2023-01-13T06:30:47.265280Z",
|
||||
"last_signed_in_at": null,
|
||||
"last_signed_in_method": null,
|
||||
"role": "unprivileged",
|
||||
"updated_at": "2023-01-13T06:30:47.265280Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
### DELETE /v0/users/{id}
|
||||
|
||||
|
||||
|
||||
#### Example
|
||||
**URI Parameters:**
|
||||
|
||||
- `id`: `fc0b513f-bd4b-4015-ac71-29b59c678a20`
|
||||
```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
|
||||
```
|
||||
#### An email can be used instead of ID.
|
||||
**URI Parameters:**
|
||||
|
||||
- `id`: `test-3816@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
|
||||
```
|
||||
@@ -1,11 +0,0 @@
|
||||
---
|
||||
title: Reverse Proxy Templates
|
||||
sidebar_position: 8
|
||||
---
|
||||
|
||||
```mdx-code-block
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
|
||||
|
||||
<DocCardList items={useCurrentSidebarCategory().items}/>
|
||||
```
|
||||
@@ -1,66 +0,0 @@
|
||||
---
|
||||
title: Apache
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
`<server-name>` needs to be replaced with your domain name.
|
||||
|
||||
This configuration needs to be placed in
|
||||
`/etc/sites-available/<server-name>.conf`
|
||||
|
||||
and activated with `a2ensite <server-name>`
|
||||
|
||||
```conf
|
||||
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
|
||||
<VirtualHost *:80>
|
||||
ServerName <server-name>
|
||||
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]
|
||||
</VirtualHost>
|
||||
```
|
||||
|
||||
## With SSL termination
|
||||
|
||||
This configuration builds on the one above and uses Firezone's auto-generated
|
||||
self-signed certificates.
|
||||
|
||||
```conf
|
||||
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
|
||||
<VirtualHost *:443>
|
||||
ServerName <server-name>
|
||||
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"
|
||||
</VirtualHost>
|
||||
```
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
title: HAProxy
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
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`:
|
||||
|
||||
```conf
|
||||
defaults
|
||||
mode http
|
||||
|
||||
frontend app1
|
||||
bind *:80
|
||||
option forwardfor
|
||||
default_backend backend_app1
|
||||
|
||||
backend backend_app1
|
||||
server mybackendserver 127.0.0.1:13000
|
||||
```
|
||||
@@ -1,275 +0,0 @@
|
||||
---
|
||||
title: Traefik
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
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
|
||||
`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: 2001: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: 2001: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://docs.firezone.dev/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: 2001: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}
|
||||
ADMIN_EMAIL: ${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.
|
||||
EXTERAL_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: 2001: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
|
||||
```
|
||||
@@ -1,65 +0,0 @@
|
||||
---
|
||||
title: Security Controls
|
||||
sidebar_position: 10
|
||||
---
|
||||
|
||||
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://pgp.mit.edu/pks/lookup?op=get&search=0x45113BA04AD83D8A
|
||||
|
||||
```
|
||||
-----BEGIN PGP PUBLIC KEY BLOCK-----
|
||||
Version: SKS 1.1.6
|
||||
Comment: Hostname: pgp.mit.edu
|
||||
|
||||
mDMEYYwK5BYJKwYBBAHaRw8BAQdA4ooDpwDy3V0wHCftM/LHD5e713LSr0SQy49joUMgHoS0
|
||||
JkZpcmV6b25lIFNlY3VyaXR5IDxzZWN1cml0eUBmaXJlei5vbmU+iJoEExYKAEIWIQQlD4tW
|
||||
gEEHBC38anNFETugStg9igUCYYwK5AIbAwUJA8JnAAULCQgHAgMiAgEGFQoJCAsCBBYCAwEC
|
||||
HgcCF4AACgkQRRE7oErYPYoORwEAiYi3arrcR2e5OfqsoAbCN0O6M0HWeo1K/ZoFWH2jLy0B
|
||||
AMsWk58vepKqNhUKhuDb8bSjK8TOr/IxB63lSkQaz9MIuDgEYYwK5BIKKwYBBAGXVQEFAQEH
|
||||
QPLzia/me7FOsFfAJKWm0X1qC5byv2GWn6LZPV013AdoAwEIB4h+BBgWCgAmFiEEJQ+LVoBB
|
||||
BwQt/GpzRRE7oErYPYoFAmGMCuQCGwwFCQPCZwAACgkQRRE7oErYPYr0ZQEAig86wu+zrNiT
|
||||
B4t3dk3psHRj+Kdn4uURLjUBZqYNvXoA+QEBUPtP7hNjum+1FrzYmHUFdCBA/cszz7x7PQ36
|
||||
5gcE
|
||||
=0gEr
|
||||
-----END PGP PUBLIC KEY BLOCK-----
|
||||
```
|
||||
@@ -1,108 +0,0 @@
|
||||
---
|
||||
title: Telemetry
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
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
|
||||
|
||||
:::note
|
||||
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:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="docker" label="Docker" default>
|
||||
|
||||
Set the `TELEMETRY_ENABLED` environment variable to `false` and
|
||||
restart the `firezone` container.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="omnibus" label="Omnibus">
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
:::note
|
||||
If you’re looking for support running Firezone in air-gapped or other
|
||||
restrictive environments, [contact us](https://www.firezone.dev/contact/sales?utm_source=docs.firezone.dev) about our
|
||||
[Enterprise](https://www.firezone.dev/pricing?utm_source=docs.firezone.dev) functionality.
|
||||
:::
|
||||
@@ -1,11 +0,0 @@
|
||||
---
|
||||
title: User Guides
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
```mdx-code-block
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
|
||||
|
||||
<DocCardList items={useCurrentSidebarCategory().items}/>
|
||||
```
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
title: Add Devices
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# 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](/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`.
|
||||
|
||||
|
||||
|
||||
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](/user-guides/add-users/) for more information on how to add a
|
||||
user.
|
||||
|
||||
## Related guides
|
||||
|
||||
* [Client Instructions](/user-guides/client-instructions/)
|
||||
@@ -1,24 +0,0 @@
|
||||
---
|
||||
title: Add Users
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# 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](/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](/authenticate/) for more
|
||||
information.
|
||||
|
||||
|
||||
|
||||
## Related guides
|
||||
|
||||
* [Authenticate](/authenticate/)
|
||||
@@ -1,185 +0,0 @@
|
||||
---
|
||||
title: Client Instructions
|
||||
sidebar_position: 4
|
||||
description:
|
||||
Set up your client app to connect to your organization's private
|
||||
networks and resources. Download the open-source WireGuard® app
|
||||
for your operating system (Windows, MacOS, iOS, Android, Linux) to
|
||||
get started.
|
||||
---
|
||||
|
||||
# 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`)
|
||||
|
||||
|
||||
|
||||
### Step 3 (optional): Enable on boot
|
||||
|
||||
Open the WireGuard client and import the `.conf` file.
|
||||
Activate the VPN session by toggling the `Activate` switch.
|
||||
|
||||
|
||||
|
||||
## 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
|
||||
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
|
||||
### Step 3: Activate VPN session
|
||||
|
||||
|
||||
|
||||
## Linux: Network Manager
|
||||
|
||||
The following steps can be used on Linux devices to import the WireGuard
|
||||
configuration profile using Network Manager CLI (`nmcli`).
|
||||
|
||||
:::note
|
||||
Importing the configuration file using the Network Manager GUI may fail
|
||||
with the following error if the profile has IPv6 support enabled:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```shell
|
||||
sudo apt install wireguard
|
||||
```
|
||||
|
||||
For Fedora:
|
||||
|
||||
```shell
|
||||
sudo dnf install wireguard-tools
|
||||
```
|
||||
|
||||
For Arch Linux:
|
||||
|
||||
```shell
|
||||
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`)
|
||||
|
||||
|
||||
|
||||
### Step 3: Import configuration
|
||||
|
||||
Using `nmcli`, import the downloaded configuration file:
|
||||
|
||||
```shell
|
||||
sudo nmcli connection import type wireguard file /path/to/configuration.conf
|
||||
```
|
||||
|
||||
:::note
|
||||
The WireGuard connection/interface will match the name of the configuration
|
||||
file. If required, the connection can be renamed after import:
|
||||
|
||||
```shell
|
||||
nmcli connection modify [old name] connection.id [new name]
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### Step 4: Connect/disconnect
|
||||
|
||||
To connect to the VPN via the command line:
|
||||
|
||||
```shell
|
||||
nmcli connection up [vpn name]
|
||||
```
|
||||
|
||||
To disconnect:
|
||||
|
||||
```shell
|
||||
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`:
|
||||
|
||||
```shell
|
||||
nmcli connection modify [vpn name] connection.autoconnect yes
|
||||
```
|
||||
|
||||
To disable the automatic connection set it back to `no`:
|
||||
|
||||
```shell
|
||||
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.
|
||||
@@ -1,18 +0,0 @@
|
||||
---
|
||||
title: Egress Rules
|
||||
sidebar_position: 3
|
||||
description:
|
||||
Define access policies with egress filtering rules using
|
||||
Firezone's WireGuard®-based secure access platform.
|
||||
---
|
||||
|
||||
# Network access control
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@@ -1,11 +0,0 @@
|
||||
---
|
||||
title: Common Use Cases
|
||||
sidebar_position: 10
|
||||
---
|
||||
|
||||
```mdx-code-block
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
|
||||
|
||||
<DocCardList items={useCurrentSidebarCategory().items}/>
|
||||
```
|
||||
@@ -1,71 +0,0 @@
|
||||
---
|
||||
title: NAT Gateway
|
||||
sidebar_position: 3
|
||||
description: Set a static IP for egress traffic with Firezone's WireGuard®-based secure access platform.
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
|
||||
|
||||
## 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](/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`.
|
||||
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
|
||||
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](/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`.
|
||||
@@ -1,89 +0,0 @@
|
||||
---
|
||||
title: Restrict SSO to Firezone Users
|
||||
sidebar_position: 1
|
||||
description: Configure your identity provider to whitelist traffic from Firezone's WireGuard®-based secure access platform.
|
||||
---
|
||||
<!--
|
||||
XXX: This document is in draft status. Remove this notice when it's published.
|
||||
-->
|
||||
# Restrict application authentication to VPN users
|
||||
|
||||
Some identity providers support restricting SSO functionality
|
||||
Some identity providers support restricting SSO access to a predefined CIDR range or list of IP addresses. You can set this to the IP address of
|
||||
your Firezone gateway to restrict SSO to users connected to Firezone.
|
||||
|
||||
This adds an additional layer of security to any service that uses
|
||||
your identity provider for SSO.
|
||||
|
||||
We have identified a few common providers that support this
|
||||
feature and included basic instructions below on how you can set
|
||||
this up. The pre-requisites to this guide are a deployed Firezone
|
||||
server with a static IP
|
||||
([see NAT Gateway](.../nat-gateway))
|
||||
and ensuring traffic to the identity provider's SSO services are
|
||||
routed from client devices through the Firezone gateway
|
||||
([see Split Tunnel](.../split-tunnel)).
|
||||
|
||||
## Okta
|
||||
|
||||
Okta supports restricting SSO authentication to a "network zone" on
|
||||
a per application basis.
|
||||
|
||||
:::note
|
||||
If you have split tunneling enabled, ensure the AllowedIPs are
|
||||
correctly configured to direct traffic to
|
||||
[Okta's IPs](https://help.okta.com/en-us/Content/Topics/Security/ip-address-allow-listing.htm)
|
||||
through the Firezone gateway.
|
||||
:::
|
||||
|
||||
:::caution
|
||||
Sign-on policies are assigned on an application level. We advise
|
||||
excluding the Firezone application from the IP restriction policy above if Okta
|
||||
is being used for Firezone authentication.
|
||||
|
||||
With
|
||||
[periodic authentication](../../authenticate#enforce-periodic-re-authentication)
|
||||
enabled, you may be locked out of Okta entirely when your VPN session
|
||||
expires.
|
||||
:::
|
||||
|
||||
### Create the network zone
|
||||
|
||||
_This section is based on Okta's
|
||||
[documentation](https://help.okta.com/oie/en-us/Content/Topics/Security/network/create-ip-zone.htm)._
|
||||
|
||||
Navigate to **Security > Networks**. Add an **IP Zone** with the
|
||||
static IP of the Firezone Gateway in **Gateway IPs**.
|
||||
|
||||
|
||||
|
||||
### Create a sign-on policy
|
||||
|
||||
_This section is based on Okta's
|
||||
[documentation](https://help.okta.com/oie/en-us/Content/Topics/Security/network/add-network-zone-signon-policy.htm)._
|
||||
|
||||
Navigate to **Security > Authentication policies**. Create a new
|
||||
policy that denies access when a user
|
||||
is **NOT** on the network zone defined above.
|
||||
|
||||
|
||||
|
||||
### Associate sign-on policy to application
|
||||
|
||||
Under the **Sign On** tab, set the **Authentication policy** to the
|
||||
policy defined above. Do this for applications where authentication
|
||||
should be restricted only to users on the VPN.
|
||||
|
||||
|
||||
|
||||
### Configure VPN notification (optional)
|
||||
|
||||
_This section is based on Okta's
|
||||
[documentation](https://help.okta.com/oie/en-us/Content/Topics/Security/network/vpn-notification.htm)._
|
||||
|
||||
Optionally configure a notification to alert users why
|
||||
their access was denied.
|
||||
On the details page of your Okta application, configure the
|
||||
**General > VPN Notification** section.
|
||||
|
||||
|
||||
@@ -1,84 +0,0 @@
|
||||
---
|
||||
title: Reverse Tunnel
|
||||
sidebar_position: 2
|
||||
description:
|
||||
Configure Firezone as a relay to connect two or more devices.
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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](/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.
|
||||
|
||||
|
||||
|
||||
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](/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](/user-guides/use-cases/nat-gateway/)
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
title: Split Tunnel VPN
|
||||
sidebar_position: 1
|
||||
description:
|
||||
Configure Firezone for split tunneling. Route some network traffic
|
||||
from end users through the encrypted WireGuard® tunnel.
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
:::note
|
||||
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.
|
||||
|
||||
:::note
|
||||
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](/user-guides/add-devices/) for instructions.
|
||||
@@ -1,178 +0,0 @@
|
||||
// @ts-check
|
||||
// Note: type annotations allow type checking and IDEs autocompletion
|
||||
|
||||
const lightCodeTheme = require('prism-react-renderer/themes/github');
|
||||
const darkCodeTheme = require('prism-react-renderer/themes/dracula');
|
||||
|
||||
/** @type {import('@docusaurus/types').Config} */
|
||||
const config = {
|
||||
title: 'Firezone',
|
||||
tagline: 'Open-source VPN server and Linux firewall built on WireGuard®',
|
||||
url: 'https://docs.firezone.dev',
|
||||
baseUrl: '/',
|
||||
onBrokenLinks: 'throw',
|
||||
onBrokenMarkdownLinks: 'warn',
|
||||
trailingSlash: true,
|
||||
favicon: 'img/favicon.ico',
|
||||
|
||||
// GitHub pages deployment config.
|
||||
// If you aren't using GitHub pages, you don't need these.
|
||||
organizationName: 'firezone', // Usually your GitHub org/user name.
|
||||
projectName: 'firezone', // Usually your repo name.
|
||||
|
||||
// Even if you don't use internalization, you can use this field to set useful
|
||||
// metadata like html lang. For example, if your site is Chinese, you may want
|
||||
// to replace 'en' with 'zh-Hans'.
|
||||
i18n: {
|
||||
defaultLocale: 'en',
|
||||
locales: ['en'],
|
||||
},
|
||||
|
||||
// An array of scripts to load. The values can be either strings or plain
|
||||
// objects of attribute-value maps. The <script> tags will be inserted in the
|
||||
// HTML <head>. If you use a plain object, the only required attribute is src,
|
||||
// and any other attributes are permitted (each one should have boolean/string
|
||||
// values).
|
||||
//
|
||||
// Note that <script> added here are render-blocking, so you might want to
|
||||
// add async: true/defer: true to the objects.
|
||||
scripts: [
|
||||
{
|
||||
src: '/js/posthog.js',
|
||||
async: true
|
||||
}
|
||||
],
|
||||
|
||||
plugins: [],
|
||||
|
||||
themes: [],
|
||||
|
||||
presets: [
|
||||
[
|
||||
'classic',
|
||||
/** @type {import('@docusaurus/preset-classic').Options} */
|
||||
({
|
||||
docs: {
|
||||
routeBasePath: '/',
|
||||
sidebarPath: require.resolve('./sidebars.js'),
|
||||
editUrl: 'https://github.com/firezone/firezone/tree/master/docs',
|
||||
docLayoutComponent: "@theme/DocPage"
|
||||
},
|
||||
theme: {
|
||||
customCss: require.resolve('./src/css/custom.css'),
|
||||
},
|
||||
}),
|
||||
],
|
||||
],
|
||||
|
||||
themeConfig:
|
||||
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
|
||||
({
|
||||
navbar: {
|
||||
title: 'Documentation',
|
||||
logo: {
|
||||
alt: 'Firezone Logo',
|
||||
src: 'img/logo.svg',
|
||||
},
|
||||
items: [
|
||||
{
|
||||
href: 'https://discourse.firez.one/?utm_source=docs.firezone.dev',
|
||||
label: 'Ask a Question',
|
||||
position: 'right',
|
||||
'aria-label': 'GitHub repository',
|
||||
},
|
||||
{
|
||||
href: 'https://www.firezone.dev/contact/sales?utm_source=docs.firezone.dev',
|
||||
label: 'Contact sales',
|
||||
position: 'right',
|
||||
'aria-label': 'Contact sales',
|
||||
},
|
||||
{
|
||||
href: 'https://github.com/firezone/firezone',
|
||||
className: 'header-github-link',
|
||||
position: 'right',
|
||||
'aria-label': 'GitHub repository',
|
||||
},
|
||||
],
|
||||
},
|
||||
footer: {
|
||||
style: 'light',
|
||||
links: [
|
||||
{
|
||||
title: 'Company',
|
||||
items: [
|
||||
{
|
||||
label: 'Homepage',
|
||||
href: 'https://www.firezone.dev/?utm_source=docs.firezone.dev',
|
||||
},
|
||||
{
|
||||
label: 'Pricing',
|
||||
href: 'https://www.firezone.dev/pricing?utm_source=docs.firezone.dev',
|
||||
},
|
||||
{
|
||||
label: 'About',
|
||||
href: 'https://www.firezone.dev/about?utm_source=docs.firezone.dev',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
title: 'Community',
|
||||
items: [
|
||||
{
|
||||
label: 'Support Forums',
|
||||
href: 'https://discourse.firez.one/?utm_source=docs.firezone.dev',
|
||||
},
|
||||
{
|
||||
label: 'Slack',
|
||||
href: 'https://www.firezone.dev/slack?utm_source=docs.firezone.dev',
|
||||
},
|
||||
{
|
||||
label: 'Github',
|
||||
href: 'https://github.com/firezone/firezone?utm_source=docs.firezone.dev',
|
||||
},
|
||||
{
|
||||
label: 'Twitter',
|
||||
href: 'https://twitter.com/firezonehq?utm_source=docs.firezone.dev',
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
copyright: `Copyright © ${new Date().getFullYear()} Firezone, Inc.`,
|
||||
},
|
||||
prism: {
|
||||
theme: lightCodeTheme,
|
||||
darkTheme: darkCodeTheme,
|
||||
additionalLanguages: ['ruby', 'elixir']
|
||||
},
|
||||
algolia: {
|
||||
// The application ID provided by Algolia
|
||||
appId: 'XXPZ9QVGFB',
|
||||
|
||||
start_urls: [
|
||||
'https://docs.firezone.dev/'
|
||||
],
|
||||
|
||||
sitemap_urls: [
|
||||
'https://docs.firezone.dev/sitemap.xml'
|
||||
],
|
||||
|
||||
// Public API key: it is safe to commit it
|
||||
apiKey: '66664e8765e1645ea0b500acebb0b0c2',
|
||||
|
||||
indexName: 'firezone',
|
||||
|
||||
// Optional: see doc section below
|
||||
// Requires more configuration and setup to work, so disabling. See
|
||||
// https://discourse.algolia.com/t/algolia-searchbar-is-not-working-with-docusaurus-v2/14659/2
|
||||
contextualSearch: true,
|
||||
|
||||
// Optional: path for search page that enabled by default (`false` to disable it)
|
||||
searchPagePath: 'search',
|
||||
|
||||
//... other Algolia params
|
||||
},
|
||||
metadata: [{name: 'keywords', content: 'wireguard, vpn, firewall, remote access, network, documentation'}],
|
||||
}),
|
||||
};
|
||||
|
||||
module.exports = config;
|
||||
@@ -1,43 +0,0 @@
|
||||
{
|
||||
"name": "firezone-docs",
|
||||
"version": "0.0.0",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"docusaurus": "docusaurus",
|
||||
"start": "docusaurus start",
|
||||
"build": "docusaurus build",
|
||||
"swizzle": "docusaurus swizzle",
|
||||
"deploy": "docusaurus deploy",
|
||||
"clear": "docusaurus clear",
|
||||
"serve": "docusaurus serve",
|
||||
"write-translations": "docusaurus write-translations",
|
||||
"write-heading-ids": "docusaurus write-heading-ids"
|
||||
},
|
||||
"dependencies": {
|
||||
"@docusaurus/core": "^2.1.0",
|
||||
"@docusaurus/preset-classic": "^2.1.0",
|
||||
"@docusaurus/theme-search-algolia": "^2.1.0",
|
||||
"@mdx-js/react": "^1.6.22",
|
||||
"clsx": "^1.1.1",
|
||||
"markdownlint-cli": "^0.31.1",
|
||||
"prism-react-renderer": "^1.3.3",
|
||||
"react": "^17.0.2",
|
||||
"react-dom": "^17.0.2"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@docusaurus/module-type-aliases": "2.1.0",
|
||||
"css-minimizer-webpack-plugin": "4.1.0"
|
||||
},
|
||||
"browserslist": {
|
||||
"production": [
|
||||
">0.5%",
|
||||
"not dead",
|
||||
"not op_mini all"
|
||||
],
|
||||
"development": [
|
||||
"last 1 chrome version",
|
||||
"last 1 firefox version",
|
||||
"last 1 safari version"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,31 +0,0 @@
|
||||
/**
|
||||
* Creating a sidebar enables you to:
|
||||
- create an ordered group of docs
|
||||
- render a sidebar for each doc of that group
|
||||
- provide next/previous navigation
|
||||
|
||||
The sidebars can be generated from the filesystem, or explicitly defined here.
|
||||
|
||||
Create as many sidebars as you want.
|
||||
*/
|
||||
|
||||
// @ts-check
|
||||
|
||||
/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
|
||||
const sidebars = {
|
||||
// By default, Docusaurus generates a sidebar from the docs folder structure
|
||||
tutorialSidebar: [{ type: "autogenerated", dirName: "." }],
|
||||
|
||||
// But you can create a sidebar manually
|
||||
/*
|
||||
tutorialSidebar: [
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Tutorial',
|
||||
items: ['hello'],
|
||||
},
|
||||
],
|
||||
*/
|
||||
};
|
||||
|
||||
module.exports = sidebars;
|
||||
@@ -1,50 +0,0 @@
|
||||
import React from "react";
|
||||
import styles from "./styles.module.css";
|
||||
|
||||
const AccentBlock = ({
|
||||
title,
|
||||
description,
|
||||
buttonOneText,
|
||||
buttonOneLink,
|
||||
buttonTwoText,
|
||||
buttonTwoLink,
|
||||
imageSrc,
|
||||
imageAlt,
|
||||
imageHeight,
|
||||
}) => {
|
||||
return (
|
||||
<div className={styles.accentBlock}>
|
||||
<div className={styles.contentBlock}>
|
||||
<div>
|
||||
<h1>{title ? title : "Please Add Title"}</h1>
|
||||
<p>{description ? description : "Please Add Description"}</p>
|
||||
</div>
|
||||
<div className={styles.btnWrapper}>
|
||||
{buttonOneText && buttonOneLink && (
|
||||
<button
|
||||
onClick={() => window.open(buttonOneLink)}
|
||||
className={styles.btnPrimary}>
|
||||
{buttonOneText}
|
||||
</button>
|
||||
)}
|
||||
{buttonTwoText && buttonTwoLink && (
|
||||
<button
|
||||
onClick={() => window.open(buttonTwoLink)}
|
||||
className={styles.btn}>
|
||||
{buttonTwoText}
|
||||
</button>
|
||||
)}
|
||||
</div>
|
||||
</div>
|
||||
{imageSrc && (
|
||||
<img
|
||||
alt={imageAlt}
|
||||
src={imageSrc}
|
||||
height={imageHeight}
|
||||
className={styles.sideImage}></img>
|
||||
)}
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
||||
export default AccentBlock;
|
||||
@@ -1,75 +0,0 @@
|
||||
.accentBlock {
|
||||
width: 100%;
|
||||
background-color: #f8f7f7;
|
||||
border-radius: 12px;
|
||||
padding: 20px;
|
||||
margin-top: 40px;
|
||||
display: flex;
|
||||
justify-content: space-between;
|
||||
}
|
||||
|
||||
[data-theme="dark"] .accentBlock {
|
||||
background-color: #1b140e;
|
||||
}
|
||||
|
||||
.contentBlock {
|
||||
width: 60%;
|
||||
height: inherit;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
justify-content: space-between;
|
||||
}
|
||||
|
||||
.accentBlock h1 {
|
||||
margin: 0 !important;
|
||||
font-size: 2rem;
|
||||
}
|
||||
|
||||
.accentBlock p {
|
||||
font-size: 1rem;
|
||||
margin-top: 5px;
|
||||
margin-bottom: 0px;
|
||||
}
|
||||
|
||||
.btnWrapper {
|
||||
margin-top: 10px;
|
||||
}
|
||||
|
||||
.btnWrapper button {
|
||||
padding: 15px 25px;
|
||||
margin: 5px;
|
||||
border-radius: 6px;
|
||||
font-size: 1rem;
|
||||
cursor: pointer;
|
||||
transition: all 0.2s ease-out;
|
||||
}
|
||||
|
||||
.btnWrapper button:first-child {
|
||||
margin-left: 0px;
|
||||
}
|
||||
|
||||
.btnPrimary {
|
||||
background-color: #1b140e;
|
||||
color: #fcfcfc;
|
||||
border: none;
|
||||
}
|
||||
|
||||
[data-theme="dark"] .btnPrimary {
|
||||
background-color: #4c3e33;
|
||||
}
|
||||
|
||||
.btnPrimary:hover {
|
||||
transform: scale(1.05);
|
||||
}
|
||||
|
||||
.btn {
|
||||
background: transparent;
|
||||
border: none;
|
||||
}
|
||||
|
||||
.sideImage {
|
||||
padding: 10px;
|
||||
width: 40%;
|
||||
object-fit: cover;
|
||||
border: none;
|
||||
}
|
||||
@@ -1,46 +0,0 @@
|
||||
import React, { useState } from "react";
|
||||
import styles from "./styles.module.css";
|
||||
|
||||
const Feedback = () => {
|
||||
const [showFeedbackAction, setShowFeedbackAction] = useState(false);
|
||||
return (
|
||||
<div className={styles.feedbackWrapper}>
|
||||
<h1>
|
||||
{showFeedbackAction
|
||||
? "Thanks for the feedback"
|
||||
: "Was this page useful?"}
|
||||
</h1>
|
||||
{!showFeedbackAction ? (
|
||||
<div className={styles.voteWrapper}>
|
||||
<button onClick={() => setShowFeedbackAction(true)}>
|
||||
<img src="img/like.svg"></img> Like
|
||||
</button>
|
||||
<button onClick={() => setShowFeedbackAction(true)}>
|
||||
<img src="img/dislike.svg"></img> Dislike
|
||||
</button>
|
||||
</div>
|
||||
) : (
|
||||
<div>
|
||||
<p>
|
||||
If you need help on any of the above, feel free to create an issue
|
||||
on{" "}
|
||||
<a href="https://github.com/firezone/firezone" target="_blank">
|
||||
our repo
|
||||
</a>
|
||||
, or{" "}
|
||||
<a
|
||||
href="https://join.slack.com/t/firezone-users/shared_invite/zt-19jd956j4-rWcCqiKMh~ikPGsUFbvZiA"
|
||||
target="_blank">
|
||||
join our Slack
|
||||
</a>{" "}
|
||||
where a member of our team can assist you! Chances are that if you
|
||||
have a problem or question, someone else does too - so please don't
|
||||
hesitate to create a new issue or ask us a question.
|
||||
</p>
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
||||
export default Feedback;
|
||||
@@ -1,58 +0,0 @@
|
||||
.feedbackWrapper {
|
||||
width: 100%;
|
||||
height: 200px;
|
||||
margin: 10px 0px;
|
||||
padding: 0px;
|
||||
background-color: transparent;
|
||||
border-radius: 12px;
|
||||
}
|
||||
|
||||
.feedbackWrapper h1 {
|
||||
margin: 0 !important;
|
||||
font-size: 1.2rem;
|
||||
}
|
||||
|
||||
.feedbackWrapper p {
|
||||
font-size: 1rem;
|
||||
margin-top: 10px;
|
||||
}
|
||||
|
||||
.voteWrapper {
|
||||
margin-top: 10px;
|
||||
display: flex;
|
||||
}
|
||||
.voteWrapper button {
|
||||
padding: 15px 20px;
|
||||
border: none;
|
||||
cursor: pointer;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
border-radius: 6px;
|
||||
font-size: 1rem;
|
||||
margin: 10px;
|
||||
background-color: transparent;
|
||||
border: 1px solid rgba(0, 0, 0, 0.5);
|
||||
transition: all 0.2s ease-out;
|
||||
}
|
||||
|
||||
[data-theme="dark"] .voteWrapper button {
|
||||
border: 1px solid rgba(255, 255, 255, 0.5);
|
||||
}
|
||||
|
||||
.voteWrapper button:first-child {
|
||||
margin-left: 0px;
|
||||
}
|
||||
|
||||
.voteWrapper button:hover {
|
||||
border: 1px solid rgba(0, 0, 0, 1);
|
||||
}
|
||||
|
||||
[data-theme="dark"] .voteWrapper button:hover {
|
||||
border: 1px solid rgba(255, 255, 255, 1);
|
||||
}
|
||||
|
||||
.voteWrapper button img {
|
||||
height: 20px;
|
||||
margin-right: 10px;
|
||||
}
|
||||
@@ -1,22 +0,0 @@
|
||||
import React from "react";
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
import BrowserOnly from '@docusaurus/BrowserOnly';
|
||||
|
||||
export default function InstallBlock() {
|
||||
return (
|
||||
<BrowserOnly fallback={<div>Loading...</div>}>
|
||||
{() => {
|
||||
const distinct_id =
|
||||
(window.posthog && typeof window.posthog.get_distinct_id === "function")
|
||||
? window.posthog.get_distinct_id()
|
||||
: "posthog-blocked"
|
||||
|
||||
return (
|
||||
<CodeBlock language="bash">
|
||||
{`bash <(curl -fsSL https://github.com/firezone/firezone/raw/master/scripts/install.sh) ${distinct_id}`}
|
||||
</CodeBlock>
|
||||
)
|
||||
}}
|
||||
</BrowserOnly>
|
||||
)
|
||||
}
|
||||
@@ -1,24 +0,0 @@
|
||||
import React, { useState } from "react";
|
||||
import styles from "./styles.module.css";
|
||||
|
||||
const SignUp = () => {
|
||||
const [email, setEmail] = useState("");
|
||||
const [isInvalid, setIsInvalid] = useState("");
|
||||
|
||||
const onSubmit = () => {
|
||||
if (email.length > 1) {
|
||||
console.log(email);
|
||||
}
|
||||
};
|
||||
return (
|
||||
<div className={styles.signupWrapper}>
|
||||
<iframe
|
||||
height="100%"
|
||||
width="100%"
|
||||
src="https://cdn.forms-content.sg-form.com/ae95a755-f1b0-11ec-bae1-cec19e074e52"
|
||||
/>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
||||
export default SignUp;
|
||||
@@ -1,10 +0,0 @@
|
||||
.signupWrapper {
|
||||
width: 100%;
|
||||
height: 500px;
|
||||
background-color: #f8f7f7;
|
||||
border-radius: 12px;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
justify-content: space-between;
|
||||
margin: 20px 0px;
|
||||
}
|
||||
@@ -1,72 +0,0 @@
|
||||
/**
|
||||
* Any CSS included here will be global. The classic template
|
||||
* bundles Infima by default. Infima is a CSS framework designed to
|
||||
* work well for content-centric websites.
|
||||
*/
|
||||
|
||||
@import url('https://fonts.googleapis.com/css2?family=Fira+Sans:ital,wght@0,300;0,400;0,700;1,300;1,400;1,700&family=Open+Sans:ital,wght@0,300;0,400;0,700;1,300;1,400;1,700&display=swap');
|
||||
|
||||
/* You can override the default Infima variables here. */
|
||||
:root {
|
||||
--ifm-color-primary: #3400c2;
|
||||
--ifm-color-primary-dark: #766a60;
|
||||
--ifm-color-primary-darker: #4c3e33;
|
||||
--ifm-color-primary-darkest: #1b140e;
|
||||
--ifm-color-primary-light: #dfdedd;
|
||||
--ifm-color-primary-lighter: #ebebea;
|
||||
--ifm-color-primary-lightest: #f8f7f7;
|
||||
--ifm-code-font-size: 95%;
|
||||
--docusaurus-highlighted-code-line-bg: rgba(205, 153, 153, 0.2);
|
||||
}
|
||||
|
||||
/* For readability concerns, you should choose a lighter palette in dark mode. */
|
||||
[data-theme="dark"] {
|
||||
--ifm-color-primary: #ff7300;
|
||||
--ifm-color-primary-dark: #c25700;
|
||||
--ifm-color-primary-darker: #7f3900;
|
||||
--ifm-color-primary-darkest: #5c2900;
|
||||
--ifm-color-primary-light: #ffbc85;
|
||||
--ifm-color-primary-lighter: #ffddc2;
|
||||
--ifm-color-primary-lightest: #fff1e5;
|
||||
--ifm-code-font-size: 95%;
|
||||
--docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
|
||||
}
|
||||
|
||||
body {
|
||||
font-family: 'Fira Sans', sans-serif;
|
||||
}
|
||||
|
||||
h1,h2,h3,h4,h5,h6 {
|
||||
font-family: 'Open Sans', sans-serif;
|
||||
}
|
||||
|
||||
table {
|
||||
display: table;
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
.header-github-link:hover {
|
||||
opacity: 0.6;
|
||||
}
|
||||
|
||||
.header-github-link::before {
|
||||
content: '';
|
||||
width: 24px;
|
||||
height: 24px;
|
||||
display: flex;
|
||||
background: url(/img/github_light.svg) no-repeat;
|
||||
}
|
||||
|
||||
[data-theme='dark'] .header-github-link::before {
|
||||
background: url(/img/github_dark.svg) no-repeat;
|
||||
}
|
||||
|
||||
/* Show a border around Tab containers to make it more clear
|
||||
* where they end
|
||||
*/
|
||||
.tabs-container {
|
||||
background: rgba(100, 100, 100, 0.1);
|
||||
padding-bottom: 1.5rem;
|
||||
padding-left: 1.5rem;
|
||||
border-radius: 5px;
|
||||
}
|
||||
@@ -1,12 +0,0 @@
|
||||
## Need additional help?
|
||||
|
||||
Try asking on one of our community-powered support channels:
|
||||
|
||||
* [Discussion Forums](https://discourse.firez.one/?utm_source=docs.firezone.dev): Ask questions, report bugs,
|
||||
and suggest features.
|
||||
* [Public Slack Group](https://join.slack.com/t/firezone-users/shared_invite/zt-111043zus-j1lP_jP5ohv52FhAayzT6w):
|
||||
join discussions, meet other users, and meet the contributors
|
||||
|
||||
**Looking for dedicated support?** [Contact us](https://www.firezone.dev/contact/sales?utm_source=docs.firezone.dev)
|
||||
about our paid support option if you're using Firezone in a production
|
||||
capacity for your team or organization.
|
||||
@@ -1,21 +0,0 @@
|
||||
// Import the original mapper
|
||||
import MDXComponents from "@theme-original/MDXComponents";
|
||||
import InstallBlock from "@site/src/components/InstallBlock";
|
||||
import AccentBlock from "@site/src/components/AccentBlock";
|
||||
import Feedback from "@site/src/components/Feedback";
|
||||
import SignUp from "@site/src/components/SignUp";
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
export default {
|
||||
// Re-use the default mapping
|
||||
...MDXComponents,
|
||||
// Map the "highlight" tag to our <Highlight /> component!
|
||||
// `Highlight` will receive all props that were passed to `highlight` in MDX
|
||||
InstallBlock: InstallBlock,
|
||||
accentblock: AccentBlock,
|
||||
feedback: Feedback,
|
||||
newsletter: SignUp,
|
||||
Tabs: Tabs,
|
||||
TabItem: TabItem,
|
||||
};
|
||||
0
docs/static/.nojekyll
vendored
0
docs/static/.nojekyll
vendored
1
docs/static/img/dislike.svg
vendored
1
docs/static/img/dislike.svg
vendored
@@ -1 +0,0 @@
|
||||
<?xml version="1.0" ?><!DOCTYPE svg PUBLIC '-//W3C//DTD SVG 1.1//EN' 'http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd'><svg height="512px" style="enable-background:new 0 0 512 512;" version="1.1" viewBox="0 0 512 512" width="512px" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"><g id="_x39_4-dislike"><g><path d="M128.543,270.411V68.616c0-7.953,6.442-14.408,14.379-14.408H27.926 c-7.944,0-14.378,6.456-14.378,14.408v201.795c0,7.955,6.434,14.411,14.378,14.413H134.58l-4.139-7.264 C129.176,275.376,128.543,272.922,128.543,270.411z" style="fill:#F54E00;"/><path d="M497.179,192.488l-46.106-104.04c-9.174-20.779-29.813-34.24-52.532-34.24H182.203h-14.375 c-7.937,0-14.379,6.456-14.379,14.408v201.795c0,2.511,0.633,4.965,1.898,7.149l4.139,7.264l51.466,90.317v68.233 c0,7.959,6.442,14.417,14.367,14.417h43.134c31.71,0,57.491-25.864,57.491-57.652v-86.485h115.007 c31.712,0,57.502-25.863,57.501-57.656v-57.656C498.452,196.328,498.021,194.336,497.179,192.488z" style="fill:#F54E00;"/></g></g><g id="Layer_1"/></svg>
|
||||
|
Before Width: | Height: | Size: 1.1 KiB |
BIN
docs/static/img/favicon.ico
vendored
BIN
docs/static/img/favicon.ico
vendored
Binary file not shown.
|
Before Width: | Height: | Size: 15 KiB |
1
docs/static/img/github_dark.svg
vendored
1
docs/static/img/github_dark.svg
vendored
@@ -1 +0,0 @@
|
||||
<svg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'><path fill='white' d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/></svg>
|
||||
|
Before Width: | Height: | Size: 804 B |
1
docs/static/img/github_light.svg
vendored
1
docs/static/img/github_light.svg
vendored
@@ -1 +0,0 @@
|
||||
<svg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'><path d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/></svg>
|
||||
|
Before Width: | Height: | Size: 791 B |
1
docs/static/img/like.svg
vendored
1
docs/static/img/like.svg
vendored
@@ -1 +0,0 @@
|
||||
<?xml version="1.0" ?><!DOCTYPE svg PUBLIC '-//W3C//DTD SVG 1.1//EN' 'http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd'><svg height="512px" style="enable-background:new 0 0 512 512;" version="1.1" viewBox="0 0 512 512" width="512px" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"><g id="_x31_99-like"><g><path d="M133.815,443.378V241.587c0-2.507,0.632-4.962,1.897-7.148l4.141-7.268H33.193 c-7.938,0-14.378,6.46-14.378,14.416v201.791c0,7.953,6.44,14.412,14.378,14.412h114.994 C140.255,457.79,133.815,451.331,133.815,443.378z" style="fill:#2AC276;"/><path d="M435.682,198.344H320.684v-86.483c0-31.798-25.787-57.651-57.494-57.651h-43.132 c-7.93,0-14.368,6.456-14.368,14.408v68.237l-51.463,90.315l-4.141,7.268c-1.265,2.186-1.897,4.642-1.897,7.148v201.791 c0,7.953,6.44,14.412,14.372,14.412h14.38h216.339c22.715,0,43.355-13.46,52.527-34.245l46.111-104.04 c0.838-1.841,1.27-3.834,1.27-5.849V256C493.186,224.199,467.395,198.344,435.682,198.344z" style="fill:#2AC276;"/></g></g><g id="Layer_1"/></svg>
|
||||
|
Before Width: | Height: | Size: 1.0 KiB |
5
docs/static/img/logo.svg
vendored
5
docs/static/img/logo.svg
vendored
@@ -1,5 +0,0 @@
|
||||
<svg width="228" height="184" viewBox="0 0 228 184" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<path fill-rule="evenodd" clip-rule="evenodd" d="M145.858 0C190.958 37.5635 144.268 120.815 160.744 154.43C126.887 105.847 173.016 64.0952 145.858 0Z" fill="#EF7A30"/>
|
||||
<path fill-rule="evenodd" clip-rule="evenodd" d="M170.867 72.3025C200.346 91.4569 164.96 136.337 183.798 147.825C202.876 159.46 200.717 111.106 227.059 123.51C199.632 114.179 211.01 171.748 177.025 164.087C138.134 155.319 186.501 93.4581 170.867 72.3025Z" fill="#7F3900"/>
|
||||
<path fill-rule="evenodd" clip-rule="evenodd" d="M0 137.888C56.1454 93.1552 132.622 164.939 168.711 169.425C215.123 175.192 202.76 121.53 225.99 123.53C204.585 126.111 217.433 182.233 169.576 183.967C117.459 185.856 65.4612 106.395 9.60305e-05 137.888H0Z" fill="#331700"/>
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 821 B |
2
docs/static/js/posthog.js
vendored
2
docs/static/js/posthog.js
vendored
@@ -1,2 +0,0 @@
|
||||
!function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
|
||||
posthog.init('phc_ubuPhiqqjMdedpmbWpG2Ak3axqv5eMVhFDNBaXl9UZK',{api_host:'https://t.firez.one'})
|
||||
7710
docs/yarn.lock
7710
docs/yarn.lock
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user