Reorganize documentation for GitHub pages (#378)

Reorganize documentation for clarity and use with GitHub pages static
site generator. This closes #371.

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 ### Filing New Issues
 
-* Check that your issue is not already described in the [FAQ](docs/FAQ.md), [troubleshooting](docs/TROUBLESHOOTING.md) docs, or an [existing issue](https://github.com/trailofbits/algo/issues)
+* Check that your issue is not already described in the [FAQ](docs/faq.md), [troubleshooting](docs/troubleshooting.md) docs, or an [existing issue](https://github.com/trailofbits/algo/issues)
 * Did you remember to install the dependencies for your operating system prior to installing Algo?
 * We only support modern operating systems, e.g. macOS 10.11+, iOS 9+, Windows 10+, Ubuntu 17.04+, etc.
 * Cloud provider support is limited to DO, AWS, GCE, and Azure. Any others are best effort only.

README.md

@@ -55,8 +55,8 @@ The easiest way to get an Algo server running is to let it set up a _new_ virtua
           python-setuptools \
           python-virtualenv -y
       ```
-     - Linux (rpm-based): See the [Pre-Install Documentation for RedHat/CentOS 6.x](docs/pre-install_redhat_centos_6.x.md)
-     - Windows: See the [Windows documentation](docs/WINDOWS.md)
+     - Linux (rpm-based): See the [Pre-Install Documentation for RedHat/CentOS 6.x](docs/server-redhat-centos-6.md)
+     - Windows: See the [Windows documentation](docs/client-windows.md)
 
 4. Install Algo's remaining dependencies for your operating system. Using the same terminal window as the previous step run the command below.
     ```bash
@@ -66,7 +66,7 @@ The easiest way to get an Algo server running is to let it set up a _new_ virtua
 
 5. Open `config.cfg` in your favorite text editor. Specify the users you wish to create in the `users` list.
 
-6. Start the deployment. Return to your terminal. In the Algo directory, run `./algo` and follow the instructions. There are several optional features available. None are required for a fully functional VPN server. These optional features are described in greater detail in [ROLES.md](docs/ROLES.md).
+6. Start the deployment. Return to your terminal. In the Algo directory, run `./algo` and follow the instructions. There are several optional features available. None are required for a fully functional VPN server. These optional features are described in greater detail in [ansible-roles.md](docs/ansible-roles.md).
 
 That's it! You will get the message below when the server deployment process completes. You now have an Algo server on the internet. Take note of the p12 (user certificate) password in case you need it later.
 
@@ -86,7 +86,7 @@ You can now setup clients to connect it, e.g. your iPhone or laptop. Proceed to
 
 Note: If you want to run Algo again at any point in the future, you must first "reactivate" the dependencies for it. To reactivate them, open your terminal, use `cd` to navigate to the directory with Algo, then run `source env/bin/activate`.
 
-Advanced users who want to install Algo on top of a server they already own or want to script the deployment of Algo onto a network of servers, please see the [Advanced Usage](/docs/ADVANCED.md) documentation.
+Advanced users who want to install Algo on top of a server they already own or want to script the deployment of Algo onto a network of servers, please see the [Advanced Usage](/docs/advanced-usage.md) documentation.
 
 ## Configure the VPN Clients
 
@@ -98,7 +98,7 @@ Find the corresponding mobileconfig (Apple Profile) for each user and send it to
 
 ### Android Devices
 
-You need to install the [strongSwan VPN Client for Android 4 and newer](https://play.google.com/store/apps/details?id=org.strongswan.android) because no version of Android supports IKEv2. Import the corresponding user.p12 certificate to your device. See the [Android setup instructions](/docs/ANDROID.md) for more detailed steps.
+You need to install the [strongSwan VPN Client for Android 4 and newer](https://play.google.com/store/apps/details?id=org.strongswan.android) because no version of Android supports IKEv2. Import the corresponding user.p12 certificate to your device. See the [Android setup instructions](/docs/client-android.md) for more detailed steps.
 
 ### Windows
 
@@ -164,10 +164,10 @@ The Algo VPN server now contains only the users listed in the `config.cfg` file.
 
 ## Additional Documentation
 
-* [Advanced Usage](docs/ADVANCED.md) describes how to deploy an Algo VPN server directly from Ansible.
-* [FAQ](docs/FAQ.md) includes answers to common questions.
-* [Roles](docs/ROLES.md) includes a description of optional Algo VPN server features.
-* [Troubleshooting](docs/TROUBLESHOOTING.md) includes answers to common technical issues.
+* [Advanced Usage](docs/anvanced-usage.md) describes how to deploy an Algo VPN server directly from Ansible.
+* [FAQ](docs/faq.md) includes answers to common questions.
+* [Roles](docs/ansible-roles.md) includes a description of optional Algo VPN server features.
+* [Troubleshooting](docs/troubleshooting.md) includes answers to common technical issues.
 
 ## Endorsements
 

algo

@@ -67,28 +67,28 @@ deploy () {
 
 azure () {
   read -p "
-Enter your azure secret id (https://github.com/trailofbits/algo/blob/master/docs/AZURE.md)
+Enter your azure secret id (https://github.com/trailofbits/algo/blob/master/docs/cloud-azure.md)
 You can skip this step if you want to use your defaults credentials from ~/.azure/credentials
 $ADDITIONAL_PROMPT
 [...]: " -rs azure_secret
 
   read -p "
 
-Enter your azure tenant id (https://github.com/trailofbits/algo/blob/master/docs/AZURE.md)
+Enter your azure tenant id (https://github.com/trailofbits/algo/blob/master/docs/cloud-azure.md)
 You can skip this step if you want to use your defaults credentials from ~/.azure/credentials
 $ADDITIONAL_PROMPT
 [...]: " -rs azure_tenant
 
   read -p "
 
-Enter your azure client id (application id) (https://github.com/trailofbits/algo/blob/master/docs/AZURE.md)
+Enter your azure client id (application id) (https://github.com/trailofbits/algo/blob/master/docs/cloud-azure.md)
 You can skip this step if you want to use your defaults credentials from ~/.azure/credentials
 $ADDITIONAL_PROMPT
 [...]: " -rs azure_client_id
 
   read -p "
 
-Enter your azure subscription id (https://github.com/trailofbits/algo/blob/master/docs/AZURE.md)
+Enter your azure subscription id (https://github.com/trailofbits/algo/blob/master/docs/cloud-azure.md)
 You can skip this step if you want to use your defaults credentials from ~/.azure/credentials
 $ADDITIONAL_PROMPT
 [...]: " -rs azure_subscription_id

docs/advanced-usage.md

@@ -2,13 +2,13 @@
 
 Make sure you have installed all the dependencies necessary for your operating system as described in the [README](../README.md).
 
-## Local Deployment
+## Local deployment
 
 It is possible to download the Algo scripts to your own Ubuntu server and run the scripts locally. You need to install Ansible to run Algo on Ubuntu. Installing ansible via pip requires pulling in a lot of dependencies, including a full compiler suite. It would be easier to use apt, however, Ubuntu 16.04 only comes with Ansible 2.0.0.2. Therefore, to use apt you must use the ansible PPA, and using a PPA requires installing `software-properties-common`.
 
 tl;dr:
 
-```
+```shell
 sudo apt-get install software-properties-common && sudo apt-add-repository ppa:ansible/ansible
 sudo apt-get update && sudo apt-get install ansible
 git clone https://github.com/trailofbits/algo
@@ -17,7 +17,7 @@ cd algo && ./algo
 
 **Warning**: If you run Algo on your existing server, the iptables rules will be overwritten. If you don't want to overwrite the rules, you must deploy via `ansible-playbook` and skip the `iptables` tag as described below.
 
-## Scripted Deployment
+## Scripted deployment
 
 You can deploy Algo non-interactively by running the Ansible playbooks directly with `ansible-playbook`.
 
@@ -27,11 +27,11 @@ You can deploy Algo non-interactively by running the Ansible playbooks directly
 
 Here is a full example for DigitalOcean:
 
-```
+```shell
 ansible-playbook deploy.yml -t digitalocean,vpn,cloud -e 'do_access_token=my_secret_token do_server_name=algo.local do_region=ams2'
 ```
 
-### Roles
+### Ansible roles
 
 Required tags:
 

docs/ansible-roles.md

@@ -1,6 +1,6 @@
 # Ansible Roles
 
-## Required Roles
+## Required roles
 
 * **Common**
   * Installs several required packages and software updates, then reboots if necessary
@@ -11,7 +11,7 @@
   * Bundles the appropriate certificates into Apple mobileconfig profiles for each user
   * Configures IPtables to block traffic that might pose a risk to VPN users, such as [SMB/CIFS](https://medium.com/@ValdikSS/deanonymizing-windows-users-and-capturing-microsoft-and-vpn-accounts-f7e53fe73834)
 
-## Optional Roles
+## Optional roles
 
 * **Security Enhancements**
   * Enables [unattended-upgrades](https://help.ubuntu.com/community/AutomaticSecurityUpdates) to ensure available patches are always applied

docs/client-android.md

@@ -1,3 +1,5 @@
+# Android client setup
+
 **NOTE:** If you are a Project Fi user, you must disable WiFi Assistant before continuing. See the [strongSwan documentation](https://wiki.strongswan.org/projects/strongswan/wiki/AndroidVPNClient) for details.
 
 | Instruction | Screenshot(s) |
@@ -35,4 +37,4 @@ Ensure that "WiFi Assistant" and any other always-on VPNs are disabled before at
 [step7-screen]: https://i.imgur.com/aT2MPih.png
 [step8-screen]: https://i.imgur.com/gvaKzkh.png
 [step9-screen]: https://i.imgur.com/eZp8DNb.png
-[step10-screen]: https://i.imgur.com/Nd8rYMJ.png
+[step10-screen]: https://i.imgur.com/Nd8rYMJ.png

docs/client-linux.md

@@ -1,4 +1,4 @@
-# Client installation
+# Linux client setup
 
 It's possible to deploy an ipsec connection on Linux clients.
 Supported distributives are: Debian, Ubuntu, CentOS, Fedora
@@ -14,4 +14,6 @@ The playbook is `deploy_client.yml`
 
 ### Example:
 
-`ansible-playbook deploy_client.yml -e 'client_ip=client.com vpn_user=jack server_ip=vpn-server.com server_ssh_user=root'`
+```shell
+ansible-playbook deploy_client.yml -e 'client_ip=client.com vpn_user=jack server_ip=vpn-server.com server_ssh_user=root'
+```

docs/client-windows.md

@@ -1,6 +1,4 @@
-# Windows
-
-## How to run Algo on Windows 10
+# Windows client prerequisites
 
 Before run Algo, you have to have:
 
@@ -23,10 +21,14 @@ The subsystem will be installed, then Windows will require a reboot. Reboot, the
 
 Install additional packages:
 
-`sudo apt-get update && sudo apt-get install python-pip python-setuptools build-essential libssl-dev libffi-dev python-dev python-virtualenv git -y`
+```shell
+sudo apt-get update && sudo apt-get install python-pip python-setuptools build-essential libssl-dev libffi-dev python-dev python-virtualenv git -y
+```
 
 Clone the Algo repository:
 
-`git clone https://github.com/trailofbits/algo && cd algo`
+```shell
+git clone https://github.com/trailofbits/algo && cd algo
+```
 
 Now, you can go through the [README](https://github.com/trailofbits/algo#deploy-the-algo-server) (start from the 4th step) and deploy your Algo server!

docs/cloud-azure.md

@@ -1,4 +1,4 @@
-### Authenticating with Azure
+# Azure cloud setup
 
 | Instruction | Screenshot(s) |
 | ----------- | ---------- |
@@ -22,7 +22,7 @@ Now you can use Environment Variables:
 * AZURE_TENANT - from the 8th step
 * AZURE_SUBSCRIPTION_ID - from the 9th step
 
-or create the credentials file ~/.azure/credentials:
+or create the credentials file ``~/.azure/credentials`:
 
 ```
 [default]

docs/faq.md

@@ -1,37 +1,37 @@
-## FAQ
+# FAQ
 
-1. [Has Algo been audited?](#1-has-algo-been-audited)
-2. [Why aren't you using Tor?](#2-why-arent-you-using-tor)
-3. [Why aren't you using Racoon, LibreSwan, or OpenSwan?](#3-why-arent-you-using-racoon-libreswan-or-openswan)
-4. [Why aren't you using a memory-safe or verified IKE daemon?](#4-why-arent-you-using-a-memory-safe-or-verified-ike-daemon)
-5. [Why aren't you using OpenVPN?](#5-why-arent-you-using-openvpn)
-6. [Why aren't you using Alpine Linux, OpenBSD, or HardenedBSD?](#6-why-arent-you-using-alpine-linux-openbsd-or-hardenedbsd)
-7. [Where did the name "Algo" come from?](#7-where-did-the-name-algo-come-from)
+[Has Algo been audited?](#has-algo-been-audited)
+[Why aren't you using Tor?](#why-arent-you-using-tor)
+[Why aren't you using Racoon, LibreSwan, or OpenSwan?](#why-arent-you-using-racoon-libreswan-or-openswan)
+[Why aren't you using a memory-safe or verified IKE daemon?](#why-arent-you-using-a-memory-safe-or-verified-ike-daemon)
+[Why aren't you using OpenVPN?](#why-arent-you-using-openvpn)
+[Why aren't you using Alpine Linux, OpenBSD, or HardenedBSD?](#why-arent-you-using-alpine-linux-openbsd-or-hardenedbsd)
+[Where did the name "Algo" come from?](#where-did-the-name-algo-come-from)
 
-### 1. Has Algo been audited?
+## Has Algo been audited?
 
 No. This project is under [active development](https://github.com/trailofbits/algo/projects/1). We're happy to [accept and fix issues](https://github.com/trailofbits/algo/issues) as they are identified. Use Algo at your own risk. If you find a security issue of any severity, please [contact us on Slack](https://empireslacking.herokuapp.com).
 
-### 2. Why aren't you using Tor?
+## Why aren't you using Tor?
 
 The goal of this project is not to provide anonymity, but to ensure confidentiality of network traffic while traveling. Tor introduces new risks that are unsuitable for Algo's intended users. Namely, with Algo, users are in control over the gateway routing their traffic. With Tor, users are at the mercy of [actively](https://www.securityweek2016.tu-darmstadt.de/fileadmin/user_upload/Group_securityweek2016/pets2016/10_honions-sanatinia.pdf) [malicious](https://chloe.re/2015/06/20/a-month-with-badonions/) [exit](https://community.fireeye.com/people/archit.mehta/blog/2014/11/18/onionduke-apt-malware-distributed-via-malicious-tor-exit-node) [nodes](https://www.wired.com/2010/06/wikileaks-documents/).
 
-### 3. Why aren't you using Racoon, LibreSwan, or OpenSwan?
+## Why aren't you using Racoon, LibreSwan, or OpenSwan?
 
 Racoon does not support IKEv2. Racoon2 supports IKEv2 but is not actively maintained. When we looked, the documentation for strongSwan was better than the corresponding documentation for LibreSwan or OpenSwan. strongSwan also has the benefit of a from-scratch rewrite to support IKEv2. I consider such rewrites a positive step when supporting a major new protocol version.
 
-### 4. Why aren't you using a memory-safe or verified IKE daemon?
+## Why aren't you using a memory-safe or verified IKE daemon?
 
 I would, but I don't know of any [suitable ones](https://github.com/trailofbits/algo/issues/68). If you're in the position to fund the development of such a project, [contact us](mailto:info@trailofbits.com). We would be interested in leading such an effort. At the very least, I plan to make modifications to strongSwan and the environment it's deployed in that prevent or significantly complicate exploitation of any latent issues.
 
-### 5. Why aren't you using OpenVPN?
+## Why aren't you using OpenVPN?
 
 OpenVPN does not have out-of-the-box client support on any major desktop or mobile operating system. This introduces user experience issues and requires the user to [update](https://www.exploit-db.com/exploits/34037/) and [maintain](https://www.exploit-db.com/exploits/20485/) the software themselves. OpenVPN depends on the security of [TLS](https://tools.ietf.org/html/rfc7457), both the [protocol](http://arstechnica.com/security/2016/08/new-attack-can-pluck-secrets-from-1-of-https-traffic-affects-top-sites/) and its [implementations](http://arstechnica.com/security/2014/04/confirmed-nasty-heartbleed-bug-exposes-openvpn-private-keys-too/), and we simply trust the server less due to [past](https://sweet32.info/) [security](https://github.com/ValdikSS/openvpn-fix-dns-leak-plugin/blob/master/README.md) [incidents](https://www.exploit-db.com/exploits/34879/).
 
-### 6. Why aren't you using Alpine Linux, OpenBSD, or HardenedBSD?
+## Why aren't you using Alpine Linux, OpenBSD, or HardenedBSD?
 
 Alpine Linux is not supported out-of-the-box by any major cloud provider. We are interested in supporting Free-, Open-, and HardenedBSD. Follow along or contribute to our BSD support in [this issue](https://github.com/trailofbits/algo/issues/35).
 
-### 7. Where did the name "Algo" come from?
+## Where did the name "Algo" come from?
 
 Algo is short for "Al Gore", the **V**ice **P**resident of **N**etworks everywhere for [inventing the Internet](https://www.youtube.com/watch?v=BnFJ8cHAlco).

docs/index.md

@@ -0,0 +1,15 @@
+# Algo VPN documentation
+
+* [Advanced usage](advanced-usage.md)
+* [Ansible roles](ansible-roles.md)
+* Client setup
+  - [Windows](client-windows.md)
+  - [Android](client-android.md)
+  - [Generic/Linux](client-generic.md)
+* Cloud setup
+  - [Azure](cloud-azure.md)
+* Server setup
+  - [RedHat/CentOS 6.x](server-centos6.md)
+  - [FreeBSD](server-freebsd.md)
+* [Troubleshooting](troubleshooting.md)
+* [FAQ](faq.md)

docs/server-freebsd.md

@@ -1,8 +1,8 @@
-# FreeBSD / HardenedBSD
+# FreeBSD / HardenedBSD server setup
 
 It is only possible to install Algo on existing systems only. We support only 11 version for now.
 
-## Pre-paring the system
+## System preparation
 
 Ensure that the following kernel options are enabled:
 
@@ -21,8 +21,10 @@ device	crypto
 
 ## Additional variables
 
-* rebuild_kernel - set to `true` if you want to let Algo to rebuild your kernel if needed (Takes a lot of time)
+* rebuild_kernel - set to `true` if you want to let Algo to rebuild your kernel if needed (takes a lot of time)
 
 ## Installation
 
-`ansible-playbook deploy.yml -t local,vpn -e "server_ip=$server_ip server_user=$server_user IP_subject_alt_name=$server_ip Store_CAKEY=N" --skip-tags cloud`
+```shell
+ansible-playbook deploy.yml -t local,vpn -e "server_ip=$server_ip server_user=$server_user IP_subject_alt_name=$server_ip Store_CAKEY=N" --skip-tags cloud
+```

docs/server-redhat-centos6.md

@@ -1,42 +1,48 @@
-# Algo pre-install steps for Red Hat/CentOS 6.x (currently 6.8)
+# RedHat/CentOS 6.x pre-installation requirements
 
 Many people prefer RedHat or CentOS 6 (or similar variants like Amazon Linux) for to their stability and lack of systemd. Unfortunately, there are a number of dated libraries, notably Python 2.6, that prevent Algo from running without errors. This script will prepare a RedHat, CentOS, or similar VM to deploy to Algo cloud instances.
 
 ## Step 1: Prep for RH/CentOS 6.8/Amazon
 
-```
+```shell
 yum -y -q update
 yum -y -q install epel-release
 ```
 
 Enable any kernel updates:
 
-``reboot`` 
+```shell
+reboot
+```
 
-## Step 2: Install Ansible & launch Algo
+## Step 2: Install Ansible and launch Algo
 
 Fix GPG key warnings during Ansible rpm install:
 
-``rpm --import https://dl.fedoraproject.org/pub/epel/RPM-GPG-KEY-EPEL-6``
+```shell
+rpm --import https://dl.fedoraproject.org/pub/epel/RPM-GPG-KEY-EPEL-6
+```
 
 Fix GPG key warning during official Software Collections (SCL) package install:
 
-``rpm --import https://raw.githubusercontent.com/sclorg/centos-release-scl/master/centos-release-scl/RPM-GPG-KEY-CentOS-SIG-SCLo``
+```shell
+rpm --import https://raw.githubusercontent.com/sclorg/centos-release-scl/master/centos-release-scl/RPM-GPG-KEY-CentOS-SIG-SCLo
+```
 
 RedHat/CentOS 6.x uses Python 2.6 by default, which is explicitly deprecated and produces many warnings and errors, so we must install a safe, non-invasive 2.7 tool set which has to be expressly enabled (and will not survive login sessions and reboots):
 
-```
+```shell
 # Install the Software Collections Library (to enable Python 2.7)
 yum -y -q install centos-release-SCL
 
 # 2.7 will not be used until explicitly enabled, per login session		
 yum -y -q install python27-python-devel python27-python-setuptools python27-python-pip
-yum -y -q install openssl-devel libffi-devel automake gcc gcc-c++ kernel-devel wget unzip ansible nano 
+yum -y -q install openssl-devel libffi-devel automake gcc gcc-c++ kernel-devel wget unzip ansible nano
 
 # Enable 2.7 default for this session (needs re-run between logins & reboots)
 # shellcheck disable=SC1091
 source /opt/rh/python27/enable
-# We're now defaulted to 2.7 
+# We're now defaulted to 2.7
 
 # Upgrade pip itself
 pip -q install --upgrade pip
@@ -48,7 +54,7 @@ pip -q install setuptools --upgrade
 pip -q install virtualenv
 
 wget -q https://github.com/trailofbits/algo/archive/master.zip
-unzip master.zip 
+unzip master.zip
 cd algo-master || echo "No Algo directory found"
 
 # Set up a virtualenv and install the local Algo dependencies (must be run from algo-master)
@@ -61,11 +67,20 @@ nano config.cfg
 ./algo
 ```
 
-## Post-install OSX
+## Post-install macOS
+
+1. Copy `./configs/*mobileconfig` to your local Mac
+
+2. Install the VPN profile on your Mac (10.10+ required)
+
+    ```shell
+    /usr/bin/profiles -I -F ./x.x.x.x_NAME.mobileconfig
+    ```
+
+3. To remove:
 
-* Copy ./configs/*mobileconfig to your local Mac
-* Install the VPN profile on your Mac (10.10+ required)
-  * ``/usr/bin/profiles -I -F ./x.x.x.x_NAME.mobileconfig``
-* To remove: ```/usr/bin/profiles -D -F ./x.x.x.x_NAME.mobileconfig```
+    ```shell
+    /usr/bin/profiles -D -F ./x.x.x.x_NAME.mobileconfig
+    ```
 
 The VPN connection will now appear under Networks (which can be pinned to the top menu bar if preferred)

docs/troubleshooting.md

@@ -1,3 +1,5 @@
+# Troubleshooting
+
 ## Table of Contents
 
 1. [Error: "You have not agreed to the Xcode license agreements"](#1-error-you-have-not-agreed-to-the-xcode-license-agreements)