diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d1c98eabf..0fcbdf465 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,23 +16,22 @@ Read this guide before opening a pull request. ## Prerequisites -You'll need the following software installed to develop for FireZone: +You'll need the following software installed to develop for Firezone: -- [Vagrant](vagrantup.com) -- [Ansible](ansible.com) -- [VirtualBox](virtualbox.org) -- [asdf VM](asdf-vm.com) +- [asdf](asdf-vm.com) - A recent version of [PostgreSQL](postgresql.org) server installed and running - [dotenv](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/dotenv) functionality for your shell +- ## Project Setup -1. Ensure Postgres is running with a superuser role of `firezone`. E.g. +1. Ensure Postgres is running ``` $ psql -h localhost -d postgres > CREATE ROLE firezone; + > ALTER ROLE firezone WITH LOGIN; ``` 2. Install the language versions defined in `.tool-versions`: ``` diff --git a/README.md b/README.md index d9814b413..bf27245a6 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,8 @@ firezone logo

- - firezone + + firezone Slack @@ -19,7 +19,7 @@

-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. +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. ![Architecture](https://user-images.githubusercontent.com/167144/134593363-870c982d-921b-4f0c-b210-e77c8860d9ca.png) @@ -40,42 +40,47 @@ Firezone can be set up in minutes to manage your WireGuard VPN through a simple # 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. + ## Requirements -FireZone currently supports the following operating systems: +Firezone currently supports the following Linux distributions: -| Name | Status | -| --- | --- | -| CentOS 7 | **Fully-supported** | -| CentOS 8 | **Fully-supported** | -| Ubuntu 18.04 | **Fully-supported** | -| Ubuntu 20.04 | **Fully-supported** | -| Debian 10 | **Fully-supported** | -| Debian 11 | **Fully-supported** | -| Fedora 33 | **Fully-supported** | -| Fedora 34 | **Fully-supported** | -| macOS | Unsupported at this time | -| Windows | Unsupported at this time | +| 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 we'll look into adding it. +If your distro isn't listed here please [open an issue](https://github.com/firezone/firezone/issues/new/choose) and let us know. -FireZone requires a valid SSL certificate and a matching DNS record to run in +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. ## 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. This will unpack the application and set up necessary directory structure. +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`. You'll want to make sure `default['firezone']['fqdn']`, `default['firezone']['url_host']`, `default['firezone']['ssl']['certificate']`, and `default['firezone']['ssl']['certificate']` are set properly. +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://` # Using Firezone -Your FireZone installation can be managed via the `firezone-ctl` command, as shown below. Most subcommands require prefixing with `sudo`. +Your Firezone installation can be managed via the `firezone-ctl` command, as shown below. Most subcommands require prefixing with `sudo`. ```shell root@demo:~# firezone-ctl @@ -127,24 +132,50 @@ Service Management Commands: Send the services a USR2. ``` -# Architecture +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. -FireZone is written in the Elixir programming language and composed as an [Umbrella -project](https://elixir-lang.org/getting-started/mix-otp/dependencies-and-umbrella-projects.html) -consisting of three independent applications: +## Troubleshooting -- [apps/fz_http](apps/fz_http): The Web Application -- [apps/fz_wall](apps/fz_wall): Firewall Management Process -- [apps/fz_vpn](apps/fz_vpn): WireGuard™ Management Process +To view Firezone logs, run `sudo firezone-ctl tail`. -For now, FireZone assumes these apps are all running on the same host. +Occasionally, during a `sudo firezone-ctl reconfigure`, the `phoenix` will fail +to start with a `TIMEOUT` error like below: -[Chef Omnibus](https://github.com/chef/omnibus) is used to bundle all FireZone dependencies into a single distributable Linux package. +``` +================================================================================ +Error executing action `restart` on resource 'runit_service[phoenix]' +================================================================================ + +Mixlib::ShellOut::ShellCommandFailed +------------------------------------ +Expected process to exit with [0], but received '1' +---- Begin output of /opt/firezone/embedded/bin/sv restart /opt/firezone/service/phoenix ---- +STDOUT: timeout: run: /opt/firezone/service/phoenix: (pid 3091432) 34s, got TERM +STDERR: +---- End output of /opt/firezone/embedded/bin/sv restart /opt/firezone/service/phoenix ---- +Ran /opt/firezone/embedded/bin/sv restart /opt/firezone/service/phoenix returned 1 +``` + +This happens because of the way phoenix handles input before fully starting up. +To workaround, simply run `sudo firezone-ctl reconfigure` once more 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` + +**Warning**: This will irreversibly destroy ALL Firezone data and can't be +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 - See [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/scripts/install.sh b/scripts/install.sh deleted file mode 100755 index ef2425872..000000000 --- a/scripts/install.sh +++ /dev/null @@ -1,78 +0,0 @@ -#!/bin/sh -set -e - -# XXX: Update this for Omnibus packages. - -os_not_found () { - echo "Operating System not detected. Build from source?" - exit 1 -} - -download_release () { - regex="Operating System: (\w+) ([\d\.]+)" - os=`hostnamectl` - if [[ $os =~ $regex ]]; then - distro="${BASH_REMATCH[1]}" - version="${BASH_REMATCH[2]}" - if [[ -z $distro ]] && [[ -z $version ]]; then - os_not_found - else - echo "Fetching latest release..." - file="firezone-latest-${distro}_${version}.amd64.tar.gz" - curl -L -O "https://github.com/firezone/firezone/releases/${file}" - fi - else - os_not_found - fi -} - -echo "Installing FireZone..." -echo - -if [ -n "$1" ]; then - echo "Package tarball supplied. Skipping download..." - file=$1 -else - download_release -fi - -echo "Setting up FireZone..." -echo - -if id firezone &>/dev/null; then - echo "firezone user exists... not creating." -else - echo "Creating system user firezone" - useradd --system firezone -fi - -echo "Extracting package to /opt/firezone..." -echo -tar -zxf $file -C /opt/ -chmod -R firezone:firezone /opt/firezone - -# Create DB user -echo "Creating DB user..." -hostname=$(hostname) -db_user=firezone -db_password="$(openssl rand -hex 16)" -res=$(su postgres -c "psql -c \"SELECT 1 FROM pg_roles WHERE rolname = '${db_user}';\"") -if [[ $res == *"0 rows"* ]]; then - su postgres -c "psql -c \"CREATE ROLE ${db_user} WITH LOGIN PASSWORD '${db_password}';\"" -else - echo "${db_user} role found in DB" -fi - -# Create DB if not exists -db_name=firezone -res=$(su postgres -c "psql -c \"SELECT 1 FROM pg_database WHERE datname = '${db_name}';\"") -if [[ $res == *"0 rows"* ]]; then - su postgres -c "psql -c \"CREATE DATABASE firezone;\" || true" -else - echo "${db_name} exists; not creating" -fi - - - - -echo "FireZone installed successfully!" diff --git a/scripts/uninstall.sh b/scripts/uninstall.sh index 29c4c8090..5381931bc 100755 --- a/scripts/uninstall.sh +++ b/scripts/uninstall.sh @@ -1,12 +1,28 @@ #!/bin/sh set -ex -sudo apt-get remove -y --purge firezone || true -sudo yum remove -y firezone || true +echo 'Removing all Firezone configuration data...' +firezone-ctl cleanse yes -sudo rm -rf \ +apt=`which apt-get` +yum=`which yum` + +echo 'Removing firezone package...' +if [ -f $apt ]; then + apt-get remove -y --purge firezone +elif [ -f $yum ]; then + yum remove -y firezone +else + echo 'apt-get or yum not found' + exit 1 +fi + +echo 'Removing remaining directories...' +rm -rf \ /var/opt/firezone \ /var/log/firezone \ /etc/firezone \ /usr/bin/firezone-ctl \ /opt/firezone + +echo 'Done! Firezone has been uninstalled.'