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

Table of Contents

What is Firezone?

Firezone is a Linux package to manage your WireGuard VPN through a simple web interface.

Features

• Fast: Uses WireGuard to be 3-4 times faster than OpenVPN.
• No dependencies: All dependencies are bundled thanks to 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 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 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 requires a valid SSL certificate and a matching DNS record to run in production. We recommend using Let's Encrypt 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:

If your distro isn't listed here please open an issue 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 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 for an example.

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 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.

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:

   # 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

Your Firezone installation can be managed via the firezone-ctl command, as shown below. Most subcommands require prefixing with sudo.

root@demo:~# firezone-ctl
I don't know that command.
omnibus-ctl: command (subcommand)
create_admin
  Create an Admin user
General Commands:
  cleanse
    Delete *all* firezone data, and start from scratch.
  help
    Print this help message.
  reconfigure
    Reconfigure the application.
  show-config
    Show the configuration that would be generated by reconfigure.
  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.

Phoenix restart times out

Occasionally, during a sudo firezone-ctl reconfigure, the phoenix service will fail to start with a TIMEOUT error like below:

================================================================================
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 and everything should start fine.

Uninstalling

To completely remove Firezone and its configuration files, run the uninstall.sh script:

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.

Getting Support

For help, feedback or contributions please join our Discourse. We're actively working to improve Firezone, and the Discourse is the best way to coordinate our efforts.

Developing and Contributing

License

WireGuard™ is a registered trademark of Jason A. Donenfeld.