diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6d99a6a4a..7cc67adb9 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -86,7 +86,7 @@ jobs: cd omnibus bundle install --binstubs sudo mkdir -p /opt/firezone - sudo chown vagrant:vagrant /opt/firezone + sudo chown -R vagrant:vagrant /opt/firezone bin/omnibus build firezone - name: Functional Test run: | @@ -100,7 +100,7 @@ jobs: - name: Cleanup if: always() run: | - scripts/uninstall.sh + sudo scripts/uninstall.sh rm -rf omnibus/pkg/* publish: diff --git a/README.md b/README.md index bf27245a6..4a7681b24 100644 --- a/README.md +++ b/README.md @@ -19,64 +19,155 @@

-Firezone is a simple [WireGuard](https://www.wireguard.com/) based VPN server and firewall for Linux designed to be secure, easy to manage, and quick to set up. +

+ A self-managed WireGuard-based VPN server and Linux firewall designed for simplicity and security. +

+ +
![Architecture](https://user-images.githubusercontent.com/167144/134593363-870c982d-921b-4f0c-b210-e77c8860d9ca.png) +# 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) + * [Uninstalling](#uninstalling) +* [Getting Support](#getting-support) +* [Developing and Contributing](#developing-and-contributing) + + # What is Firezone? -Firezone can be set up in minutes to manage your WireGuard VPN through a simple web interface. - -## Features - -- **Fast:** [3-4 times](https://wireguard.com/performance/) faster than OpenVPN. -- **Firewall built in:** Uses [nftables](https://netfilter.org) to block - unwanted egress traffic. -- **No dependencies:** All dependencies are bundled thanks to - [Chef Omnibus](https://github.com/chef/omnibus). -- **Secure:** Runs unprivileged. HTTPS enforced. Encrypted cookies. +Firezone is a Linux package to manage your WireGuard VPN through a simple web interface. ![Firezone](./apps/fz_http/assets/static/images/firezone-usage.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 API. +- **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 is built using [Chef Omnibus](https://github.com/chef/omnibus) which -bundles all dependences into a single distributable `.deb` or `.rpm` for your -distro. All that's needed is Linux kernel 4.19 or newer with proper WireGuard -support. We recommend Linux 5.6 or higher since [it has WireGuard -support](https://lwn.net/ml/linux-kernel/CA+55aFz5EWE9OTbzDoMfsY2ez04Qv9eg0KQhwKfyJY0vFvoD3g@mail.gmail.com/) -built-in. +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. -## Requirements +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. -Firezone currently supports the following Linux distributions: - -| Name | Status | Notes | -| --- | --- | --- | -| CentOS 7 | **Fully-supported** | Kernel upgrade to `kernel-lt` or `kernel-ml` required. See [this guide](https://medium.com/@nazishalam07/update-centos-kernel-3-10-to-5-13-latest-9462b4f1e62c) for an example. | -| CentOS 8 | **Fully-supported** | Works as-is | -| Ubuntu 18.04 | **Fully-supported** | WireGuard must be installed: `apt install wireguard-dkms`. We also recommend updating the kernel to 5.4 or higher: `apt install linux-image-generic-hwe-18.04` | -| Ubuntu 20.04 | **Fully-supported** | Works as-is | -| Debian 10 | **Fully-supported** | Kernel upgrade required. See [this guide](https://jensd.be/968/linux/install-a-newer-kernel-in-debian-10-buster-stable) for an example. | -| Debian 11 | **Fully-supported** | Works as-is | -| Fedora 33 | **Fully-supported** | Works as-is | -| Fedora 34 | **Fully-supported** | Works as-is | - -If your distro isn't listed here please [open an issue](https://github.com/firezone/firezone/issues/new/choose) and let us know. +### 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** to prevent exposing it to the public Internet. + +## Supported Linux Distributions + +Firezone currently supports the following distributions: + +| Name | Status | Notes | +| --- | --- | --- | +| CentOS 7 | **Fully-supported** | See [CentOS 7 Notes](#centos-7-notes) | +| CentOS 8 | **Fully-supported** | Works as-is | +| Ubuntu 18.04 | **Fully-supported** | See [Ubuntu 18.04 Notes](#ubuntu-1804-notes) | +| Ubuntu 20.04 | **Fully-supported** | Works as-is | +| Debian 10 | **Fully-supported** | See [Debian 10 Notes](#debian-10-notes)| +| Debian 11 | **Fully-supported** | Works as-is | +| Fedora 33 | **Fully-supported** | Works as-is | +| Fedora 34 | **Fully-supported** | Works as-is | + +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. + +### 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. + +### 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. + ## Installation Instructions -1. Download the relevant package for your distribution from the [releases page](https://github.com/firezone/firezone/releases). -2. Install with `sudo rpm -i firezone-.rpm` or `sudo dpkg -i firezone-.deb` depending on your distribution. -3. Bootstrap the application with `sudo firezone-ctl reconfigure`. This will initialize config files, set up needed services and generate the default configuration. -4. Edit the default configuration at `/etc/firezone/firezone.rb`. At a minimum, you'll need to make sure `default['firezone']['fqdn']`, `default['firezone']['url_host']`, `default['firezone']['ssl']['certificate']`, and `default['firezone']['ssl']['certificate_key']` are set properly. -5. Reconfigure the application to pick up the new changes: `sudo firezone-ctl reconfigure`. -6. Finally, create an admin user with `sudo firezone-ctl create_admin`. Check the console for the login credentials. -7. Now you should be able to log into the web UI at `https://` +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_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 @@ -132,16 +223,16 @@ Service Management Commands: Send the services a USR2. ``` -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. - ## 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`. -Occasionally, during a `sudo firezone-ctl reconfigure`, the `phoenix` will fail -to start with a `TIMEOUT` error like below: +### Phoenix restart times out + +Occasionally, during a `sudo firezone-ctl reconfigure`, the `phoenix` service +will fail to start with a `TIMEOUT` error like below: ``` ================================================================================ @@ -159,16 +250,15 @@ Ran /opt/firezone/embedded/bin/sv restart /opt/firezone/service/phoenix returned ``` This happens because of the way phoenix handles input before fully starting up. -To workaround, simply run `sudo firezone-ctl reconfigure` once more everything +To workaround, simply run `sudo firezone-ctl reconfigure` once more and everything should start fine. - ## Uninstalling To completely remove Firezone and its configuration files, run the [uninstall.sh script](https://github.com/firezone/firezone/blob/master/scripts/uninstall.sh): -`curl -L https://github.com/firezone/firezone/raw/master/scripts/uninstall.sh | sudo bash -E` +`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. @@ -176,7 +266,7 @@ undone. # Getting Support For help, feedback or contributions please join our [Slack group](https://admin.typeform.com/form/rpMtkZw4/create?block=a9c11a46-1dcf-4155-b447-0d8ce5700d5f). We're actively working to improve Firezone, and the Slack group is the best way to coordinate our efforts. -## Developing and Contributing +# Developing and Contributing - See [CONTRIBUTING.md](CONTRIBUTING.md). - Report issues and bugs in [this Github project](). diff --git a/apps/fz_http/README.md b/apps/fz_http/README.md index f664de6e4..01340d794 100644 --- a/apps/fz_http/README.md +++ b/apps/fz_http/README.md @@ -1,3 +1,3 @@ # FzHttp -Phoenix app for managing FireZone. +Phoenix app for managing Firezone. diff --git a/apps/fz_http/lib/fz_http_web/templates/layout/auth.html.heex b/apps/fz_http/lib/fz_http_web/templates/layout/auth.html.heex index a2301c9c0..0a8ac1377 100644 --- a/apps/fz_http/lib/fz_http_web/templates/layout/auth.html.heex +++ b/apps/fz_http/lib/fz_http_web/templates/layout/auth.html.heex @@ -5,7 +5,7 @@ <%= csrf_meta_tag() %> - <%= live_title_tag assigns[:page_title] || "FireZone" %> + <%= live_title_tag assigns[:page_title] || "Firezone" %> diff --git a/apps/fz_http/lib/fz_http_web/templates/layout/root.html.heex b/apps/fz_http/lib/fz_http_web/templates/layout/root.html.heex index dac69eb83..2afe6e85d 100644 --- a/apps/fz_http/lib/fz_http_web/templates/layout/root.html.heex +++ b/apps/fz_http/lib/fz_http_web/templates/layout/root.html.heex @@ -5,7 +5,7 @@ <%= csrf_meta_tag() %> - <%= live_title_tag assigns[:page_title], prefix: "FireZone • " %> + <%= live_title_tag assigns[:page_title], prefix: "Firezone • " %> @@ -64,7 +64,7 @@