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

Remove docs in README to favor docs.firez.one

Browse Source
This commit is contained in:
Jamil Bou Kheir
2022-01-14 15:29:01 -08:00
parent 7f05d7a218
commit fe00de5766
15 changed files with 144 additions and 367 deletions
Download Patch File Download Diff File Expand all files Collapse all files

316
README.md
View File

@@ -29,317 +29,29 @@
![Architecture](https://user-images.githubusercontent.com/52545545/147286088-08b0d11f-d81d-4622-8145-179071d2f0fb.png)
**Important**: Ensure you're reading the correct version of this README for the
current version of Firezone you're running. Links to the README for past
versions:
# Documentation
* [0.1.19](https://github.com/firezone/firezone/tree/0.1.19)
* [0.1.18](https://github.com/firezone/firezone/tree/0.1.18)
* [0.1.17](https://github.com/firezone/firezone/tree/0.1.17)
* [0.1.16](https://github.com/firezone/firezone/tree/0.1.17)
* [0.1.15](https://github.com/firezone/firezone/tree/0.1.17)
Our documentation is now published at https://docs.firez.one. Please refer to
that to install, configure, and manage Firezone.
# Table of Contents
* [What is Firezone?](#what-is-firezone)
* [Features](#features)
* [Anti-features](#anti-features)
* [Deploying and Configuring](#deploying-and-configuring)
* [Supported Linux Distributions](#supported-linux-distributions)
* [Installation Instructions](#installation-instructions)
* [Configuration File](#configuration-file)
* [Using Firezone](#using-firezone)
* [Troubleshooting](#troubleshooting)
* [Upgrading](#upgrading)
* [Uninstalling](#uninstalling)
* [Client Setup and Usage](#client-setup-and-usage)
* [Adding Devices](#adding-devices)
* [Client Instructions](#client-instructions)
* [Getting Support](#getting-support)
* [Developing and Contributing](#developing-and-contributing)
# Get Help
If you're looking for help installing and configuring Firezone, we're happy to
help:
# What is Firezone?
[Firezone](https://www.firez.one/) is a Linux package to manage your WireGuard VPN through a simple web interface.
![firezone-usage](https://user-images.githubusercontent.com/52545545/147392573-fe4cb936-a0a8-436f-a69b-c0a9587de58b.gif)
## Features
- **Fast:** Uses WireGuard to be [3-4 times](https://wireguard.com/performance/) faster than OpenVPN.
- **No dependencies:** All dependencies are bundled thanks to
[Chef Omnibus](https://github.com/chef/omnibus).
- **Simple:** Takes minutes to set up. Manage via a simple CLI.
- **Secure:** Runs unprivileged. HTTPS enforced. Encrypted cookies.
- **Firewall included:** Uses Linux [nftables](https://netfilter.org) to block
unwanted egress traffic.
## Anti-features
Firezone is **not:**
- An inbound firewall
- A tool for creating mesh networks
- A full-featured router
- An IPSec or OpenVPN server
# Deploying and Configuring
Firezone consists of a single distributable Linux package that you install and
manage yourself. Management of the Firezone installation is handled by the
`firezone-ctl` utility while management of the VPN and firewall themselves are
handled by the Web UI.
Firezone acts as a frontend to both the WireGuard kernel module and
[netfilter](https://netfilter.org) kernel subsystem. It creates a WireGuard
interface (by default called `wg-firezone`) and
`firezone` netfilter table and adds appropriate routes to the routing
table. Other programs that modify the Linux routing table or netfilter firewall
may interfere with Firezone's operation.
### SSL
Firezone requires a valid SSL certificate and a matching DNS record to run in
production. We recommend using [Let's Encrypt](https://letsencrypt.org) to
generate a free SSL cert for your domain.
### Security Considerations
Firezone is **beta** software. We highly recommend **limiting network access to
the Web UI** (by default port tcp/443) to prevent exposing it to the public Internet.
The WireGuard listen port (by default port udp/51821) should be exposed to allow user
devices to connect.
## Supported Linux Distributions
Firezone currently supports the following distributions and architectures:
| Name | Architectures | Status | Notes |
| --- | --- | --- | --- |
| AmazonLinux 2 | `amd64` | **Fully-supported** | See [AmazonLinux 2 Notes](#amazonlinux-2-notes) |
| CentOS 7 | `amd64` | **Fully-supported** | See [CentOS 7 Notes](#centos-7-notes) |
| CentOS 8 | `amd64` | **Fully-supported** | See [CentOS 8 Notes](#centos-8-notes |
| Debian 10 | `amd64` | **Fully-supported** | See [Debian 10 Notes](#debian-10-notes)|
| Debian 11 | `amd64` | **Fully-supported** | Works as-is |
| Fedora 33 | `amd64` | **Fully-supported** | Works as-is |
| Fedora 34 | `amd64` | **Fully-supported** | Works as-is |
| Ubuntu 18.04 | `amd64` | **Fully-supported** | See [Ubuntu 18.04 Notes](#ubuntu-1804-notes) |
| Ubuntu 20.04 | `amd64` | **Fully-supported** | Works as-is |
| openSUSE Leap 15.3 | `amd64` | **Fully-supported** | See [openSUSE Notes](#opensuse-notes) |
If your distro isn't listed here please
[open an issue](https://github.com/firezone/firezone/issues/new/choose) and let
us know. New distros are being supported on a regular basis and there's a good
chance yours will be added soon.
### AmazonLinux 2 Notes
Kernel upgrade required:
```bash
sudo amazon-linux-extras install -y kernel-5.10
```
### CentOS 7 Notes
Kernel upgrade to 4.19+ required. See [this guide
](https://medium.com/@nazishalam07/update-centos-kernel-3-10-to-5-13-latest-9462b4f1e62c)
for an example.
### CentOS 8 Notes
The WireGuard kernel module needs to be installed:
```bash
yum install elrepo-release epel-release
yum install kmod-wireguard
```
### Ubuntu 18.04 Notes
Kernel upgrade to 4.19+ required. E.g. `apt install linux-image-generic-hwe-18.04`
### Debian 10 Notes
Kernel upgrade to 4.19+ required. See [this guide
](https://jensd.be/968/linux/install-a-newer-kernel-in-debian-10-buster-stable)
for an example.
### openSUSE Notes
Firezone requires the `setcap` utility, but some recent openSUSE releases may
not have it installed by default. To fix, ensure `libcap-progs` is installed:
```bash
sudo zypper install libcap-progs
```
## Installation Instructions
Assuming you're running Linux kernel 4.19+ on one of the supported distros
listed above, follow these steps to setup and install Firezone:
1. [Install WireGuard](https://www.wireguard.com/install/) for your distro. If using Linux kernel 5.6 or higher, skip
this step.
2. Download the relevant package for your distribution from the
[releases page](https://github.com/firezone/firezone/releases).
3. Install with `sudo rpm -i firezone*.rpm` or `sudo dpkg -i firezone*.deb`
depending on your distro.
4. Bootstrap the application with `sudo firezone-ctl reconfigure`. This will initialize config files, set up needed services and generate the default configuration.
5. Edit the default configuration located at `/etc/firezone/firezone.rb`.
At a minimum, you'll need to review the following configuration variables:
```ruby
# Auto-generated based on the server's hostname.
# Set this to the FQDN used to access the Web UI.
default['firezone']['fqdn'] = 'firezone.example.com'
# ...
# Specify the path to your SSL cert and private key.
# If set to nil, a self-signed cert will be generated for you.
default['firezone']['ssl']['certificate'] = '/path/to/cert.pem'
default['firezone']['ssl']['certificate_key'] = '/path/to/key.pem'
```
6. Reconfigure the application to pick up the new changes: `sudo firezone-ctl reconfigure`.
7. Finally, create an admin user with `sudo firezone-ctl create-or-reset-admin`.
The login credentials will be printed to the console output.
8. Now you should be able to log into the web UI at the FQDN you specified in
step 5 above, e.g. `https://firezone.example.com`
## Configuration File
User-configurable settings can be found in `/etc/firezone/firezone.rb`.
Changing this file **requires re-running** `sudo firezone-ctl reconfigure` to pick up
the changes and apply them to the running system.
# Using Firezone
Your Firezone installation can be managed via the `firezone-ctl` command, as shown below. Most subcommands require prefixing with `sudo`.
```console
root@demo:~# firezone-ctl
I don't know that command.
omnibus-ctl: command (subcommand)
General Commands:
cleanse
Delete *all* firezone data, and start from scratch.
create-or-reset-admin
Resets the password for admin with email specified by default['firezone']['admin_email'] or creates a new admin if that email doesn't exist.
help
Print this help message.
reconfigure
Reconfigure the application.
reset-network
Resets nftables, WireGuard interface, and routing table back to Firezone defaults.
show-config
Show the configuration that would be generated by reconfigure.
teardown-network
Removes WireGuard interface and firezone nftables table.
uninstall
Kill all processes and uninstall the process supervisor (data will be preserved).
version
Display current version of Firezone
Service Management Commands:
graceful-kill
Attempt a graceful stop, then SIGKILL the entire process group.
hup
Send the services a HUP.
int
Send the services an INT.
kill
Send the services a KILL.
once
Start the services if they are down. Do not restart them if they stop.
restart
Stop the services if they are running, then start them again.
service-list
List all the services (enabled services appear with a *.)
start
Start services if they are down, and restart them if they stop.
status
Show the status of all the services.
stop
Stop the services, and do not restart them.
tail
Watch the service logs of all enabled services.
term
Send the services a TERM.
usr1
Send the services a USR1.
usr2
Send the services a USR2.
```
## Troubleshooting
For any problems that arise, a good first bet is to check the Firezone logs.
To view Firezone logs, run `sudo firezone-ctl tail`.
## Upgrading
Upgrading Firezone will disconnect all VPN connections and require shutting
down the Web UI. We recommend a maintenance window of about an hour in case
anything goes wrong during the upgrade.
To upgrade Firezone, simply download the new OS package, install it over the existing installation with `sudo dpkg -i firezone_X.X.X.deb` or
`sudo rpm -i firezone_X.X.X.rpm` and then run `sudo firezone-ctl reconfigure`.
Occasionally problems arise. If you hit any, please let us know by [filing an
issue](https://github.com/firezone/firezone/issues/new/choose).
### Upgrading from 0.1.x to 0.2.x
Firezone 0.2.x contains some configuration file changes that will need to be
handled manually if you're upgrading from 0.1.x. Run the commands below as root
to perform the needed changes to your `/etc/firezone/firezone.rb` file.
```bash
cp /etc/firezone/firezone.rb /etc/firezone/firezone.rb.bak
sed -i "s/\['enable'\]/\['enabled'\]/" /etc/firezone/firezone.rb
echo "default['firezone']['connectivity_checks']['enabled'] = true" >> /etc/firezone/firezone.rb
echo "default['firezone']['connectivity_checks']['interval'] = 3_600" >> /etc/firezone/firezone.rb
firezone-ctl reconfigure
firezone-ctl restart
```
## Uninstalling
To completely remove Firezone and its configuration files, run the [uninstall.sh
script](https://github.com/firezone/firezone/blob/master/scripts/uninstall.sh):
```bash
sudo /bin/bash -c "$(curl -fsSL https://github.com/firezone/firezone/raw/master/scripts/uninstall.sh)"
```
**Warning**: This will irreversibly destroy ALL Firezone data and can't be
undone.
# Client Setup and Usage
## Adding Devices
Add a device through the Web UI by clicking the "Add Device" button under `/devices` or `/users`. Once the device profile is created, you can send the WireGuard configuration file to the client.
## Client Instructions
Clients should download the latest version of the WireGuard client from https://www.wireguard.com/install/. Once installed, clients can import the tunnel via the `.conf` file sent by the administrator.
![Client Instructions](https://user-images.githubusercontent.com/52545545/147296703-a7fa8fce-33bb-42ef-83b3-1b8e9047d1d5.gif)
# Getting Support
For help, feedback or contributions please join our [
Discourse](https://discourse.firez.one). We're actively working to improve
Firezone, and the Discourse is the best way to coordinate our efforts.
* [Discussion Forums](https://discourse.firez.one/)
* [Public Slack Group](https://join.slack.com/t/firezone-users/shared_invite/zt-111043zus-j1lP_jP5ohv52FhAayzT6w)
* [Email Us](mailto:team@firez.one)
# Developing and Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).
## License
# Security Information
See [SECURITY.md](SECURITY.md).
# License
See [LICENSE](LICENSE).

4
docs/_config.yml
View File

@@ -51,6 +51,10 @@ gh_edit_branch: "master" # the branch that your docs is served from
gh_edit_source: docs # the source that your files originate from
gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
asset_urls:
architecture_diagram: "https://user-images.githubusercontent.com/52545545/147286088-08b0d11f-d81d-4622-8145-179071d2f0fb.png"
client_instructions: "https://user-images.githubusercontent.com/52545545/147296703-a7fa8fce-33bb-42ef-83b3-1b8e9047d1d5.gif"
# Aux links for the upper right navigation
aux_links:
"Ask a Question":

3
docs/assets/js/version-selector.js
View File

@@ -32,7 +32,8 @@ let populateSelect = function (versions) {
} else {
// Add version to path
window.location.href =
window.location.origin + e.target.value + window.location.pathname
window.location.origin + '/' +
e.target.value + window.location.pathname
}
})
})

12
docs/docs/get-started/client-setup.md
View File

@@ -1,7 +1,7 @@
---
layout: default
title: Client Setup
nav_order: 2
nav_order: 3
parent: Get Started
---
@@ -10,9 +10,13 @@ parent: Get Started
---
## Adding Devices
Add a device through the Web UI by clicking the "Add Device" button under `/devices` or `/users`. Once the device profile is created, you can send the WireGuard configuration file to the client.
Add a device through the Web UI by clicking the "Add Device" button under
`/devices` or `/users`. Once the device profile is created, you can send the
WireGuard configuration file to the client.
## Client Instructions
Clients should download the latest version of the WireGuard client from https://www.wireguard.com/install/. Once installed, clients can import the tunnel via the `.conf` file sent by the administrator.
Clients should download the latest version of the WireGuard client from
https://www.wireguard.com/install/. Once installed, clients can import the
tunnel via the `.conf` file sent by the administrator.
![Client Instructions](https://user-images.githubusercontent.com/52545545/147296703-a7fa8fce-33bb-42ef-83b3-1b8e9047d1d5.gif)
![Client Instructions]({{ site.asset_urls.client_instructions }})

2
docs/docs/get-started/index.md
View File

@@ -1,7 +1,7 @@
---
layout: default
title: Get Started
nav_order: 2
nav_order: 3
has_children: true
---

68
docs/docs/get-started/deploy.md → docs/docs/get-started/install.md
View File

@@ -1,15 +1,17 @@
---
layout: default
title: Deploy and Configure
nav_order: 1
title: Install
nav_order: 2
parent: Get Started
---
# Deploy and Configure
# Install
{: .no_toc }
---
**Important**: Ensure you've satisfied the [prerequisites]({% link docs/get-started/prerequisites.md %})
before following this guide.
## Table of Contents
{: .no_toc .text-delta }
@@ -18,33 +20,6 @@ parent: Get Started
---
Firezone consists of a single distributable Linux package that you install and
manage yourself. Management of the Firezone installation is handled by the
`firezone-ctl` utility while management of the VPN and firewall themselves are
handled by the Web UI.
Firezone acts as a frontend to both the WireGuard kernel module and
[netfilter](https://netfilter.org) kernel subsystem. It creates a WireGuard
interface (by default called `wg-firezone`) and
`firezone` netfilter table and adds appropriate routes to the routing
table. Other programs that modify the Linux routing table or netfilter firewall
may interfere with Firezone's operation.
### SSL
Firezone requires a valid SSL certificate and a matching DNS record to run in
production. We recommend using [Let's Encrypt](https://letsencrypt.org) to
generate a free SSL cert for your domain.
### Security Considerations
Firezone is **beta** software. We highly recommend **limiting network access to
the Web UI** (by default port tcp/443) to prevent exposing it to the public Internet.
The WireGuard listen port (by default port udp/51821) should be exposed to allow user
devices to connect.
## Supported Linux Distributions
Firezone currently supports the following distributions and architectures:
@@ -53,7 +28,7 @@ Firezone currently supports the following distributions and architectures:
| --- | --- | --- | --- |
| AmazonLinux 2 | `amd64` | **Fully-supported** | See [AmazonLinux 2 Notes](#amazonlinux-2-notes) |
| CentOS 7 | `amd64` | **Fully-supported** | See [CentOS 7 Notes](#centos-7-notes) |
| CentOS 8 | `amd64` | **Fully-supported** | Works as-is |
| CentOS 8 | `amd64` | **Fully-supported** | See [CentOS 8 Notes](#centos-8-notes) |
| Debian 10 | `amd64` | **Fully-supported** | See [Debian 10 Notes](#debian-10-notes)|
| Debian 11 | `amd64` | **Fully-supported** | Works as-is |
| Fedora 33 | `amd64` | **Fully-supported** | Works as-is |
@@ -81,13 +56,22 @@ Kernel upgrade to 4.19+ required. See [this guide
](https://medium.com/@nazishalam07/update-centos-kernel-3-10-to-5-13-latest-9462b4f1e62c)
for an example.
### CentOS 8 Notes
The WireGuard kernel module needs to be installed:
```bash
yum install elrepo-release epel-release
yum install kmod-wireguard
```
### Ubuntu 18.04 Notes
Kernel upgrade to 4.19+ required. E.g. `apt install linux-image-generic-hwe-18.04`
### Debian 10 Notes
Kernel upgrade to 4.19+ required. See [this guide
Kernel upgrade to 5.6+ required. See [this guide
](https://jensd.be/968/linux/install-a-newer-kernel-in-debian-10-buster-stable)
for an example.
@@ -96,14 +80,19 @@ for an example.
Firezone requires the `setcap` utility, but some recent openSUSE releases may
not have it installed by default. To fix, ensure `libcap-progs` is installed:
```bash
```shell
sudo zypper install libcap-progs
```
## Installation Instructions
**NOTE**: Firezone modifies the kernel netfilter and routing tables. Other
programs that modify the Linux routing table or netfilter firewall
will likely interfere with Firezone's operation.
Assuming you're running Linux kernel 4.19+ on one of the supported distros
listed above, follow these steps to setup and install Firezone:
listed above, follow these steps to install and configure Firezone for first
use:
1. [Install WireGuard](https://www.wireguard.com/install/) for your distro. If using Linux kernel 5.6 or higher, skip
this step.
@@ -120,8 +109,6 @@ listed above, follow these steps to setup and install Firezone:
# Set this to the FQDN used to access the Web UI.
default['firezone']['fqdn'] = 'firezone.example.com'
# ...
# Specify the path to your SSL cert and private key.
# If set to nil, a self-signed cert will be generated for you.
default['firezone']['ssl']['certificate'] = '/path/to/cert.pem'
@@ -133,9 +120,4 @@ listed above, follow these steps to setup and install Firezone:
8. Now you should be able to log into the web UI at the FQDN you specified in
step 5 above, e.g. `https://firezone.example.com`
## Configuration File
User-configurable settings can be found in `/etc/firezone/firezone.rb`.
Changing this file **requires re-running** `sudo firezone-ctl reconfigure` to pick up
the changes and apply them to the running system.
Next, proceed to [read about using Firezone]({% link docs/usage/index.md %}).

32
docs/docs/get-started/prerequisites.md Normal file
View File

@@ -0,0 +1,32 @@
---
layout: default
title: Prerequisites
nav_order: 1
parent: Get Started
---
# Prerequisites
---
Firezone requires the setup of a DNS record and matching SSL certificate to run
in production. Not using Firezone in production? [
Skip directly to the installation guide]({% link docs/get-started/install.md %}).
## Create a DNS record
Firezone requires a fully-qualified domain name (e.g. `firezone.company.com`)
for production use. You'll need to create the appropriate DNS record at your
registrar to achieve this. Typically this is either an A, CNAME, or AAAA record
depending on your requirements.
## Create an SSL certificate
While Firezone generates a self-signed SSL certificate for you on install,
you'll need a valid SSL certificate to use Firezone in a production capacity.
We recommend using [Let's Encrypt](https://letsencrypt.org) to
generate a free SSL cert for your domain. Firezone will include the ability to
automatically generate valid SSL certificates for you in an upcoming release,
but for now these must be generated manually and specified in the configuration
file. See here for a guide on how to do so:
[https://eff-certbot.readthedocs.io/en/stable/using.html#manual](https://eff-certbot.readthedocs.io/en/stable/using.html#manual)

18
docs/docs/get-started/security-considerations.md Normal file
View File

@@ -0,0 +1,18 @@
---
layout: default
title: Security Considerations
nav_order: 4
parent: Get Started
---
# Security Considerations
---
Firezone is still young software. For mission-critical applications, we
recommend **limiting network access to the Web UI** (by default ports tcp/443
and tcp/80) to prevent exposing it to the public Internet at this time.
The WireGuard listen port (by default port udp/51821) can be safely exposed to
allow user devices to connect. Traffic to this port is handled directly by the
WireGuard kernel module.

13
docs/docs/usage/configure.md Normal file
View File

@@ -0,0 +1,13 @@
---
layout: default
title: Configure
nav_order: 1
parent: Usage
---
# Configure
---
User-configurable settings can be found in the main configuration file located
at `/etc/firezone/firezone.rb`. Changing this file **requires re-running** `sudo firezone-ctl reconfigure` to pick up
the changes and apply them to the running system.

2
docs/docs/usage/index.md
View File

@@ -1,7 +1,7 @@
---
layout: default
title: Usage
nav_order: 3
nav_order: 4
has_children: true
---

8
docs/docs/usage/manage.md
View File

@@ -1,7 +1,7 @@
---
layout: default
title: Manage Installation
nav_order: 1
nav_order: 2
parent: Usage
---
@@ -64,9 +64,3 @@ Service Management Commands:
usr2
Send the services a USR2.
```
## Troubleshooting
For any problems that arise, a good first bet is to check the Firezone logs.
To view Firezone logs, run `sudo firezone-ctl tail`.

0
docs/docs/usage/troubleshooting.md → docs/docs/usage/troubleshoot.md
View File

2
docs/docs/usage/uninstall.md
View File

@@ -5,7 +5,7 @@ nav_order: 3
parent: Usage
---
# Uninstalling
# Uninstall
---

1
docs/docs/usage/upgrade.md
View File

@@ -6,7 +6,6 @@ parent: Usage
---
# Upgrade
---
Upgrading Firezone will disconnect all VPN connections and require shutting

30
docs/index.md
View File

@@ -9,15 +9,33 @@ description: "Firezone is a self-managed WireGuard-based VPN server and Linux fi
---
# Overview
---
Firezone is an open source, self-managed VPN server and Linux firewall designed for simplicity and security.
[Firezone](https://firez.one) is an open source, self-hosted VPN server and
egress firewall for Linux. Use it to **quickly and easily** secure access to
your private network and internal applications from a simple Web UI.
Here are a few helpful links to get you started:
* [Quick Start Guide]({% link docs/get-started/index.md %})
## Features
- **Fast:** Uses WireGuard to be [3-4 times](https://wireguard.com/performance/) faster than OpenVPN.
- **No dependencies:** All dependencies are bundled thanks to
[Chef Omnibus](https://github.com/chef/omnibus).
- **Simple:** Takes minutes to set up. Manage via a simple CLI.
- **Secure:** Runs unprivileged. HTTPS enforced. Encrypted cookies.
- **Firewall included:** Uses Linux [nftables](https://netfilter.org) to block
unwanted egress traffic.
## Quick Start
1. [Prepare for install]({% link docs/get-started/index.md %})
2. [Install]({% link docs/get-started/install.md %})
3. [Configure]({% link docs/usage/configure.md %})
## Get Help
If you're looking for help installing and configuring Firezone, we're happy to
help.
If you're looking for help in deploying and configuring Firezone, we're happy to help.
* [Discussion Forums](https://discourse.firez.one/)
* [Public Slack Group](https://join.slack.com/t/firezone-users/shared_invite/zt-111043zus-j1lP_jP5ohv52FhAayzT6w)
* [Contact Us](mailto:team@firez.one)
* [Email Us](mailto:team@firez.one)