From a2c3620ee0ffe6cbe69ef09c6ed1dfa7717ce87c Mon Sep 17 00:00:00 2001 From: Jamil Bou Kheir Date: Thu, 22 Oct 2020 08:38:10 -0500 Subject: [PATCH] Docs Update --- .github/workflows/main.yml | 2 +- .tool-versions | 2 +- CONTRIBUTING.md | 91 ++++------- README.md | 73 ++++++--- Vagrantfile | 47 ++---- ansible/local.yml | 145 ++++++++++++++++++ .../sample_conf/wg-client.conf | 0 .../sample_conf/wg-server.conf | 0 apps/fg_vpn/lib/fg_vpn/wg_cli.ex | 16 ++ vagrant/provision_deps.sh | 77 ---------- vagrant/provision_runtimes.sh | 10 -- 11 files changed, 259 insertions(+), 204 deletions(-) create mode 100644 ansible/local.yml rename {vagrant => ansible}/sample_conf/wg-client.conf (100%) rename {vagrant => ansible}/sample_conf/wg-server.conf (100%) create mode 100644 apps/fg_vpn/lib/fg_vpn/wg_cli.ex delete mode 100644 vagrant/provision_deps.sh delete mode 100644 vagrant/provision_runtimes.sh diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 5637d81f6..8e192b0e8 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -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 diff --git a/.tool-versions b/.tool-versions index 68cc84c13..40b2557f0 100644 --- a/.tool-versions +++ b/.tool-versions @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 55faf8610..56fbf2326 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. diff --git a/README.md b/README.md index 5e6a9307e..3c2cd0b73 100644 --- a/README.md +++ b/README.md @@ -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). diff --git a/Vagrantfile b/Vagrantfile index c762d2bcb..eba9917a6 100644 --- a/Vagrantfile +++ b/Vagrantfile @@ -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 diff --git a/ansible/local.yml b/ansible/local.yml new file mode 100644 index 000000000..39cfbdc0b --- /dev/null +++ b/ansible/local.yml @@ -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' diff --git a/vagrant/sample_conf/wg-client.conf b/ansible/sample_conf/wg-client.conf similarity index 100% rename from vagrant/sample_conf/wg-client.conf rename to ansible/sample_conf/wg-client.conf diff --git a/vagrant/sample_conf/wg-server.conf b/ansible/sample_conf/wg-server.conf similarity index 100% rename from vagrant/sample_conf/wg-server.conf rename to ansible/sample_conf/wg-server.conf diff --git a/apps/fg_vpn/lib/fg_vpn/wg_cli.ex b/apps/fg_vpn/lib/fg_vpn/wg_cli.ex new file mode 100644 index 000000000..0bc809f33 --- /dev/null +++ b/apps/fg_vpn/lib/fg_vpn/wg_cli.ex @@ -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 diff --git a/vagrant/provision_deps.sh b/vagrant/provision_deps.sh deleted file mode 100644 index f637cdb6d..000000000 --- a/vagrant/provision_deps.sh +++ /dev/null @@ -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 diff --git a/vagrant/provision_runtimes.sh b/vagrant/provision_runtimes.sh deleted file mode 100644 index 55a6cb50e..000000000 --- a/vagrant/provision_runtimes.sh +++ /dev/null @@ -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