Firezone is a simple WireGuard based VPN server and firewall for Linux designed to be secure, easy to manage, and quick to set up.

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 faster than OpenVPN.
• Firewall built in: Uses nftables to block unwanted egress traffic.
• No dependencies: All dependencies are bundled thanks to Chef Omnibus.
• Secure: Runs unprivileged. HTTPS enforced. Encrypted cookies.

Deploying and Configuring

Firezone is built using 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 built-in.

Requirements

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 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 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 and let us know.

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.

Installation Instructions

1. Download the relevant package for your distribution from the releases page.
2. Install with sudo rpm -i firezone-<version>.rpm or sudo dpkg -i firezone-<version>.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://<your-server-fqdn>

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.

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

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:

================================================================================
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:

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. 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.
• Report issues and bugs in this Github project.

License

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