mirror of
https://github.com/trailofbits/algo.git
synced 2025-08-02 19:03:04 +02:00
Update README for Python 3 (#1564)
* Update README for Python 3 * Remove tabs and tweak instructions * Remove cosmetic command indentation * Update README.md
This commit is contained in:
David Myers
Jack Ivanov
parent
0f3788b97b
commit
4bee6e9efa
9 changed files with 86 additions and 166 deletions
91
README.md
91
README.md
|
|
@ -27,49 +27,57 @@ Algo VPN is a set of Ansible scripts that simplify the setup of a personal Wireg
|
||||||
|
|
||||||
## Deploy the Algo Server
|
## Deploy the Algo Server
|
||||||
|
|
||||||
The easiest way to get an Algo server running is to run it on your local machine and let it set up a _new_ virtual machine in the cloud for you.
|
The easiest way to get an Algo server running is to run it on your local system and let it set up a _new_ virtual machine in the cloud for you.
|
||||||
|
|
||||||
1. **Setup an account on a cloud hosting provider.** Algo supports [DigitalOcean](https://m.do.co/c/4d7f4ff9cfe4) (most user friendly), [Amazon Lightsail](https://aws.amazon.com/lightsail/), [Amazon EC2](https://aws.amazon.com/), [Vultr](https://www.vultr.com/), [Microsoft Azure](https://azure.microsoft.com/), [Google Compute Engine](https://cloud.google.com/compute/), [Scaleway](https://www.scaleway.com/), [DreamCompute](https://www.dreamhost.com/cloud/computing/) or other OpenStack-based cloud hosting, [Exoscale](https://www.exoscale.com) or other CloudStack-based cloud hosting, or [Hetzner Cloud](https://www.hetzner.com/).
|
1. **Setup an account on a cloud hosting provider.** Algo supports [DigitalOcean](https://m.do.co/c/4d7f4ff9cfe4) (most user friendly), [Amazon Lightsail](https://aws.amazon.com/lightsail/), [Amazon EC2](https://aws.amazon.com/), [Vultr](https://www.vultr.com/), [Microsoft Azure](https://azure.microsoft.com/), [Google Compute Engine](https://cloud.google.com/compute/), [Scaleway](https://www.scaleway.com/), [DreamCompute](https://www.dreamhost.com/cloud/computing/) or other OpenStack-based cloud hosting, [Exoscale](https://www.exoscale.com) or other CloudStack-based cloud hosting, or [Hetzner Cloud](https://www.hetzner.com/).
|
||||||
|
|
||||||
2. **[Download Algo](https://github.com/trailofbits/algo/archive/master.zip).** Unzip it in a convenient location on your local machine.
|
2. **Get a copy of Algo.** The Algo scripts will be installed on your local system. There are two ways to get a copy:
|
||||||
|
|
||||||
3. **Install Algo's core dependencies.** Open the Terminal. `cd` into the `algo-master` directory where you unzipped Algo, then run:
|
- Download the [ZIP file](https://github.com/trailofbits/algo/archive/master.zip). Unzip the file to create a directory named `algo-master` containing the Algo scripts.
|
||||||
|
|
||||||
- macOS:
|
- Run the command `git clone https://github.com/trailofbits/algo.git` to create a directory named `algo` containing the Algo scripts.
|
||||||
|
|
||||||
|
3. **Install Algo's core dependencies.** Algo requires that Python 3 and one supporting package are installed on your system.
|
||||||
|
|
||||||
|
- **macOS:** Apple does not provide Python 3 with macOS. There are two ways to obtain it:
|
||||||
|
* 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 package](https://www.python.org/downloads/mac-osx/). Be sure to run the included *Install Certificates* command from Finder.
|
||||||
|
|
||||||
|
Once Python 3 is installed on your Mac, from Terminal run:
|
||||||
```bash
|
```bash
|
||||||
$ python3 -m ensurepip --user
|
python3 -m pip install --upgrade virtualenv
|
||||||
$ python3 -m pip install --user --upgrade virtualenv
|
|
||||||
```
|
```
|
||||||
- Linux (deb-based):
|
|
||||||
```bash
|
|
||||||
$ sudo apt-get update && sudo apt-get install \
|
|
||||||
build-essential \
|
|
||||||
libssl-dev \
|
|
||||||
libffi-dev \
|
|
||||||
python3-dev \
|
|
||||||
python3-pip \
|
|
||||||
python3-setuptools \
|
|
||||||
python3-virtualenv -y
|
|
||||||
```
|
|
||||||
- Linux (rpm-based): See the pre-installation documentation for [RedHat/CentOS 6.x](docs/deploy-from-redhat-centos6.md) or [Fedora](docs/deploy-from-fedora-workstation.md)
|
|
||||||
- Windows: See the [Windows documentation](docs/deploy-from-windows.md)
|
|
||||||
|
|
||||||
4. **Install Algo's remaining dependencies.** Use the same Terminal window as the previous step and run:
|
- **Linux:** Recent releases of Ubuntu, Debian, and Fedora come with Python 3 already installed. Make sure your system is up-to-date and install the needed supporting package:
|
||||||
|
* Ubuntu and Debian:
|
||||||
```bash
|
```bash
|
||||||
$ python3 -m virtualenv --python="$(command -v python3)" .env &&
|
sudo apt install -y python3-pip python3-virtualenv
|
||||||
|
```
|
||||||
|
* Fedora:
|
||||||
|
```bash
|
||||||
|
sudo dnf install -y python3-virtualenv
|
||||||
|
```
|
||||||
|
* Red Hat and CentOS: See this [documentation](docs/deploy-from-redhat-centos6.md).
|
||||||
|
|
||||||
|
- **Windows:** Use the Windows Subsystem for Linux (WSL) to create your own copy of Ubuntu running under Windows from which to install and run Algo. See the [Windows documentation](docs/deploy-from-windows.md).
|
||||||
|
|
||||||
|
4. **Install Algo's remaining dependencies.** You'll need to run these commands from the Algo directory each time you download a new copy of Algo. In a Terminal window `cd` into the `algo-master` (ZIP file) or `algo` (`git clone`) directory and run:
|
||||||
|
```bash
|
||||||
|
python3 -m virtualenv --python="$(command -v python3)" .env &&
|
||||||
source .env/bin/activate &&
|
source .env/bin/activate &&
|
||||||
python3 -m pip install -U pip virtualenv &&
|
python3 -m pip install -U pip virtualenv &&
|
||||||
python3 -m pip install -r requirements.txt
|
python3 -m pip install -r requirements.txt
|
||||||
```
|
```
|
||||||
On macOS, you may be prompted to install `cc`. You should press accept if so.
|
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 `config.cfg` in your favorite text editor. Specify the users you wish to create in the `users` list. If you want to be able to add or delete users later, you **must** select `yes` for the `Do you want to retain the CA key?` prompt during the deployment. Make a unique user for each device you plan to setup.
|
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.
|
||||||
|
|
||||||
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 [deploy-from-ansible.md](docs/deploy-from-ansible.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 [here](docs/deploy-from-ansible.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 and the CA key in case you need them later, **they will only be displayed this time**.
|
That's it! You will get the message below when the server deployment process completes. Take note of the p12 (user certificate) password and the CA key in case you need them later, **they will only be displayed this time**.
|
||||||
|
|
||||||
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.
|
You can now set up clients to connect to your VPN. Proceed to [Configure the VPN Clients](#configure-the-vpn-clients) below.
|
||||||
|
|
||||||
```
|
```
|
||||||
"# Congratulations! #"
|
"# Congratulations! #"
|
||||||
|
|
@ -111,36 +119,13 @@ WireGuard is used to provide VPN services on Windows. Algo generates a WireGuard
|
||||||
|
|
||||||
Install the [WireGuard VPN Client](https://www.wireguard.com/install/#windows-7-8-81-10-2012-2016-2019). Import the generated `wireguard/<username>.conf` file to your device, then setup a new connection with it.
|
Install the [WireGuard VPN Client](https://www.wireguard.com/install/#windows-7-8-81-10-2012-2016-2019). Import the generated `wireguard/<username>.conf` file to your device, then setup a new connection with it.
|
||||||
|
|
||||||
### Linux Network Manager Clients (e.g., Ubuntu, Debian, or Fedora Desktop)
|
### Linux WireGuard Clients
|
||||||
|
|
||||||
Network Manager does not support AES-GCM. In order to support Linux Desktop clients, choose the "compatible" cryptography during the deploy process and use at least Network Manager 1.4.1. See [Issue #263](https://github.com/trailofbits/algo/issues/263) for more information.
|
WireGuard works great with Linux clients. See [this page](docs/client-linux-wireguard.md) for an example of how to configure WireGuard on Ubuntu.
|
||||||
|
|
||||||
### Linux strongSwan Clients (e.g., OpenWRT, Ubuntu Server, etc.)
|
### Linux strongSwan IPsec Clients (e.g., OpenWRT, Ubuntu Server, etc.)
|
||||||
|
|
||||||
Install strongSwan, then copy the included ipsec_user.conf, ipsec_user.secrets, user.crt (user certificate), and user.key (private key) files to your client device. These will require customization based on your exact use case. These files were originally generated with a point-to-point OpenWRT-based VPN in mind.
|
Please see [this page](docs/client-linux-ipsec.md).
|
||||||
|
|
||||||
#### Ubuntu Server example
|
|
||||||
|
|
||||||
1. `sudo apt-get install strongswan libstrongswan-standard-plugins`: install strongSwan
|
|
||||||
2. `/etc/ipsec.d/certs`: copy `<name>.crt` from `algo-master/configs/<server_ip>/ipsec/manual/<name>.crt`
|
|
||||||
3. `/etc/ipsec.d/private`: copy `<name>.key` from `algo-master/configs/<server_ip>/ipsec/manual/<name>.key`
|
|
||||||
4. `/etc/ipsec.d/cacerts`: copy `cacert.pem` from `algo-master/configs/<server_ip>/ipsec/manual/cacert.pem`
|
|
||||||
5. `/etc/ipsec.secrets`: add your `user.key` to the list, e.g. `<server_ip> : ECDSA <name>.key`
|
|
||||||
6. `/etc/ipsec.conf`: add the connection from `ipsec_user.conf` and ensure `leftcert` matches the `<name>.crt` filename
|
|
||||||
7. `sudo ipsec restart`: pick up config changes
|
|
||||||
8. `sudo ipsec up <conn-name>`: start the ipsec tunnel
|
|
||||||
9. `sudo ipsec down <conn-name>`: shutdown the ipsec tunnel
|
|
||||||
|
|
||||||
One common use case is to let your server access your local LAN without going through the VPN. Set up a passthrough connection by adding the following to `/etc/ipsec.conf`:
|
|
||||||
|
|
||||||
conn lan-passthrough
|
|
||||||
leftsubnet=192.168.1.1/24 # Replace with your LAN subnet
|
|
||||||
rightsubnet=192.168.1.1/24 # Replace with your LAN subnet
|
|
||||||
authby=never # No authentication necessary
|
|
||||||
type=pass # passthrough
|
|
||||||
auto=route # no need to ipsec up lan-passthrough
|
|
||||||
|
|
||||||
To configure the connection to come up at boot time replace `auto=add` with `auto=start`.
|
|
||||||
|
|
||||||
### Other Devices
|
### Other Devices
|
||||||
|
|
||||||
|
|
|
||||||
37
docs/client-linux-ipsec.md
Normal file
37
docs/client-linux-ipsec.md
Normal file
|
|
@ -0,0 +1,37 @@
|
||||||
|
# Linux strongSwan IPsec Clients (e.g., OpenWRT, Ubuntu Server, etc.)
|
||||||
|
|
||||||
|
Install strongSwan, then copy the included ipsec_user.conf, ipsec_user.secrets, user.crt (user certificate), and user.key (private key) files to your client device. These will require customization based on your exact use case. These files were originally generated with a point-to-point OpenWRT-based VPN in mind.
|
||||||
|
|
||||||
|
## Ubuntu Server example
|
||||||
|
|
||||||
|
1. `sudo apt-get install strongswan libstrongswan-standard-plugins`: install strongSwan
|
||||||
|
2. `/etc/ipsec.d/certs`: copy `<name>.crt` from `algo-master/configs/<server_ip>/ipsec/manual/<name>.crt`
|
||||||
|
3. `/etc/ipsec.d/private`: copy `<name>.key` from `algo-master/configs/<server_ip>/ipsec/manual/<name>.key`
|
||||||
|
4. `/etc/ipsec.d/cacerts`: copy `cacert.pem` from `algo-master/configs/<server_ip>/ipsec/manual/cacert.pem`
|
||||||
|
5. `/etc/ipsec.secrets`: add your `user.key` to the list, e.g. `<server_ip> : ECDSA <name>.key`
|
||||||
|
6. `/etc/ipsec.conf`: add the connection from `ipsec_user.conf` and ensure `leftcert` matches the `<name>.crt` filename
|
||||||
|
7. `sudo ipsec restart`: pick up config changes
|
||||||
|
8. `sudo ipsec up <conn-name>`: start the ipsec tunnel
|
||||||
|
9. `sudo ipsec down <conn-name>`: shutdown the ipsec tunnel
|
||||||
|
|
||||||
|
One common use case is to let your server access your local LAN without going through the VPN. Set up a passthrough connection by adding the following to `/etc/ipsec.conf`:
|
||||||
|
|
||||||
|
conn lan-passthrough
|
||||||
|
leftsubnet=192.168.1.1/24 # Replace with your LAN subnet
|
||||||
|
rightsubnet=192.168.1.1/24 # Replace with your LAN subnet
|
||||||
|
authby=never # No authentication necessary
|
||||||
|
type=pass # passthrough
|
||||||
|
auto=route # no need to ipsec up lan-passthrough
|
||||||
|
|
||||||
|
To configure the connection to come up at boot time replace `auto=add` with `auto=start`.
|
||||||
|
|
||||||
|
## Notes on SELinux
|
||||||
|
|
||||||
|
If you use a system with SELinux enabled you might need to set appropriate file contexts:
|
||||||
|
|
||||||
|
````
|
||||||
|
semanage fcontext -a -t ipsec_key_file_t "$(pwd)(/.*)?"
|
||||||
|
restorecon -R -v $(pwd)
|
||||||
|
````
|
||||||
|
|
||||||
|
See [this comment](https://github.com/trailofbits/algo/issues/263#issuecomment-328053950).
|
||||||
|
|
@ -1,102 +0,0 @@
|
||||||
# Deploy from Fedora Workstation
|
|
||||||
|
|
||||||
These docs were written based on experience on Fedora Workstation 30.
|
|
||||||
|
|
||||||
## Prerequisites
|
|
||||||
|
|
||||||
### DNF counterparts of apt packages
|
|
||||||
|
|
||||||
The following table lists `apt` packages with their `dnf` counterpart. This is purely informative.
|
|
||||||
|
|
||||||
| `apt` | `dnf` |
|
|
||||||
| ----- | ----- |
|
|
||||||
| `build-essential` | `make automake gcc gcc-c++ kernel-devel` |
|
|
||||||
| `libssl-dev` | `openssl-devel` |
|
|
||||||
| `libffi-dev` | `libffi-devel` |
|
|
||||||
| `python3-dev` | `python3-devel` |
|
|
||||||
| `python3-pip` | `python3-pip` |
|
|
||||||
| `python3-setuptools` | `python3-setuptools` |
|
|
||||||
| `python3-virtualenv` | `python3-virtualenv` |
|
|
||||||
|
|
||||||
### Install requirements
|
|
||||||
|
|
||||||
First, let's make sure our system is up-to-date:
|
|
||||||
|
|
||||||
````
|
|
||||||
dnf upgrade
|
|
||||||
````
|
|
||||||
|
|
||||||
Next, install the required packages:
|
|
||||||
|
|
||||||
````
|
|
||||||
dnf install -y \
|
|
||||||
automake \
|
|
||||||
gcc \
|
|
||||||
gcc-c++ \
|
|
||||||
kernel-devel \
|
|
||||||
openssl-devel \
|
|
||||||
libffi-devel \
|
|
||||||
python3-devel \
|
|
||||||
python3-pip \
|
|
||||||
python3-setuptools \
|
|
||||||
python3-virtualenv \
|
|
||||||
python3-crypto \
|
|
||||||
python3-pyyaml \
|
|
||||||
python3-pyOpenSSL \
|
|
||||||
python3-libselinux \
|
|
||||||
make
|
|
||||||
````
|
|
||||||
|
|
||||||
## Get Algo
|
|
||||||
|
|
||||||
|
|
||||||
[Download](https://github.com/trailofbits/algo/archive/master.zip) or clone:
|
|
||||||
|
|
||||||
````
|
|
||||||
git clone https://github.com/trailofbits/algo.git
|
|
||||||
cd algo
|
|
||||||
````
|
|
||||||
|
|
||||||
If you downloaded Algo, unzip to your prefered location and `cd` into it.
|
|
||||||
We'll assume from this point forward that our working directory is the `algo` root directory.
|
|
||||||
|
|
||||||
|
|
||||||
## Prepare algo
|
|
||||||
|
|
||||||
Some steps are needed before we can deploy our Algo VPN server.
|
|
||||||
|
|
||||||
### Setup virtualenv and install requirements
|
|
||||||
|
|
||||||
```
|
|
||||||
python3 -m virtualenv --python="$(command -v python3)" .env
|
|
||||||
source .env/bin/activate
|
|
||||||
python3 -m pip install -U pip virtualenv
|
|
||||||
python3 -m pip install -r requirements.txt
|
|
||||||
```
|
|
||||||
|
|
||||||
## Configure
|
|
||||||
|
|
||||||
Edit the userlist and any other settings you desire in `config.cfg` using your prefered editor.
|
|
||||||
|
|
||||||
## Deploy
|
|
||||||
|
|
||||||
We can now deploy our server by running:
|
|
||||||
|
|
||||||
````
|
|
||||||
./algo
|
|
||||||
````
|
|
||||||
|
|
||||||
Note the IP and password of the newly created Algo VPN server and store it safely.
|
|
||||||
|
|
||||||
If you want to setup client config on your Fedora Workstation, refer to [the Linux Client docs](client-linux.md).
|
|
||||||
|
|
||||||
## Notes on SELinux
|
|
||||||
|
|
||||||
If you have SELinux enabled, you'll need to set appropriate file contexts:
|
|
||||||
|
|
||||||
````
|
|
||||||
semanage fcontext -a -t ipsec_key_file_t "$(pwd)(/.*)?"
|
|
||||||
restorecon -R -v $(pwd)
|
|
||||||
````
|
|
||||||
|
|
||||||
See [this comment](https://github.com/trailofbits/algo/issues/263#issuecomment-328053950).
|
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
# Local Installation
|
# Local Installation
|
||||||
|
|
||||||
You can use Algo to configure a pre-existing server as an AlgoVPN rather than using it create and configure a new server on a supported cloud provider. This is referred to as a **local** installation rather than a **cloud** deployment.
|
You can use Algo to configure a pre-existing server as an AlgoVPN rather than using it to create and configure a new server on a supported cloud provider. This is referred to as a **local** installation rather than a **cloud** deployment.
|
||||||
|
|
||||||
Install the Algo scripts following the normal installation instructions, then choose:
|
Install the Algo scripts following the normal installation instructions, then choose:
|
||||||
```
|
```
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,6 @@
|
||||||
# Algo VPN documentation
|
# Algo VPN documentation
|
||||||
|
|
||||||
* Deployment instructions
|
* 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 [RedHat/CentOS 6.x](deploy-from-redhat-centos6.md)
|
||||||
- Deploy from [Windows](deploy-from-windows.md)
|
- Deploy from [Windows](deploy-from-windows.md)
|
||||||
- Deploy from a [Docker container](deploy-from-docker.md)
|
- Deploy from a [Docker container](deploy-from-docker.md)
|
||||||
|
|
@ -11,6 +10,7 @@
|
||||||
- Setup [Android](client-android.md) clients
|
- Setup [Android](client-android.md) clients
|
||||||
- Setup [Generic/Linux](client-linux.md) clients with Ansible
|
- Setup [Generic/Linux](client-linux.md) clients with Ansible
|
||||||
- Setup Ubuntu clients to use [WireGuard](client-linux-wireguard.md)
|
- Setup Ubuntu clients to use [WireGuard](client-linux-wireguard.md)
|
||||||
|
- Setup Linux clients to use [IPSEC](client-linux-ipsec.md)
|
||||||
- Setup Apple devices to use [IPSEC](client-apple-ipsec.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)
|
- Setup Macs running macOS 10.13 or older to use [Wireguard](client-macos-wireguard.md)
|
||||||
* Cloud provider setup
|
* Cloud provider setup
|
||||||
|
|
|
||||||
|
|
@ -22,7 +22,7 @@
|
||||||
Authorization: "Bearer {{ algo_do_token }}"
|
Authorization: "Bearer {{ algo_do_token }}"
|
||||||
register: _do_regions
|
register: _do_regions
|
||||||
|
|
||||||
- name: Set facts about thre regions
|
- name: Set facts about the regions
|
||||||
set_fact:
|
set_fact:
|
||||||
do_regions: "{{ _do_regions.json.regions | sort(attribute='slug') }}"
|
do_regions: "{{ _do_regions.json.regions | sort(attribute='slug') }}"
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -2,7 +2,7 @@
|
||||||
- include_tasks: ubuntu.yml
|
- include_tasks: ubuntu.yml
|
||||||
when: ansible_distribution == 'Debian' or ansible_distribution == 'Ubuntu'
|
when: ansible_distribution == 'Debian' or ansible_distribution == 'Ubuntu'
|
||||||
|
|
||||||
- name: Ensure that the strongswan user exist
|
- name: Ensure that the strongswan user exists
|
||||||
user:
|
user:
|
||||||
name: strongswan
|
name: strongswan
|
||||||
group: nogroup
|
group: nogroup
|
||||||
|
|
|
||||||
|
|
@ -38,7 +38,7 @@
|
||||||
- strongswan
|
- strongswan
|
||||||
- netfilter-persistent
|
- netfilter-persistent
|
||||||
|
|
||||||
- name: Ubuntu | Ensure that the strongswan service directory exist
|
- name: Ubuntu | Ensure that the strongswan service directory exists
|
||||||
file:
|
file:
|
||||||
path: /etc/systemd/system/strongswan.service.d/
|
path: /etc/systemd/system/strongswan.service.d/
|
||||||
state: directory
|
state: directory
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue