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

Docs Update

Browse Source
This commit is contained in:
Jamil Bou Kheir
2020-10-22 08:38:10 -05:00
parent b410df60ea
commit a2c3620ee0
11 changed files with 259 additions and 204 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/main.yml vendored
View File

@@ -32,7 +32,7 @@ jobs:
- name: Run Static Tests
uses: actions/setup-elixir@v1
with:
elixir-version: "1.11.0"
elixir-version: "1.11.1"
otp-version: "23.1.1"
- name: Install Dependencies
run: mix deps.get --only test

2
.tool-versions
View File

@@ -1,4 +1,4 @@
elixir 1.11.0-otp-23
elixir 1.11.1-otp-23
erlang 23.1.1
nodejs 10.22.1
python 3.7.9

91
CONTRIBUTING.md
View File

@@ -5,9 +5,7 @@ Read this guide before opening a pull request.
## Table of Contents
1. [Prerequisites](#prerequisites)
1. [Vagrant](#vagrant)
2. [Consciousness](#consciousness)
2. [Development](#development)
2. [Project Setup](#project-setup)
1. [Provision the test VMs](#provision-the-test-vms)
2. [Start the WireGuard™ interface on the
server](#start-the-wireguard-interface-on-the-server)
@@ -16,66 +14,43 @@ Read this guide before opening a pull request.
3. [Testing](#testing)
TBD
## Prerequisites
### Vagrant
You'll need the following software installed to develop for FireGuard:
### Consciousness
- [Vagrant](vagrantup.com)
- [Ansible](ansible.com)
- [VirtualBox](virtualbox.org)
- [asdf VM](asdf-vm.com)
- A recent version of [PostgreSQL](postgresql.org) server installed and running
## Development
## Project Setup
### Provision the test VMs
1. Ensure Postgres is running with a superuser role of `fireguard`. E.g.
```
$ psql -h localhost -d postgres
```bash
> vagrant up
```
### Start the WireGuard Interface on the server
```bash
> vagrant ssh server
# ... wait for SSH session to establish, then
> sudo wg-quick up wg0
```
You should see output like:
```
[#] ip link add wg0 type wireguard
[#] wg setconf wg0 /dev/fd/63
[#] ip -4 address add 192.168.10.1/24 dev wg0
[#] ip link set mtu 1420 up dev wg0
[#] iptables -A FORWARD -i wg0 -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE; ip6tables -A FORWARD -i wg0 -j ACCEPT; ip6tables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
```
### Start the WireGuard Interface on the client
```bash
> vagrant ssh client
# ... wait for SSH session to establish, then
> sudo wg-quick up wg0
```
You should see output like:
```
[#] ip link add wg0 type wireguard
[#] wg setconf wg0 /dev/fd/63
[#] ip -4 address add 192.168.10.2/32 dev wg0
[#] ip link set mtu 1420 up dev wg0
[#] resolvconf -a tun.wg0 -m 0 -x
[#] wg set wg0 fwmark 51820
[#] ip -6 route add ::/0 dev wg0 table 51820
[#] ip -6 rule add not fwmark 51820 table 51820
[#] ip -6 rule add table main suppress_prefixlength 0
[#] ip6tables-restore -n
[#] ip -4 route add 0.0.0.0/0 dev wg0 table 51820
[#] ip -4 rule add not fwmark 51820 table 51820
[#] ip -4 rule add table main suppress_prefixlength 0
[#] sysctl -q net.ipv4.conf.all.src_valid_mark=1
[#] iptables-restore -n
```
**At this point, your tunnel should be established! 🎉**
Use `wg show wg0` to see stats about the tunnel.
> CREATE ROLE fireguard;
```
2. Install the language versions defined in `.tool-versions`:
```
# Run this from the project root
$ asdf install
```
3. Resolve dependencies
```
$ mix deps.get
$ npm install --prefix apps/fg_http/assets
```
4. Bootstrap DB
```
$ mix ecto.setup
```
5. Launch Server
```
mix phx.server
```
## Testing
Run tests with `mix test` from the project root.

73
README.md
View File

@@ -1,38 +1,65 @@
![Test](https://github.com/CloudFire-LLC/fireguard/workflows/Test/badge.svg)
[![Coverage Status](https://coveralls.io/repos/github/CloudFire-LLC/fireguard/badge.svg?branch=master)](https://coveralls.io/github/CloudFire-LLC/fireguard?branch=master)
# FireGuard
**Warning**: This project is under active development and is absolutely not secure at the moment.
Do not attempt to use this software until this notice is removed.
**Warning**: This project is under active development and is not secure at the moment.
Do not attempt to use this software in any production capacity until this notice is removed.
You have been warned.
Check back later :-).
# FireGuard
1. [Intro](#intro)
2. [Architecture](#architecture)
3. [Setup](#setup)
4. [Usage](#usage)
5. [Contributing](#contributing)
# Setup
## Intro
* have postgres installed with a super user role `fireguard`
FireGuard is a host-it-yourself VPN and firewall configurable through a Web UI.
It aims to be a simple way to setup a VPN and optional firewall for all your
devices.
Use FireGuard to:
- Set up your own VPN
- Block, inspect, or capture outgoing traffic from your phone / tablet /
computer to any IP(s)
## Architecture
FireGuard 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 Elixir packages:
- [apps/fg_http](apps/fg_http): The Web Application
- [apps/fg_wall](apps/fg_wall): Firewall Management Process
- [apps/fg_vpn](apps/fg_vpn): WireGuard™ Management Process
For now, FireGuard assumes these apps are all running on the same host.
## Setup
Currently, the only supported method of running FireGuard is locally. MacOS and
Linux users shouldn't have any problems. Windows will Probably Work™.
You'll need recent versions of the following tools installed:
- ansible
- vagrant
- VirtualBox
With the above installed, you should be able to navigate into the project root
and just run:
```
psql -h localhost -d postgres
CREATE ROLE fireguard;
$ vagrant up
```
* have elixir installed
```
brew install elixir
```
setup project
```
cd apps/fg_http && mix deps.get && mix ecto.setup
npm install --prefix assets
mix phx.server
```
This will download the VM base box, provision it with dependencies, bootstrap
the FireGuard DB, launch the FireGuard Services, and print instructions for
connecting to the Web UI.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).

47
Vagrantfile vendored
View File

@@ -1,43 +1,22 @@
# -*- mode: ruby -*-
# vi: set ft=ruby :
Vagrant.configure('2') do |config|
config.vm.define "server" do |server|
server.vm.box = 'hashicorp/bionic64'
server.vm.hostname = 'server'
# Link to client
server.vm.network 'private_network', ip: '172.16.1.2'
server.vm.network 'forwarded_port', guest: 4000, host: 4000, protocol: 'tcp'
# Install dependencies
server.vm.provision 'shell', path: 'vagrant/provision_deps.sh'
server.vm.provision 'shell', path: 'vagrant/provision_runtimes.sh'
# Copy WireGuard server into place
server.vm.provision 'file', source: 'vagrant/sample_conf/wg-server.conf', destination: '/tmp/wg0.conf'
server.vm.provision 'shell', inline: 'mv /tmp/wg0.conf /etc/wireguard/'
server.vm.provision 'shell', privileged: true, inline: <<~SHELL
echo 'net.ipv4.ip_forward = 1' >> /etc/sysctl.conf
echo 'net.ipv6.conf.all.forwarding = 1' >> /etc/sysctl.conf
sysctl -p
SHELL
config.vm.provider 'virtualbox' do |vbox|
# Speed up compiles
vbox.cpus = 4
end
config.vm.define "client" do |client|
client.vm.box = 'hashicorp/bionic64'
client.vm.hostname = 'client'
# Link to server
client.vm.network 'private_network', ip: '172.16.1.3'
config.vm.box = 'ubuntu/focal64'
config.vm.hostname = 'fireguard.local'
# Install dependencies
client.vm.provision 'shell', path: 'vagrant/provision_deps.sh'
client.vm.provision 'shell', path: 'vagrant/provision_runtimes.sh'
# Web
config.vm.network 'forwarded_port', guest: 4000, host: 4000, protocol: 'tcp'
# Copy WireGuard client into place
client.vm.provision 'file', source: 'vagrant/sample_conf/wg-client.conf', destination: '/tmp/wg0.conf'
client.vm.provision 'shell', inline: 'mv /tmp/wg0.conf /etc/wireguard/', privileged: true
# VPN
config.vm.network 'forwarded_port', guest: 51820, host: 51820, protocol: 'udp'
config.vm.provision 'ansible' do |ansible|
ansible.playbook = 'ansible/local.yml'
ansible.verbose = true
end
end

145
ansible/local.yml Normal file
View File

@@ -0,0 +1,145 @@
---
- name: provision deps
hosts: '*'
tasks:
- name: install deps
become: true
apt:
install_recommends: no
autoclean: yes
autoremove: yes
update_cache: true
pkg:
- git
- curl
- wireguard
- wireguard-tools
- wireguard-dkms
- gnupg
- unzip
# pkg:
# - libodbc1
# - libsctp1
# - libwxgtk3.0-0v5
# - libwxgtk3.0-dev
# - unixodbc-dev
# - libsctp-dev
# - autoconf
# - automake
# - bzip2
# - dpkg-dev
# - file
# - g++
# - gcc
# - imagemagick
# - libbz2-dev
# - libc6-dev
# - libcurl4-openssl-dev
# - libdb-dev
# - libevent-dev
# - libffi-dev
# - libgdbm-dev
# - libglib2.0-dev
# - libgmp-dev
# - libjpeg-dev
# - libkrb5-dev
# - liblzma-dev
# - libmagickcore-dev
# - libmagickwand-dev
# - libmaxminddb-dev
# - libncurses5-dev
# - libncursesw5-dev
# - libpng-dev
# - libpq-dev
# - libreadline-dev
# - libsqlite3-dev
# - libssl-dev
# - libtool
# - libwebp-dev
# - libxml2-dev
# - libxslt-dev
# - libyaml-dev
# - make
# - patch
# - xz-utils
# - zlib1g-dev
# - linux-image-generic-hwe-18.04-edge
# - linux-headers-generic-hwe-18.04-edge
# - git
# - curl
# - ca-certificates
# - resolvconf
# - gnupg
# - wireguard
# - wireguard-tools
# - wireguard-dkms
- name: Install Postgres
hosts: '*'
tasks:
- name: add postgres repo
become: true
shell: |
curl https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add -
sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
- name: install postgres
become: true
apt:
update_cache: true
install_recommends: no
autoclean: yes
autoremove: yes
name: postgresql-13
- name: Configure System
hosts: '*'
tasks:
- name: copy files
become: true
shell: |
cp /vagrant/ansible/sample_conf/wg-server.conf /etc/wireguard/wg0.conf
- name: ensure ipv4 forward
become: true
lineinfile:
path: /etc/sysctl.conf
line: 'net.ipv4.ip_forward = 1'
- name: ensure ipv6 forward
become: true
lineinfile:
path: /etc/sysctl.conf
line: 'net.ipv6.conf.all.forwarding = 1'
- name: apply sysctl
become: true
shell: sysctl -p
- name: Provision Runtimes
hosts: '*'
tasks:
- name: install erlang
become: true
apt:
install_recommends: no
autoclean: yes
autoremove: yes
update_cache: true
deb: https://packages.erlang-solutions.com/erlang/debian/pool/esl-erlang_23.1-1~ubuntu~focal_amd64.deb
- name: install elixir
become: false
shell:
executable: /bin/bash
cmd: |
[ ! -d ~/.asdf ] && git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.8.0
~/.asdf/bin/asdf plugin-add elixir
~/.asdf/bin/asdf install elixir 1.11.1-otp-23
~/.asdf/bin/asdf global elixir 1.11.1-otp-23
~/.asdf/bin/asdf reshim elixir 1.11.1-otp-23
- name: asdf to bashrc
become: false
lineinfile:
path: ~/.bashrc
line: '. ~/.asdf/asdf.sh'
- name: asdf completions to bashrc
become: false
lineinfile:
path: ~/.bashrc
line: '. ~/.asdf/completions/asdf.bash'

0
vagrant/sample_conf/wg-client.conf → ansible/sample_conf/wg-client.conf
View File

0
vagrant/sample_conf/wg-server.conf → ansible/sample_conf/wg-server.conf
View File

16
apps/fg_vpn/lib/fg_vpn/wg_cli.ex Normal file
View File

@@ -0,0 +1,16 @@
defmodule FgVpn.WGCLI do
@moduledoc """
Wraps command-line functionality of WireGuard for our purposes
"""
def add_client(_public_key) do
# Add network for this device
# Generate config entry
end
def add_client_network do
end
def save_config do
end
end

77
vagrant/provision_deps.sh
View File

@@ -1,77 +0,0 @@
#!/usr/bin/env bash
set -e
# This file provisions the vagrant vm with needed tools to develop
# and test a single-host FireGuard instance.
# Add WireGuard PPA
add-apt-repository ppa:wireguard/wireguard
# Add required packages
apt-get update
# These are from the Docker build-pack and erlang Dockerfiles
apt-get install -y --no-install-recommends \
libodbc1 \
libsctp1 \
libwxgtk3.0 \
unixodbc-dev \
libsctp-dev \
autoconf \
automake \
bzip2 \
dpkg-dev \
file \
g++ \
gcc \
imagemagick \
libbz2-dev \
libc6-dev \
libcurl4-openssl-dev \
libdb-dev \
libevent-dev \
libffi-dev \
libgdbm-dev \
libglib2.0-dev \
libgmp-dev \
libjpeg-dev \
libkrb5-dev \
liblzma-dev \
libmagickcore-dev \
libmagickwand-dev \
libmaxminddb-dev \
libncurses5-dev \
libncursesw5-dev \
libpng-dev \
libpq-dev \
libreadline-dev \
libsqlite3-dev \
libssl-dev \
libtool \
libwebp-dev \
libxml2-dev \
libxslt-dev \
libyaml-dev \
make \
patch \
unzip \
xz-utils \
zlib1g-dev \
linux-image-generic-hwe-18.04-edge \
linux-headers-generic-hwe-18.04-edge \
git \
libwxgtk3.0-dev \
curl \
ca-certificates \
resolvconf \
gnupg
# Install WireGuard
apt-get install -y --no-install-recommends wireguard wireguard-tools wireguard-dkms
# Install Postgres
curl https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add -
sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
apt-get update
apt-get install -y --no-install-recommends \
postgresql-12

10
vagrant/provision_runtimes.sh
View File

@@ -1,10 +0,0 @@
#!/usr/bin/env bash
set -e
# Install Erlang
wget https://packages.erlang-solutions.com/erlang/debian/pool/esl-erlang_22.3.3-1~ubuntu~bionic_amd64.deb
dpkg -i esl-erlang_22.3.3-1~ubuntu~bionic_amd64.deb
# Install Elixir
wget https://packages.erlang-solutions.com/erlang/debian/pool/elixir_1.10.3-1~ubuntu~bionic_all.deb
dpkg -i elixir_1.10.3-1~ubuntu~bionic_all.deb