Archives
/
algo
mirror of https://github.com/trailofbits/algo
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update docs (#1430)

Browse Source 
* Point additional docs to index.md

* Update index.md

Moves existing links from readme.md over to update this separate (previously out-of-date, redundant) page.

* Update documented Ansible roles

* Fix broken links in index.md

* Complete index.md

As a general rule all docs should be linked to from the index file. No?

* Update SSH access instructions

* Clarify SSH access instructions

* Delete setup-roles.md

* Update deploy-from-ansible.md

Change header, insert text from setup-roles.md

* Remove link to setup-roles from index.md

* Fix typos

* Update deploy-from-ansible.md

Document other `--skip-tags` options, as well as examples for Vultr and Scaleway variables.

* Update deploy-from-ansible.md

Added region examples for AWS and Lightsail. Happy to add other examples if people have experience with other providers.
pull/1405/head
TC1977 5 years ago committed by Jack Ivanov
parent 638a355196
commit 38ebe4893d
4 changed files with 53 additions and 90 deletions
Show Stats Download Patch File Download Diff File

50
README.md
Unescape Escape View File

@ -72,15 +72,15 @@ That's it! You will get the message below when the server deployment process com
You can now setup clients to connect it, e.g. your iPhone or laptop. Proceed to [Configure the VPN Clients](#configure-the-vpn-clients) below.
```
"\"#----------------------------------------------------------------------#\"",
"\"# Congratulations! #\"",
"\"# Your Algo server is running. #\"",
"\"# Config files and certificates are in the ./configs/ directory. #\"",
"\"# Go to https://whoer.net/ after connecting #\"",
"\"# and ensure that all your traffic passes through the VPN. #\"",
"\"# Local DNS resolver 172.16.0.1 #\"",
"\"# The p12 and SSH keys password is XXXXXXXX #\"",
"\"#----------------------------------------------------------------------#\"",
"# Congratulations! #"
"# Your Algo server is running. #"
"# Config files and certificates are in the ./configs/ directory. #"
"# Go to https://whoer.net/ after connecting #"
"# and ensure that all your traffic passes through the VPN. #"
"# Local DNS resolver 172.16.0.1 #"
"# The p12 and SSH keys password for new users is XXXXXXXX #"
"# The CA key password is XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX #"
"# Shell access: ssh -i configs/algo.pem root@xxx.xxx.xx.xx #"
```
## Configure the VPN Clients
@ -166,16 +166,14 @@ Use the example command below to start an SSH tunnel by replacing `user` and `ip
## SSH into Algo Server
To SSH into the Algo server for administrative purposes you can use the example command below by replacing `ip` with your own:
Your Algo server is configured for key-only SSH access for administrative purposes. Open the Terminal app, `cd` into the `algo-master` directory where you originally downloaded Algo, and then use the command listed on the success message:
`ssh root@ip -i ~/.ssh/algo.pem`
`ssh -i configs/algo.pem user@ip`
If you find yourself regularly logging into Algo then it will be useful to load your Algo ssh key automatically. Add the following snippet to the bottom of `~/.bash_profile` to add it to your shell environment permanently.
where `user` is either `root` or `ubuntu` as listed on the success message, and `ip` is the IP address of your Algo server. If you find yourself regularly logging into the server then it will be useful to load your Algo ssh key automatically. Add the following snippet to the bottom of `~/.bash_profile` to add it to your shell environment permanently.
`ssh-add ~/.ssh/algo > /dev/null 2>&1`
Note the admin username is `ubuntu` instead of `root` on providers other than Digital Ocean.
## Adding or Removing Users
If you chose to save the CA certificate during the deploy process, then Algo's own scripts can easily add and remove users from the VPN server.
@ -187,29 +185,7 @@ If you chose to save the CA certificate during the deploy process, then Algo's o
After this process completes, the Algo VPN server will contain only the users listed in the `config.cfg` file.
## Additional Documentation
* Setup instructions
- Documentation for available [Ansible roles](docs/setup-roles.md)
- Deploy from [Fedora Workstation (26)](docs/deploy-from-fedora-workstation.md)
- Deploy from [RedHat/CentOS 6.x](docs/deploy-from-redhat-centos6.md)
- Deploy from [Windows](docs/deploy-from-windows.md)
- Deploy from [Ansible](docs/deploy-from-ansible.md) directly
* Client setup
- Setup [Android](docs/client-android.md) clients
- Setup [Generic/Linux](docs/client-linux.md) clients with Ansible
- Setup Ubuntu clients to use [WireGuard](docs/client-linux-wireguard.md)
- Setup Apple devices to use [IPSEC](docs/client-apple-ipsec.md)
* Cloud setup
- Configure [Amazon EC2](docs/cloud-amazon-ec2.md)
- Configure [Azure](docs/cloud-azure.md)
- Configure [DigitalOcean](docs/cloud-do.md)
- Configure [Google Cloud Platform](docs/cloud-gce.md)
- Configure [Scaleway](docs/cloud-scaleway.md)
- Configure [Vultr](docs/cloud-vultr.md)
* Advanced Deployment
- Deploy to your own [FreeBSD](docs/deploy-to-freebsd.md) server
- Deploy to your own [Ubuntu 18.04](docs/deploy-to-ubuntu.md) server
- Deploy to an [unsupported cloud provider](docs/deploy-to-unsupported-cloud.md)
* [Deployment instructions, cloud provider setup instructions, and further client setup instructions available here.](docs/index.md)
* [FAQ](docs/faq.md)
* [Troubleshooting](docs/troubleshooting.md)

49
docs/deploy-from-ansible.md
Unescape Escape View File

@ -1,10 +1,10 @@
# Scripted Deployment
# Deployment from Ansible
Before you begin, make sure you have installed all the dependencies necessary for your operating system as described in the [README](../README.md).
You can deploy Algo non-interactively by running the Ansible playbooks directly with `ansible-playbook`.
`ansible-playbook` accepts "tags" via the `-t` or `TAGS` options. You can pass tags as a list of comma separated values. Ansible will only run plays (install roles) with the specified tags.
`ansible-playbook` accepts "tags" via the `-t` or `TAGS` options. You can pass tags as a list of comma separated values. Ansible will only run plays (install roles) with the specified tags. You can also use the `--skip-tags` option to skip certain parts of the install, such as `iptables` (overwrite iptables rules), `ipsec` (install strongSwan), `wireguard` (install Wireguard).
`ansible-playbook` accepts variables via the `-e` or `--extra-vars` option. You can pass variables as space separated key=value pairs. Algo requires certain variables that are listed below.
@ -23,25 +23,25 @@ ansible-playbook main.yml -e "provider=digitalocean
do_token=token"
```
See below for more information about providers and extra variables
See below for more information about variables and roles.
### Variables
- `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. Default: false
- `ondemand_wifi` - (Optional. See `ondemand_wifi_exclude`) VPN On Demand when connected to WiFi networks. Default: false
- `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_wifi_exclude` (Required if `ondemand_wifi` set) - WiFi networks to exclude from using the VPN. Comma-separated values
- `local_dns` - (Optional) Enable a DNS resolver. Default: false
- `ssh_tunneling` - (Optional) Enable SSH tunneling for each user. Default: false
- `windows` - (Optional) Enables compatible ciphers and key exchange to support Windows clients, less secure. Default: false
- `store_cakey` - (Optional) Whether or not keep the CA key (required to add users in the future, but less secure). Default: false
If any of those unspecified ansible will ask the user to input
If any of the above variables are unspecified, ansible will ask the user to input them.
### Ansible roles
Roles can be activated by specifying an extra variable `provider`
Cloud roles can be activated by specifying an extra variable `provider`.
Cloud roles:
@ -55,13 +55,25 @@ Cloud roles:
Server roles:
- role: vpn
- role: strongswan
* Installs [strongSwan](https://www.strongswan.org/)
* Enables AppArmor, limits CPU and memory access, and drops user privileges
* Builds a Certificate Authority (CA) with [easy-rsa-ipsec](https://github.com/ValdikSS/easy-rsa-ipsec) and creates one client certificate per user
* Bundles the appropriate certificates into Apple mobileconfig profiles and Powershell scripts for each user
- role: dns_adblocking
* Installs the [dnsmasq](http://www.thekelleys.org.uk/dnsmasq/doc.html) local resolver with a blacklist for advertising domains
* Constrains dnsmasq with AppArmor and cgroups CPU and memory limitations
- role: dns_encryption
* Installs [dnscrypt-proxy](https://github.com/jedisct1/dnscrypt-proxy)
* Constrains dnscrypt-proxy with AppArmor and cgroups CPU and memory limitations
- role: ssh_tunneling
* Adds a restricted `algo` group with no shell access and limited SSH forwarding options
* Creates one limited, local account and an SSH public key for each user
- role: wireguard
* Installs a [Wireguard](https://www.wireguard.com/) server, with a startup script, and automatic checks for upgrades
* Creates wireguard.conf files for Linux clients as well as QR codes for Apple/Android clients
Note: The `vpn` role generates Apple profiles with On-Demand Wifi and Cellular if you pass the following variables:
Note: The `strongswan` role generates Apple profiles with On-Demand Wifi and Cellular if you pass the following variables:
- ondemand_wifi: true
- ondemand_wifi_exclude: HomeNet,OfficeWifi
@ -91,9 +103,9 @@ Possible options can be gathered calling to https://api.digitalocean.com/v2/regi
Required variables:
- aws_access_key
- aws_access_key: `AKIA...`
- aws_secret_key
- region
- region: e.g. `us-east-1`
Possible options can be gathered via cli `aws ec2 describe-regions`
@ -180,8 +192,8 @@ Required variables:
Required variables:
- [vultr_config](https://trailofbits.github.io/algo/cloud-vultr.html)
- [region](https://api.vultr.com/v1/regions/list)
- [vultr_config](https://trailofbits.github.io/algo/cloud-vultr.html): /path/to/.vultr.ini
- [region](https://api.vultr.com/v1/regions/list): e.g. `Chicago`, `'New Jersey'`
### Azure
@ -197,9 +209,9 @@ Required variables:
Required variables:
- aws_access_key
- aws_access_key: `AKIA...`
- aws_secret_key
- region
- region: e.g. `us-east-1`
Possible options can be gathered via cli `aws lightsail get-regions`
@ -231,12 +243,7 @@ Possible options can be gathered via cli `aws lightsail get-regions`
Required variables:
- [scaleway_token](https://www.scaleway.com/docs/generate-an-api-token/)
- region
Possible regions:
- ams1
- par1
- region: e.g. ams1, par1
### OpenStack

16
docs/index.md
Unescape Escape View File

@ -1,21 +1,29 @@
# Algo VPN documentation
* Setup instructions
- Documentation for available [Ansible roles](setup-roles.md)
* Deployment instructions
- Deploy from [Fedora Workstation (26)](deploy-from-fedora-workstation.md)
- Deploy from [RedHat/CentOS 6.x](deploy-from-redhat-centos6.md)
- Deploy from [Windows](deploy-from-windows.md)
- Deploy from [Ansible](deploy-from-ansible.md) directly
- Deploy from a [Docker container](deploy-from-docker.md)
- Deploy from [Ansible](deploy-from-ansible.md) non-interactively
- Deploy onto a [cloud server at time of creation](deploy-from-script-or-cloud-init-to-localhost.md)
* Client setup
- Setup [Android](client-android.md) clients
- Setup [Generic/Linux](client-linux.md) clients with Ansible
* Cloud setup
- Setup Ubuntu clients to use [WireGuard](client-linux-wireguard.md)
- Setup Apple devices to use [IPSEC](client-apple-ipsec.md)
- Setup Macs running macOS 10.13 or older to use [Wireguard](client-macos-wireguard.md)
- Manual Windows 10 client setup for [IPSEC](client-windows.md)
* Cloud provider setup
- Configure [Amazon EC2](cloud-amazon-ec2.md)
- Configure [Azure](cloud-azure.md)
- Configure [DigitalOcean](cloud-do.md)
- Configure [Google Cloud Platform](cloud-gce.md)
- Configure [Vultr](cloud-vultr.md)
* Advanced Deployment
- Deploy to your own [FreeBSD](deploy-to-freebsd.md) server
- Deploy to your own [Ubuntu 18.04](deploy-to-ubuntu.md) server
- Deploy to an [unsupported cloud provider](deploy-to-unsupported-cloud.md)
* [FAQ](faq.md)
* [Firewalls](firewalls.md)
* [Troubleshooting](troubleshooting.md)

28
docs/setup-roles.md
Unescape Escape View File

@ -1,28 +0,0 @@
# Ansible Roles
## Required roles
* **Common**
* Installs several required packages and software updates, then reboots if necessary
* Configures network interfaces, and enables packet forwarding on them
* **VPN**
* Installs [strongSwan](https://www.strongswan.org/), enables AppArmor, limits CPU and memory access, and drops user privileges
* Builds a Certificate Authority (CA) with [easy-rsa-ipsec](https://github.com/ValdikSS/easy-rsa-ipsec) and creates one client certificate per user
* 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
* **Security Enhancements**
* Enables [unattended-upgrades](https://help.ubuntu.com/community/AutomaticSecurityUpdates) to ensure available patches are always applied
* Modify features like core dumps, kernel parameters, and SUID binaries to limit possible attacks
* Enhances SSH with modern ciphers and seccomp, and restricts access to old or unwanted features like X11 forwarding and SFTP
* **DNS-based Adblocking**
* Install the [dnsmasq](http://www.thekelleys.org.uk/dnsmasq/doc.html) local resolver with a blacklist for advertising domains
* Constrains dnsmasq with AppArmor and cgroups CPU and memory limitations
* **DNS encryption**
* Install [dnscrypt-proxy](https://github.com/jedisct1/dnscrypt-proxy)
* Constrains dingo with AppArmor and cgroups CPU and memory limitations
* **SSH Tunneling**
* Adds a restricted `algo` group with no shell access and limited SSH forwarding options
* Creates one limited, local account per user and an SSH public key for each
Write Preview
Loading…
Cancel
Save