From 5f6685c5aab092e6e0526fa8d08c6d9738878de1 Mon Sep 17 00:00:00 2001 From: Jason G Date: Sun, 18 Dec 2022 19:07:11 -0800 Subject: [PATCH] General Docs Improvements (#1194) * 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 Signed-off-by: Jason G * add descriptions to client instructions Signed-off-by: Jason G Co-authored-by: Jamil * chore: update logs doc * chore: apply suggestions from code review Co-authored-by: Jamil Signed-off-by: Jason G * chore: line length and log description * chore: rename debug logs * chore: apply suggestions from code review Co-authored-by: Jamil Signed-off-by: Jason G * 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 Signed-off-by: Jason G Signed-off-by: Jason G Co-authored-by: Jamil * chore: apply suggestions from code review Co-authored-by: Jamil Signed-off-by: Jason G * chore: Update docs/docs/user-guides/client-instructions.mdx Co-authored-by: Jamil Signed-off-by: Jason G * chore: update title capitalization and other small fixes * Apply suggestions from code review Signed-off-by: Jamil Signed-off-by: Jason G Signed-off-by: Jamil Co-authored-by: Jamil --- docs/docs/administer/debug-logs.mdx | 61 +++++++++++++ docs/docs/administer/migrate.mdx | 2 + docs/docs/administer/regen-keys.mdx | 4 +- docs/docs/administer/troubleshoot.mdx | 86 ++++++++++++++++-- docs/docs/authenticate/README.mdx | 6 +- docs/docs/authenticate/local-auth.mdx | 4 +- docs/docs/authenticate/multi-factor.mdx | 7 +- docs/docs/authenticate/oidc/README.mdx | 12 ++- docs/docs/authenticate/oidc/auth0.mdx | 6 ++ docs/docs/authenticate/oidc/azuread.mdx | 6 ++ docs/docs/authenticate/oidc/google.mdx | 6 ++ docs/docs/authenticate/oidc/keycloak.mdx | 6 ++ docs/docs/authenticate/oidc/okta.mdx | 6 ++ docs/docs/authenticate/oidc/onelogin.mdx | 6 ++ docs/docs/authenticate/oidc/zitadel.mdx | 6 ++ docs/docs/authenticate/saml/README.mdx | 12 ++- docs/docs/authenticate/saml/google.mdx | 7 +- docs/docs/authenticate/saml/jumpcloud.mdx | 7 +- docs/docs/authenticate/saml/okta.mdx | 7 +- docs/docs/authenticate/saml/onelogin.mdx | 7 +- docs/docs/deploy/README.mdx | 11 ++- docs/docs/deploy/configure.mdx | 2 + docs/docs/deploy/docker/README.mdx | 12 ++- docs/docs/deploy/omnibus/README.mdx | 15 ++-- docs/docs/deploy/security-considerations.mdx | 2 + docs/docs/reference/_audit-logs.mdx | 23 +++++ docs/docs/reference/configuration-file.mdx | 11 ++- docs/docs/reference/env-vars.mdx | 4 +- .../reference/firewall-templates/README.mdx | 7 ++ docs/docs/user-guides/add-devices.mdx | 2 + docs/docs/user-guides/add-users.mdx | 2 + docs/docs/user-guides/client-instructions.mdx | 35 +++++--- docs/docs/user-guides/egress-rules.mdx | 5 ++ .../README.mdx} | 25 +++--- .../use-cases/nat-gateway/_whitelist-sso.mdx | 89 +++++++++++++++++++ .../user-guides/use-cases/reverse-tunnel.mdx | 1 + .../user-guides/use-cases/split-tunnel.mdx | 45 +++++++--- 37 files changed, 483 insertions(+), 72 deletions(-) create mode 100644 docs/docs/administer/debug-logs.mdx create mode 100644 docs/docs/reference/_audit-logs.mdx rename docs/docs/user-guides/use-cases/{nat-gateway.mdx => nat-gateway/README.mdx} (80%) create mode 100644 docs/docs/user-guides/use-cases/nat-gateway/_whitelist-sso.mdx diff --git a/docs/docs/administer/debug-logs.mdx b/docs/docs/administer/debug-logs.mdx new file mode 100644 index 000000000..80d28eb6e --- /dev/null +++ b/docs/docs/administer/debug-logs.mdx @@ -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. diff --git a/docs/docs/administer/migrate.mdx b/docs/docs/administer/migrate.mdx index f79fb167d..d871a9e43 100644 --- a/docs/docs/administer/migrate.mdx +++ b/docs/docs/administer/migrate.mdx @@ -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 diff --git a/docs/docs/administer/regen-keys.mdx b/docs/docs/administer/regen-keys.mdx index ee78cf885..f4d65988e 100644 --- a/docs/docs/administer/regen-keys.mdx +++ b/docs/docs/administer/regen-keys.mdx @@ -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 -## Regenerate WireGuard Private Key +## Regenerate WireGuard private key :::warning Replacing the WireGuard private key will render all existing device configs diff --git a/docs/docs/administer/troubleshoot.mdx b/docs/docs/administer/troubleshoot.mdx index c03d6d037..abce10ec3 100644 --- a/docs/docs/administer/troubleshoot.mdx +++ b/docs/docs/administer/troubleshoot.mdx @@ -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. + + + + +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. + + + + Firezone logs are stored in `/var/log/firezone` and can be viewed with `sudo firezone-ctl tail`. -## Application Crash Loop Preventing Config Changes + + + +## 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: + + + * 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 + + + +## 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. + + + + +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. + + + + + +Run the following command to reset the password on the default admin user. + +```shell +sudo firezone-ctl create-or-reset-admin +``` + + + + +## 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: diff --git a/docs/docs/authenticate/README.mdx b/docs/docs/authenticate/README.mdx index 46d5be19c..4d92eeea1 100644 --- a/docs/docs/authenticate/README.mdx +++ b/docs/docs/authenticate/README.mdx @@ -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: diff --git a/docs/docs/authenticate/local-auth.mdx b/docs/docs/authenticate/local-auth.mdx index cd9afcdde..682e5d198 100644 --- a/docs/docs/authenticate/local-auth.mdx +++ b/docs/docs/authenticate/local-auth.mdx @@ -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. diff --git a/docs/docs/authenticate/multi-factor.mdx b/docs/docs/authenticate/multi-factor.mdx index dacbf4563..e402a1df4 100644 --- a/docs/docs/authenticate/multi-factor.mdx +++ b/docs/docs/authenticate/multi-factor.mdx @@ -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 diff --git a/docs/docs/authenticate/oidc/README.mdx b/docs/docs/authenticate/oidc/README.mdx index dcbd58bcf..c991dc9cc 100644 --- a/docs/docs/authenticate/oidc/README.mdx +++ b/docs/docs/authenticate/oidc/README.mdx @@ -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. diff --git a/docs/docs/authenticate/oidc/auth0.mdx b/docs/docs/authenticate/oidc/auth0.mdx index 1aa495a31..2dd0c486b 100644 --- a/docs/docs/authenticate/oidc/auth0.mdx +++ b/docs/docs/authenticate/oidc/auth0.mdx @@ -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: diff --git a/docs/docs/authenticate/oidc/azuread.mdx b/docs/docs/authenticate/oidc/azuread.mdx index 463be9716..e8a85d8da 100644 --- a/docs/docs/authenticate/oidc/azuread.mdx +++ b/docs/docs/authenticate/oidc/azuread.mdx @@ -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: diff --git a/docs/docs/authenticate/oidc/google.mdx b/docs/docs/authenticate/oidc/google.mdx index e7d49d8bf..508082f3b 100644 --- a/docs/docs/authenticate/oidc/google.mdx +++ b/docs/docs/authenticate/oidc/google.mdx @@ -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: diff --git a/docs/docs/authenticate/oidc/keycloak.mdx b/docs/docs/authenticate/oidc/keycloak.mdx index 8aafbbcbe..8ba28e0e4 100644 --- a/docs/docs/authenticate/oidc/keycloak.mdx +++ b/docs/docs/authenticate/oidc/keycloak.mdx @@ -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: diff --git a/docs/docs/authenticate/oidc/okta.mdx b/docs/docs/authenticate/oidc/okta.mdx index 48bf1b820..e00e5ecfb 100644 --- a/docs/docs/authenticate/oidc/okta.mdx +++ b/docs/docs/authenticate/oidc/okta.mdx @@ -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: diff --git a/docs/docs/authenticate/oidc/onelogin.mdx b/docs/docs/authenticate/oidc/onelogin.mdx index 814aa0fbb..ab7c0e64c 100644 --- a/docs/docs/authenticate/oidc/onelogin.mdx +++ b/docs/docs/authenticate/oidc/onelogin.mdx @@ -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: diff --git a/docs/docs/authenticate/oidc/zitadel.mdx b/docs/docs/authenticate/oidc/zitadel.mdx index 2fe99b689..67e327506 100644 --- a/docs/docs/authenticate/oidc/zitadel.mdx +++ b/docs/docs/authenticate/oidc/zitadel.mdx @@ -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: diff --git a/docs/docs/authenticate/saml/README.mdx b/docs/docs/authenticate/saml/README.mdx index fb3804805..4b0bd732d 100644 --- a/docs/docs/authenticate/saml/README.mdx +++ b/docs/docs/authenticate/saml/README.mdx @@ -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. -## 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. diff --git a/docs/docs/authenticate/saml/google.mdx b/docs/docs/authenticate/saml/google.mdx index 742e8c3c1..cd2dec279 100644 --- a/docs/docs/authenticate/saml/google.mdx +++ b/docs/docs/authenticate/saml/google.mdx @@ -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). diff --git a/docs/docs/authenticate/saml/jumpcloud.mdx b/docs/docs/authenticate/saml/jumpcloud.mdx index 71a2c44d1..3446ee685 100644 --- a/docs/docs/authenticate/saml/jumpcloud.mdx +++ b/docs/docs/authenticate/saml/jumpcloud.mdx @@ -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). diff --git a/docs/docs/authenticate/saml/okta.mdx b/docs/docs/authenticate/saml/okta.mdx index 32f02dcfb..c42c932f9 100644 --- a/docs/docs/authenticate/saml/okta.mdx +++ b/docs/docs/authenticate/saml/okta.mdx @@ -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). diff --git a/docs/docs/authenticate/saml/onelogin.mdx b/docs/docs/authenticate/saml/onelogin.mdx index b70a8235a..108bba756 100644 --- a/docs/docs/authenticate/saml/onelogin.mdx +++ b/docs/docs/authenticate/saml/onelogin.mdx @@ -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). diff --git a/docs/docs/deploy/README.mdx b/docs/docs/deploy/README.mdx index d0584fe11..29c71bdd4 100644 --- a/docs/docs/deploy/README.mdx +++ b/docs/docs/deploy/README.mdx @@ -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. diff --git a/docs/docs/deploy/configure.mdx b/docs/docs/deploy/configure.mdx index 688c44dae..a7afa2cf4 100644 --- a/docs/docs/deploy/configure.mdx +++ b/docs/docs/deploy/configure.mdx @@ -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 diff --git a/docs/docs/deploy/docker/README.mdx b/docs/docs/deploy/docker/README.mdx index 7245261f7..af584b0df 100644 --- a/docs/docs/deploy/docker/README.mdx +++ b/docs/docs/deploy/docker/README.mdx @@ -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: diff --git a/docs/docs/deploy/omnibus/README.mdx b/docs/docs/deploy/omnibus/README.mdx index bbbdc2b50..2dcfe5ab1 100644 --- a/docs/docs/deploy/omnibus/README.mdx +++ b/docs/docs/deploy/omnibus/README.mdx @@ -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: diff --git a/docs/docs/deploy/security-considerations.mdx b/docs/docs/deploy/security-considerations.mdx index 812cdf5f4..811ac065e 100644 --- a/docs/docs/deploy/security-considerations.mdx +++ b/docs/docs/deploy/security-considerations.mdx @@ -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 diff --git a/docs/docs/reference/_audit-logs.mdx b/docs/docs/reference/_audit-logs.mdx new file mode 100644 index 000000000..e924fd2ae --- /dev/null +++ b/docs/docs/reference/_audit-logs.mdx @@ -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. diff --git a/docs/docs/reference/configuration-file.mdx b/docs/docs/reference/configuration-file.mdx index 55a05c571..d72a85ac6 100644 --- a/docs/docs/reference/configuration-file.mdx +++ b/docs/docs/reference/configuration-file.mdx @@ -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. diff --git a/docs/docs/reference/env-vars.mdx b/docs/docs/reference/env-vars.mdx index a60d1707d..3a5f66345 100644 --- a/docs/docs/reference/env-vars.mdx +++ b/docs/docs/reference/env-vars.mdx @@ -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. diff --git a/docs/docs/reference/firewall-templates/README.mdx b/docs/docs/reference/firewall-templates/README.mdx index 8a6fcb3c1..fdf07e81c 100644 --- a/docs/docs/reference/firewall-templates/README.mdx +++ b/docs/docs/reference/firewall-templates/README.mdx @@ -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'; + + +``` diff --git a/docs/docs/user-guides/add-devices.mdx b/docs/docs/user-guides/add-devices.mdx index 356d393d3..39dde1133 100644 --- a/docs/docs/user-guides/add-devices.mdx +++ b/docs/docs/user-guides/add-devices.mdx @@ -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. diff --git a/docs/docs/user-guides/add-users.mdx b/docs/docs/user-guides/add-users.mdx index 618f6fd5b..ed48134b3 100644 --- a/docs/docs/user-guides/add-users.mdx +++ b/docs/docs/user-guides/add-users.mdx @@ -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. diff --git a/docs/docs/user-guides/client-instructions.mdx b/docs/docs/user-guides/client-instructions.mdx index fc4095767..f7c34a580 100644 --- a/docs/docs/user-guides/client-instructions.mdx +++ b/docs/docs/user-guides/client-instructions.mdx @@ -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 diff --git a/docs/docs/user-guides/egress-rules.mdx b/docs/docs/user-guides/egress-rules.mdx index e869f6216..e5f27ba91 100644 --- a/docs/docs/user-guides/egress-rules.mdx +++ b/docs/docs/user-guides/egress-rules.mdx @@ -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. diff --git a/docs/docs/user-guides/use-cases/nat-gateway.mdx b/docs/docs/user-guides/use-cases/nat-gateway/README.mdx similarity index 80% rename from docs/docs/user-guides/use-cases/nat-gateway.mdx rename to docs/docs/user-guides/use-cases/nat-gateway/README.mdx index ac70d2eb0..87c1a0ad5 100644 --- a/docs/docs/user-guides/use-cases/nat-gateway.mdx +++ b/docs/docs/user-guides/use-cases/nat-gateway/README.mdx @@ -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/) diff --git a/docs/docs/user-guides/use-cases/nat-gateway/_whitelist-sso.mdx b/docs/docs/user-guides/use-cases/nat-gateway/_whitelist-sso.mdx new file mode 100644 index 000000000..c35a5c486 --- /dev/null +++ b/docs/docs/user-guides/use-cases/nat-gateway/_whitelist-sso.mdx @@ -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. +--- + +# 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) diff --git a/docs/docs/user-guides/use-cases/reverse-tunnel.mdx b/docs/docs/user-guides/use-cases/reverse-tunnel.mdx index 0eb4661c6..90191a9f5 100644 --- a/docs/docs/user-guides/use-cases/reverse-tunnel.mdx +++ b/docs/docs/user-guides/use-cases/reverse-tunnel.mdx @@ -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 diff --git a/docs/docs/user-guides/use-cases/split-tunnel.mdx b/docs/docs/user-guides/use-cases/split-tunnel.mdx index 24323c05e..5f475b28b 100644 --- a/docs/docs/user-guides/use-cases/split-tunnel.mdx +++ b/docs/docs/user-guides/use-cases/split-tunnel.mdx @@ -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.