github-personal/firezone
1
0
Fork 0
mirror of https://github.com/outbackdingo/firezone.git synced 2026-01-27 10:18:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

General Docs Improvements (#1194)

Browse Source 
* docs: add logs and update troubleshooting

Updates the troubleshooting doc for Docker based deployments and adds a general logs doc with more info on what Firezone logs.

Also added a mention of Audit logs in beta to source more convos.

* docs: further Docker clarifications

Clarifying some troubleshooting guides that refer to firezone-ctl.

Not everyone arrives at the env-vars or config file through the deploy/configure guide. Some load these pages directly via search. Adding a more prominent note that it's for Omnibus based deploy.

* docs: add troubleshooting docs on locked out state

Adding a section on reseting admin passwords for both docker and omnibus deployments. I realize we removed the omnibus firezone-ctl reference. I won't add it back since I have no idea where to put it.

* docs: update split tunnel doc

Was originally going to write more about other ways you can achieve split tunneling with wireguard, but will leave that for now

* fix whitespace

* update split tunnel doc

* docs: add DNS considerations to split tunnel doc

https://github.com/firezone/product/issues/527

* update split tunnel doc

* further clarify split tunnel doc

* add note about on-demand feature

* Docs - Improve titles and descriptions (#1187)

* docs: update titles, descriptions

Changes:
- set more descriptive titles (better for readers and SEO)
- add meta descriptions
- convert titles to sentence case for consistency

* docs: small fixes

* fix trailing whitespaces

* fix spelling

* Apply suggestions from code review

Co-authored-by: Jamil <jamilbk@users.noreply.github.com>
Signed-off-by: Jason G <jason@firez.one>

* add descriptions to client instructions

Signed-off-by: Jason G <jason@firez.one>
Co-authored-by: Jamil <jamilbk@users.noreply.github.com>

* chore: update logs doc

* chore: apply suggestions from code review

Co-authored-by: Jamil <jamilbk@users.noreply.github.com>
Signed-off-by: Jason G <jason@firez.one>

* chore: line length and log description

* chore: rename debug logs

* chore: apply suggestions from code review

Co-authored-by: Jamil <jamilbk@users.noreply.github.com>
Signed-off-by: Jason G <jason@firez.one>

* Docs - Add draft whitelist sso doc (#1185)

* doc: adding whitelist sso doc

redo of https://github.com/firezone/firezone/pull/995

* docs: add seo titles

* docs: improve titles

* grammar fixes

* fix trailing whitespace

apparently my vscode plugin does not find trailing whitespace in front matter

* put doc in draftmode

* add note on wireguard client apps

* Revert "add note on wireguard client apps"

This reverts commit 9013ce1c3b1bcb8b825f0fcbb1c5fe7e050cae82.

* Apply suggestions from code review

Co-authored-by: Jamil <jamilbk@users.noreply.github.com>
Signed-off-by: Jason G <jason@firez.one>

Signed-off-by: Jason G <jason@firez.one>
Co-authored-by: Jamil <jamilbk@users.noreply.github.com>

* chore: apply suggestions from code review

Co-authored-by: Jamil <jamilbk@users.noreply.github.com>
Signed-off-by: Jason G <jason@firez.one>

* chore: Update docs/docs/user-guides/client-instructions.mdx

Co-authored-by: Jamil <jamilbk@users.noreply.github.com>
Signed-off-by: Jason G <jason@firez.one>

* chore: update title capitalization and other small fixes

* Apply suggestions from code review

Signed-off-by: Jamil <jamilbk@users.noreply.github.com>

Signed-off-by: Jason G <jason@firez.one>
Signed-off-by: Jamil <jamilbk@users.noreply.github.com>
Co-authored-by: Jamil <jamilbk@users.noreply.github.com>
This commit is contained in:
Jason G
2022-12-18 19:07:11 -08:00
committed by GitHub
parent 6978504da0
commit 5f6685c5aa
37 changed files with 483 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
docs/docs/administer/debug-logs.mdx Normal file
View File

@@ -0,0 +1,61 @@
---
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)
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.

2
docs/docs/administer/migrate.mdx
View File

@@ -3,6 +3,8 @@ 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/#supported-commercial-distributions).
As such, Omnibus-based deployments

4
docs/docs/administer/regen-keys.mdx
View File

@@ -10,7 +10,7 @@ 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
## Regenerate secrets
:::warning
Replacing the `DATABASE_ENCRYPTION_KEY` will render all encrypted data in the
@@ -47,7 +47,7 @@ sudo firezone-ctl reconfigure
</TabItem>
</Tabs>
## Regenerate WireGuard Private Key
## Regenerate WireGuard private key
:::warning
Replacing the WireGuard private key will render all existing device configs

86
docs/docs/administer/troubleshoot.mdx
View File

@@ -1,13 +1,31 @@
---
title: Troubleshoot
sidebar_position: 6
description: Troubleshoot common connectivity and configuration issues with Firezone's WireGuard®-based secure access platform.
---
For any problems that arise, a good first bet is to check the Firezone logs.
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`.
## Application Crash Loop Preventing Config Changes
</TabItem>
</Tabs>
## Application crash loop preventing config changes
In cases where the application is crash looping because of corrupt, inaccessible, or
invalid data in the DB, you can try clearing the affected fields.
@@ -24,7 +42,7 @@ Similarly, to clear SAML configs:
psql -d firezone -h 127.0.0.1 -U postgres -c "UPDATE configurations SET saml_providers = '{}'"
```
## Debugging Portal Websocket Connectivity Issues
## Debugging portal WebSocket connectivity issues
The portal UI requires a secure websocket connection to function. To facilitate
this, the Firezone phoenix service checks the `Host` header for inbound
@@ -45,9 +63,12 @@ to be in your reverse proxy configuration.
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 firezoen-ctl tail phoenix`
* `sudo firezone-ctl tail phoenix`
If the websocket connection is successful, you should see output in the
`phoenix` service logs similar the following:
@@ -65,13 +86,16 @@ If the websocket connection is successful, you should see output in the
2022-09-23_15:05:47.35065 Parameters: %{"token" => "SFMyNTY.g2gDYQFuBgB6HeJqgwFiAAFRgA.zSG7pefm-Vgf_zvduxa5E9VK4s8PKqzc0xBDGNx5FQE", "user_agent" => "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:106.0) Gecko/20100101 Firefox/106.0"}
```
## Debugging WireGuard Connectivity Issues
</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
### 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
@@ -108,6 +132,56 @@ To Action From
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">
First change directory to your Firezone root, 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 in CLI
For production deployments, we recommend adding a TOTP-based second factor to
admin accounts. If you promoted an account authenticated through an identity
provider, you can consider disabling local authentication for additional
security.
If 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, run the following query 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'"
```
## Need additional help?
Try asking on one of our community-powered support channels:

6
docs/docs/authenticate/README.mdx
View File

@@ -14,7 +14,7 @@ If your Identity Provider doesn't work with the methods listed above,
[contact us](https://www.firezone.dev/contact/sales) about custom integrations.
:::
## Integrate an SSO Provider
## Integrate an SSO provider
We've included instructions on how to set up Firezone with several popular
identity providers using our Generic OIDC integration:
@@ -71,7 +71,7 @@ would generate the following URLs:
These URLs 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
## 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
@@ -90,7 +90,7 @@ VPN session and sign in to the Firezone portal (URL specified during
See detailed Client Instructions on how to re-authenticate your session
[here](../user-guides/client-instructions).
#### VPN Connection Status
#### VPN connection status
A user's connection status is shown on the Users page under the table column
`VPN Connection`. The connection statuses are:

4
docs/docs/authenticate/local-auth.mdx
View File

@@ -3,6 +3,8 @@ title: Local Authentication
sidebar_position: 1
---
# Local authentication (username & 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.
@@ -12,7 +14,7 @@ For production installations, we highly recommend [enabling TOTP-based MFA](/aut
for any accounts using the local authentication method.
:::
## Disabling Local Authentication
## Disabling local authentication
If you wish to completely disable local authentication in favor of an SSO-only
approach, see our [OIDC](/authenticate/oidc/) or [SAML](/authenticate/saml/) guides.

7
docs/docs/authenticate/multi-factor.mdx
View File

@@ -1,8 +1,13 @@
---
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
@@ -23,7 +28,7 @@ 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 Identity Provider
## 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

12
docs/docs/authenticate/oidc/README.mdx
View File

@@ -1,11 +1,17 @@
---
title: OpenID Connect
sidebar_position: 10
description:
Enforce single sign-on with your identity provider. Integrate
providers like Okta, Google, Azure, and JumpCloud using Firezone's
OIDC connector.
---
# Integrate your identity provider using OIDC
Firezone supports Single Sign-On (SSO) via OpenID Connect (OIDC).
## Provider Support
## 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
@@ -25,7 +31,7 @@ The following OIDC providers are known to work well with Firezone:
| [Zitadel](zitadel) | Untested but known to work | |
| [Authentik](https://goauthentik.io/) | Untested but known to work | |
## General Instructions
## 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:
@@ -51,7 +57,7 @@ Firezone supports Proof Key for Code Exchange (PKCE) for increased login securit
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
### 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.

6
docs/docs/authenticate/oidc/auth0.mdx
View File

@@ -1,8 +1,14 @@
---
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:

6
docs/docs/authenticate/oidc/azuread.mdx
View File

@@ -1,8 +1,14 @@
---
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:

6
docs/docs/authenticate/oidc/google.mdx
View File

@@ -1,8 +1,14 @@
---
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:

6
docs/docs/authenticate/oidc/keycloak.mdx
View File

@@ -1,8 +1,14 @@
---
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:

6
docs/docs/authenticate/oidc/okta.mdx
View File

@@ -1,8 +1,14 @@
---
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:

6
docs/docs/authenticate/oidc/onelogin.mdx
View File

@@ -1,8 +1,14 @@
---
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:

6
docs/docs/authenticate/oidc/zitadel.mdx
View File

@@ -1,8 +1,14 @@
---
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:

12
docs/docs/authenticate/saml/README.mdx
View File

@@ -1,11 +1,17 @@
---
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.
## Provider Support
## Supported identity providers
In general, most identity providers that support SAML 2.0 should work with
Firezone.
@@ -62,7 +68,7 @@ and run `firezone-ctl reconfigure` to pick up the changes.
</TabItem>
</Tabs>
## General Instructions
## 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
@@ -71,7 +77,7 @@ SAML integration.
Use these general instructions to configure a SAML connector for a provider not listed
above.
### IdP Metadata Document
### 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.

7
docs/docs/authenticate/saml/google.mdx
View File

@@ -1,9 +1,14 @@
---
title: Google Workspace
sidebar_position: 2
description: Firezone's WireGuard®-based remote access platform supports using Google as a single sign-on provider using a SAML 2.0 connector.
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)
:::note
This guide assumes you have completed the prerequisite steps
(e.g. generate self-signed X.509 certificates) outlined [here](/authenticate/saml#prerequisites).

7
docs/docs/authenticate/saml/jumpcloud.mdx
View File

@@ -1,9 +1,14 @@
---
title: JumpCloud
sidebar_position: 4
description: Firezone's WireGuard®-based remote access platform supports using JumpCloud as a single sign-on provider using a SAML 2.0 connector.
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).

7
docs/docs/authenticate/saml/okta.mdx
View File

@@ -1,9 +1,14 @@
---
title: Okta
sidebar_position: 1
description: Firezone's WireGuard®-based remote access platform supports using Okta as a single sign-on provider using a SAML 2.0 connector.
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).

7
docs/docs/authenticate/saml/onelogin.mdx
View File

@@ -1,9 +1,14 @@
---
title: OneLogin
sidebar_position: 3
description: Firezone's WireGuard based remote access platform supports using OneLogin as a single sign-on provider using a SAML 2.0 connector.
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).

11
docs/docs/deploy/README.mdx
View File

@@ -1,12 +1,17 @@
---
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 about a minute.
Read more below to get started.
## Deployment Methods
## Deployment methods
You have two options for deploying Firezone:
@@ -24,7 +29,7 @@ Firezone. To transition to Docker from Omnibus today, follow our [migration guid
](../administer/migrate).
:::
## Prepare to Deploy
## Prepare to deploy
Regardless of which deployment method you choose, you'll need to follow the
preparation steps below before deploying Firezone to production.
@@ -87,7 +92,7 @@ See the
[configuration file reference](../reference/configuration-file)
for details.
### Resource Requirements
### Resource requirements
We recommend **starting with 1 vCPU and 1 GB of RAM and scaling up** as the
number of users and devices grows.

2
docs/docs/deploy/configure.mdx
View File

@@ -3,6 +3,8 @@ title: Configure
sidebar_position: 5
---
# Configure Firezone
There are two types of configuration in Firezone:
* [Runtime configuration](#runtime-configuration): Application configuration

12
docs/docs/deploy/docker/README.mdx
View File

@@ -1,8 +1,13 @@
---
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):
@@ -125,7 +130,12 @@ 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.
Firezone handles this for you by default.
## Step 5: Install Client Apps
## 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:

15
docs/docs/deploy/omnibus/README.mdx
View File

@@ -1,8 +1,13 @@
---
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
@@ -38,11 +43,11 @@ with Firezone’s operation. For help troubleshooting connectivity issues, see t
[troubleshooting guide](../../administer/troubleshoot).
:::
## Step 2: Install Server
## Step 2: Install server
After prerequisites are satisfied, you're ready to install the Firezone Server.
### Option 1: Automatic Install
### Option 1: Automatic install
The easiest way to get started using Firezone is via the automatic installation
script below.
@@ -110,7 +115,7 @@ If the automatic install script fails, try these steps to install Firezone from
1. Follow the [bootstrap instructions](#bootstrap-firezone) to setup Firezone.
### Option 3: Manual Install
### Option 3: Manual install
If all else fails, try these steps to install Firezone manually.
@@ -156,7 +161,7 @@ If all else fails, try these steps to install Firezone manually.
Find solutions to common issues during deployment in [Troubleshoot
](../../administer/troubleshoot).
## Step 3: Install Client Apps
## Step 3: Install client apps
Once successfully deployed, users and devices can be added to
connect to the VPN server:
@@ -176,7 +181,7 @@ if your issue is covered there. If you are unable to resolve the issue:
* Report bugs or propose new features on [Github
](https://github.com/firezone/firezone)
## Post Setup
## Post setup
Congrats! You have completed the setup, but there's a lot more you can do with
Firezone:

2
docs/docs/deploy/security-considerations.mdx
View File

@@ -3,6 +3,8 @@ 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

23
docs/docs/reference/_audit-logs.mdx Normal file
View File

@@ -0,0 +1,23 @@
---
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)
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.

11
docs/docs/reference/configuration-file.mdx
View File

@@ -1,8 +1,17 @@
---
title: Configuration File
sidebar_position: 1
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.

4
docs/docs/reference/env-vars.mdx
View File

@@ -1,8 +1,10 @@
---
title: Environment Variables
sidebar_position: 2
sidebar_position: 1
---
# Docker environment variables
Most day-to-day config of Firezone can (and should) be done via the
Firezone Web UI.

7
docs/docs/reference/firewall-templates/README.mdx
View File

@@ -6,3 +6,10 @@ sidebar_position: 9
Firewall templates to secure the Firezone server 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}/>
```

2
docs/docs/user-guides/add-devices.mdx
View File

@@ -3,6 +3,8 @@ 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.

2
docs/docs/user-guides/add-users.mdx
View File

@@ -3,6 +3,8 @@ 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 is done through the Web UI.

35
docs/docs/user-guides/client-instructions.mdx
View File

@@ -1,14 +1,23 @@
---
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.
---
## Install and Setup
# 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
### Step 1: Install the native WireGuard client
Firezone is compatible with the official WireGuard clients found here:
@@ -20,7 +29,7 @@ Firezone is compatible with the official WireGuard clients found here:
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
### 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.
@@ -31,7 +40,7 @@ administrator. This URL will be specific to your company
![Firezone Okta SSO Login](https://user-images.githubusercontent.com/52545545/156855886-5a4a0da7-065c-4ec1-af33-583dff4dbb72.gif)
### Step 3 - Add the config to the client
### Step 3: Enable on boot (optional)
Open the WireGuard client and import the `.conf` file.
Activate the VPN session by toggling the `Activate` switch.
@@ -48,11 +57,11 @@ follow the steps below. You will need:
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 1: Deactivate VPN session
![WireGuard Deactivate](https://user-images.githubusercontent.com/52545545/156859259-a3d386ce-b304-4caa-96e6-a8e7ca96d098.png)
### Step 2 - Re-authenticate
### 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,
@@ -60,7 +69,7 @@ click the `Reauthenticate` button, then sign in again.
![re-authenticate](https://user-images.githubusercontent.com/52545545/155812962-9b8688c1-00af-41e4-96c3-8fb52f840aed.gif)
### Step 3 - Activate VPN session
### Step 3: Activate VPN session
![Activate Session](https://user-images.githubusercontent.com/52545545/156859636-fde95fc5-5b9c-4697-9108-2f277ed3fbef.png)
@@ -79,7 +88,7 @@ ipv6.method: method "auto" is not supported for WireGuard
:::
### Step 1 - Install the WireGuard Tools
### 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`.
@@ -105,7 +114,7 @@ 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
### Step 2: Download configuration
The device config file can either be obtained from your Firezone administrator
or self-generated via the Firezone portal.
@@ -116,7 +125,7 @@ administrator. This URL will be specific to your company
![Firezone Okta SSO Login](https://user-images.githubusercontent.com/52545545/156855886-5a4a0da7-065c-4ec1-af33-583dff4dbb72.gif)
### Step 3 - Import configuration
### Step 3: Import configuration
Using `nmcli`, import the downloaded configuration file:
@@ -134,7 +143,7 @@ nmcli connection modify [old name] connection.id [new name]
:::
### Step 4 - Connect/disconnect
### Step 4: Connect/disconnect
To connect to the VPN via the command line:
@@ -151,7 +160,7 @@ nmcli connection down [vpn name]
If using a GUI, the relevant Network Manager applet can also be used to control
the connection.
### Auto Connection
### Auto connection
The VPN connection can be set to automatically connect by setting the `autoconnect`
option to `yes`:
@@ -166,7 +175,7 @@ To disable the automatic connection set it back to `no`:
nmcli connection modify [vpn name] connection.autoconnect no
```
## Enable Multi-Factor Authentication
## 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

5
docs/docs/user-guides/egress-rules.mdx
View File

@@ -1,8 +1,13 @@
---
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.

25
docs/docs/user-guides/use-cases/nat-gateway.mdx → docs/docs/user-guides/use-cases/nat-gateway/README.mdx
View File

@@ -1,8 +1,11 @@
---
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:
@@ -15,12 +18,10 @@ This is commonly used in the following scenarios:
This guide will walk through a simple example restricting access for a
self-hosted web app to a single whitelisted static IP running Firezone.
In this example the protected resource and Firezone are
in separate VPC regions.
This arrangement is commonly done in place of maintaining an IP whitelist for
multiple end users, which may become labor intensive to manage as the access
list grows.
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.
![Architecture](https://user-images.githubusercontent.com/52545545/154868328-688067dd-deca-4548-ac9d-f6ffe7eacf86.png)
@@ -31,7 +32,9 @@ 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.
### Step 1 - Deploy Firezone server
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
@@ -42,7 +45,7 @@ for details on deploying Firezone. Specific to AWS, ensure:
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`.
In this case, the IP is `52.202.88.54`.
![Allocate Elastic IP](https://user-images.githubusercontent.com/52545545/154821256-9335703b-a120-4a9d-b9f5-bbca673cef63.png)
@@ -58,15 +61,11 @@ 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
### Step 3: Route traffic to the protected resource through the VPN server
By default all traffic from users will be routed 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`.
### Related Guides
* [Authenticate](/authenticate/)

89
docs/docs/user-guides/use-cases/nat-gateway/_whitelist-sso.mdx Normal file
View File

@@ -0,0 +1,89 @@
---
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**.
![network zone](https://user-images.githubusercontent.com/52545545/193468881-d8945fb3-8a7e-45fc-88e2-9856473894b5.png)
### 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.
![sign on policy](https://user-images.githubusercontent.com/52545545/193468882-800e9baf-757f-485f-bb39-a1492a11f612.png)
### 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.
![associate policy](https://user-images.githubusercontent.com/52545545/193468877-f49412e1-3961-497d-9b8c-f5d003f9857d.png)
### 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.
![vpn notification](https://user-images.githubusercontent.com/52545545/193468874-ec3ef643-fb37-456b-8e37-df138125d1c7.png)

1
docs/docs/user-guides/use-cases/reverse-tunnel.mdx
View File

@@ -1,6 +1,7 @@
---
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

45
docs/docs/user-guides/use-cases/split-tunnel.mdx
View File

@@ -1,23 +1,28 @@
---
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 server.
through the VPN.
## Step 1 - Configure Allowed IPs
Firezone sets the `Allowed IPs` field so traffic destined for
specific IPs are encrypted and routed through the gateway.
The `Allowed IPs` field found on the `/settings/default` page determines the IP
ranges for which the client will route network traffic. Modifications to this
field will apply only to new WireGuard tunnel configurations generated by Firezone.
## Step 1: Set AllowedIPs
AllowedIPs can be set globally on the `/settings/default` page or individually
for each device during creation. Changes will only apply to new WireGuard
tunnel configurations generated by Firezone.
![set split tunneling defaults](https://user-images.githubusercontent.com/52545545/154814549-bb686ffe-ea82-4af8-a2a4-5e0b4013dec7.png)
The default value is `0.0.0.0/0, ::/0`, which routes all network traffic
from the client to the VPN server.
Some examples of values in this field are:
- `0.0.0.0/0, ::/0` - all network traffic will be routed to the VPN server.
@@ -32,10 +37,26 @@ When deciding where to route a packet, Firezone chooses the egress
interface corresponding to the most specific route first.
:::
## Step 2 - Regenerate WireGuard configurations
## Step 2: Set the DNS server(s) (optional)
To update existing user devices with the new split tunnel configuration,
users will need to regenerate the configuration files
and add them to their native WireGuard client.
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.