trailofbits · jackivanov · Dec 10, 2019 · Oct 9, 2019 · Oct 9, 2019 · Oct 9, 2019
@@ -4,12 +4,14 @@
 [![Twitter](https://img.shields.io/twitter/url/https/twitter.com/fold_left.svg?style=social&label=Follow%20%40AlgoVPN)](https://twitter.com/AlgoVPN)
 [![TravisCI Status](https://api.travis-ci.org/trailofbits/algo.svg?branch=master)](https://travis-ci.org/trailofbits/algo)
 
-Algo VPN is a set of Ansible scripts that simplify the setup of a personal Wireguard and IPSEC VPN. It uses the most secure defaults available, works with common cloud providers, and does not require client software on most devices. See our [release announcement](https://blog.trailofbits.com/2016/12/12/meet-algo-the-vpn-that-works/) for more information.
+Algo VPN is a set of Ansible scripts that simplify the setup of a personal WireGuard and IPsec VPN. It uses the most secure defaults available and works with common cloud providers. See our [release announcement](https://blog.trailofbits.com/2016/12/12/meet-algo-the-vpn-that-works/) for more information.
 
 ## Features
 
-* Supports only IKEv2 with strong crypto (AES-GCM, SHA2, and P-256) and [WireGuard](https://www.wireguard.com/)
-* Generates Apple profiles to auto-configure iOS and macOS devices
+* Supports only IKEv2 with strong crypto (AES-GCM, SHA2, and P-256) for iOS, macOS, and Linux
+* Supports [WireGuard](https://www.wireguard.com/) for all of the above, in addition to Android and Windows 10
+* Generates .conf files and QR codes for iOS, macOS, Android, and Windows WireGuard clients
+* Generates Apple profiles to auto-configure iOS and macOS devices for IPsec - no client software required
 * Includes a helper script to add and remove users
 * Blocks ads with a local DNS resolver (optional)
 * Sets up limited SSH users for tunneling traffic (optional)
@@ -21,7 +23,6 @@ Algo VPN is a set of Ansible scripts that simplify the setup of a personal Wireg
 * Does not support legacy cipher suites or protocols like L2TP, IKEv1, or RSA
 * Does not install Tor, OpenVPN, or other risky servers
 * Does not depend on the security of [TLS](https://tools.ietf.org/html/rfc7457)
-* Does not require client software on most platforms
 * Does not claim to provide anonymity or censorship avoidance
 * Does not claim to protect you from the [FSB](https://en.wikipedia.org/wiki/Federal_Security_Service), [MSS](https://en.wikipedia.org/wiki/Ministry_of_State_Security_(China)), [DGSE](https://en.wikipedia.org/wiki/Directorate-General_for_External_Security), or [FSM](https://en.wikipedia.org/wiki/Flying_Spaghetti_Monster)
 
@@ -42,7 +43,7 @@ The easiest way to get an Algo server running is to run it on your local system
     - **macOS:** Apple does not provide a suitable version of Python 3 with macOS. Here are two ways to obtain one:
         * Use the [Homebrew](https://brew.sh) package manager. After installing Homebrew install Python 3 by running `brew install python3`.
 
-        * Download and install the latest stable [Python 3.7 package](https://www.python.org/downloads/mac-osx/) (currently Python 3.8 will not work). Be sure to run the included *Install Certificates* command from Finder.
+        * Download and install the latest stable [Python 3.7.x package](https://www.python.org/downloads/mac-osx/) (currently Python 3.8 will not work). Be sure to run the included *Install Certificates* command from Finder.
 
         See [Deploy from macOS](docs/deploy-from-macos.md) for more detailed information on installing Python 3 on macOS.
 
@@ -78,7 +79,7 @@ The easiest way to get an Algo server running is to run it on your local system
     ```
     On Fedora add the option `--system-site-packages` to the first command above. On macOS install the C compiler if prompted.
 
-5. **List the users to create.** Open the file `config.cfg` in your favorite text editor. Specify the users you wish to create in the `users` list. Create a unique user for each device you plan to connect to your VPN. If you want to be able to add or delete users later, you **must** select `yes` at the `Do you want to retain the keys (PKI)?` prompt during the deployment.
+5. **Set your configuration options.** Open the file `config.cfg` in your favorite text editor. Specify the users you wish to create in the `users` list. Create a unique user for each device you plan to connect to your VPN. If you want to be able to add or delete users later, you **must** select `yes` at the `Do you want to retain the keys (PKI)?` prompt during the deployment. You should also review the other options before deployment, as changing your mind about them later [may require you to deploy a brand new server](https://github.com/trailofbits/algo/blob/master/docs/faq.md#i-deployed-an-algo-server-can-you-update-it-with-new-features).
 
 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 [here](docs/deploy-from-ansible.md).
 

@@ -9,42 +9,17 @@ users:
   - laptop
   - desktop
 
-### Advanced users only below this line ###
-
-# Store the PKI in a ram disk. Enabled only if store_pki (retain the PKI) is set to false
-# Supports on MacOS and Linux only (including Windows Subsystem for Linux)
-pki_in_tmpfs: true
-
-# If True re-init all existing certificates. Boolean
-keys_clean_all: False
+### Review these options BEFORE you run Algo, as they are very difficult/impossible to change after the server is deployed.
 
 # Deploy StrongSwan to enable IPsec support
 ipsec_enabled: true
 
-# StrongSwan log level
-# https://wiki.strongswan.org/projects/strongswan/wiki/LoggerConfiguration
-strongswan_log_level: 2
-
-# rightsourceip for ipsec
-# ipv4
-strongswan_network: 10.19.48.0/24
-# ipv6
-strongswan_network_ipv6: 'fd9d:bc11:4020::/48'
-
 # Deploy WireGuard
 # WireGuard will listen on 51820/UDP. You might need to change to another port
 # if your network blocks this one. Be aware that 53/UDP (DNS) is blocked on some
 # mobile data networks.
 wireguard_enabled: true
 wireguard_port: 51820
-# If you're behind NAT or a firewall and you want to receive incoming connections long after network traffic has gone silent.
-# This option will keep the "connection" open in the eyes of NAT.
-# See: https://www.wireguard.com/quickstart/#nat-and-firewall-traversal-persistence
-wireguard_PersistentKeepalive: 0
-
-# WireGuard network configuration
-wireguard_network_ipv4: 10.19.49.0/24
-wireguard_network_ipv6: fd9d:bc11:4021::/48
 
 # Reduce the MTU of the VPN tunnel
 # Some cloud and internet providers use a smaller MTU (Maximum Transmission
@@ -69,6 +44,29 @@ adblock_lists:
 # DNS encryption can not be disabled if DNS adblocking is enabled
 dns_encryption: true
 
+# Block traffic between connected clients. Change this to false to enable
+# connected clients to reach each other, as well as other computers on the
+# same LAN as your Algo server (i.e. the "road warrior" setup). In this
+# case, you may also want to enable SMB/CIFS and NETBIOS traffic below.
+BetweenClients_DROP: true
+
+# Block SMB/CIFS traffic
+block_smb: true
+
+# Block NETBIOS traffic
+block_netbios: true
+
+# Your Algo server will automatically install security updates. Some updates
+# require a reboot to take effect but your Algo server will not reboot itself
+# automatically unless you change 'enabled' below from 'false' to 'true', in
+# which case a reboot will take place if necessary at the time specified (as
+# HH:MM) in the time zone of your Algo server. The default time zone is UTC.
+unattended_reboot:
+  enabled: false
+  time: 06:00
+
+### Advanced users only below this line ###
+
 # DNS servers which will be used if 'dns_encryption' is 'true'. Multiple
 # providers may be specified, but avoid mixing providers that filter results
 # (like Cisco) with those that don't (like Cloudflare) or you could get
@@ -92,27 +90,36 @@ dns_servers:
     - 2606:4700:4700::1111
     - 2606:4700:4700::1001
 
-# Randomly generated IP address for the local dns resolver
-local_service_ip: "{{ '172.16.0.1' | ipmath(1048573 | random(seed=algo_server_name + ansible_fqdn)) }}"
-local_service_ipv6: "{{ 'fd00::1' | ipmath(1048573 | random(seed=algo_server_name + ansible_fqdn)) }}"
+# Store the PKI in a ram disk. Enabled only if store_pki (retain the PKI) is set to false
+# Supports on MacOS and Linux only (including Windows Subsystem for Linux)
+pki_in_tmpfs: true
 
-# Your Algo server will automatically install security updates. Some updates
-# require a reboot to take effect but your Algo server will not reboot itself
-# automatically unless you change 'enabled' below from 'false' to 'true', in
-# which case a reboot will take place if necessary at the time specified (as
-# HH:MM) in the time zone of your Algo server. The default time zone is UTC.
-unattended_reboot:
-  enabled: false
-  time: 06:00
+# Set this to 'true' when running './algo update-users' if you want ALL users to get new certs, not just new users. 
+keys_clean_all: false
 
-# Block traffic between connected clients
-BetweenClients_DROP: true
+# StrongSwan log level
+# https://wiki.strongswan.org/projects/strongswan/wiki/LoggerConfiguration
+strongswan_log_level: 2
 
-# Block SMB/CIFS traffic
-block_smb: true
+# rightsourceip for ipsec
+# ipv4
+strongswan_network: 10.19.48.0/24
+# ipv6
+strongswan_network_ipv6: 'fd9d:bc11:4020::/48'
+
+# If you're behind NAT or a firewall and you want to receive incoming connections long after network traffic has gone silent.
+# This option will keep the "connection" open in the eyes of NAT.
+# See: https://www.wireguard.com/quickstart/#nat-and-firewall-traversal-persistence
+wireguard_PersistentKeepalive: 0
+
+# WireGuard network configuration
+wireguard_network_ipv4: 10.19.49.0/24
+wireguard_network_ipv6: fd9d:bc11:4021::/48
+
+# Randomly generated IP address for the local dns resolver
+local_service_ip: "{{ '172.16.0.1' | ipmath(1048573 | random(seed=algo_server_name + ansible_fqdn)) }}"
+local_service_ipv6: "{{ 'fd00::1' | ipmath(1048573 | random(seed=algo_server_name + ansible_fqdn)) }}"
 
-# Block NETBIOS traffic
-block_netbios: true
 
 congrats:
   common: |
@@ -143,7 +150,7 @@ cloud_providers:
     size: s-1vcpu-1gb
     image: "ubuntu-19-04-x64"
   ec2:
-    # Change the encrypted flag to "true" to enable AWS volume encryption, for encryption of data at rest.
+    # Change the encrypted flag to "false" to disable AWS volume encryption.
     encrypted: true
     # Set use_existing_eip to "true" if you want to use a pre-allocated Elastic IP
     # Additional prompt will be raised to determine which IP to use

@@ -26,12 +26,12 @@ See below for more information about variables and roles.
 
 - `provider` - (Required) The provider to use. See possible values below
 - `server_name` - (Required) Server name. Default: algo
-- `ondemand_cellular` (Optional) VPN On Demand when connected to cellular networks with IPsec. Default: false
-- `ondemand_wifi` - (Optional. See `ondemand_wifi_exclude`) VPN On Demand when connected to WiFi networks with IPsec. Default: false
+- `ondemand_cellular` (Optional) Enables VPN On Demand when connected to cellular networks for iOS/macOS clients using IPsec. Default: false
+- `ondemand_wifi` - (Optional. See `ondemand_wifi_exclude`) Enables VPN On Demand when connected to WiFi networks for iOS/macOS clients using IPsec. Default: false
 - `ondemand_wifi_exclude` (Required if `ondemand_wifi` set) - WiFi networks to exclude from using the VPN. Comma-separated values
 - `dns_adblocking` - (Optional) Enables dnscrypt-proxy adblocking. Default: false
 - `ssh_tunneling` - (Optional) Enable SSH tunneling for each user. Default: false
-- `store_cakey` - (Optional) Whether or not keep the CA key (required to add users in the future, but less secure). Default: false
+- `store_pki` - (Optional) Whether or not keep the CA key (required to add users in the future, but less secure). Default: false
 
 If any of the above variables are unspecified, ansible will ask the user to input them.
 

@@ -1,8 +1,7 @@
 # Deploy from script or cloud-init
 
 You can use `install.sh` to prepare the environment and deploy AlgoVPN on the local Ubuntu server in one shot using cloud-init, or run the script directly on the server after it's been created. 
-
-The script doesn't configure any parameters in your cloud, so it's on your own to configure related [firewall rules](/docs/firewalls.md), a floating ip address and other resources you may need. The output of the install script (including the p12 and CA passwords) and user config files will be installed into the `/opt/algo` directory.
+The script doesn't configure any parameters in your cloud, so you're on your own to configure related [firewall rules](/docs/firewalls.md), a floating IP address and other resources you may need. The output of the install script (including the p12 and CA passwords) can be found at `/var/log/algo.log`, and user config files will be installed into the `/opt/algo/configs/localhost` directory. If you need to update users later, `cd /opt/algo`, change the user list in `config.cfg`, install additional dependencies as in step 4 of the [main README](https://github.com/trailofbits/algo/blob/master/README.md), and run `./algo update-users` from that directory.
 
 ## Cloud init deployment
 

@@ -8,4 +8,11 @@ Install to existing Ubuntu 18.04, 19.04, or 19.10 server (Advanced)
 ```
 Make sure your target server is running an unmodified copy of the operating system version specified. The target can be the same system where you've installed the Algo scripts, or a remote system that you are able to access as root via SSH without needing to enter the SSH key passphrase (such as when using `ssh-agent`).
 
+# Road Warrior setup
+
+Some may find it useful to set up an Algo server on an Ubuntu box on your home LAN, with the intention of being able to securely access your LAN and any resources on it when you're traveling elsewhere (the ["road warrior" setup](https://en.wikipedia.org/wiki/Road_warrior_(computing))). A few tips if you're doing so:
+- Make sure you forward any [relevant incoming ports](/docs/firewalls.md#external-firewall) to the Algo server from your router;
+- Change `BetweenClients_DROP` in `config.cfg` to `false`, and also consider changing `block_smb` and `block_netbios` to `false`;
+- If you want to use a DNS server on your LAN to resolve local domain names properly (e.g. a Pi-hole), set the `dns_encryption` flag in `config.cfg` to `false`, and change `dns_servers` to the local DNS server IP (i.e. `192.168.1.2`).
+
 **PLEASE NOTE**: Algo is intended for use to create a _dedicated_ VPN server. No uninstallation option is provided. If you install Algo on an existing server any existing services might break. In particular, the firewall rules will be overwritten. See [AlgoVPN and Firewalls](/docs/firewalls.md) for more information.