wallenstein/algo
1
0
Fork 0
mirror of https://github.com/trailofbits/algo.git synced 2025-09-03 10:33:13 +02:00
Code Issues Projects Releases Wiki Activity

Comprehensive documentation modernization and cleanup

Browse source 
- Remove all FreeBSD support (roles, documentation, references)
- Modernize troubleshooting guide by removing ~200 lines of obsolete content
- Rewrite OpenWrt router documentation with cleaner formatting
- Update Amazon EC2 documentation with current information
- Rewrite unsupported cloud provider documentation
- Remove obsolete linting documentation
- Update all version references to Ubuntu 22.04 LTS and Python 3.11+
- Add documentation style guidelines to CLAUDE.md
- Clean up compilation and legacy Python compatibility issues
- Update client documentation for current requirements

All documentation now reflects the uv-based modernization and current
supported platforms, eliminating references to obsolete tooling and
unsupported operating systems.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Dan Guido 2025-08-06 04:14:49 -07:00
parent 4c967c967d
commit 5ca15f24d2
22 changed files with 343 additions and 500 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
CLAUDE.md
View file

@ -93,13 +93,20 @@ select = ["E", "W", "F", "I", "B", "C4", "UP"]
#### Shell Scripts (shellcheck)
- Quote all variables: `"${var}"`
- Use `set -euo pipefail` for safety
- FreeBSD rc scripts will show false positives (ignore)
#### Ansible (ansible-lint)
- Many warnings are suppressed in `.ansible-lint`
- Focus on errors, not warnings
- Common suppressions: `name[missing]`, `risky-file-permissions`
#### Documentation Style
- Avoid excessive header nesting (prefer 2-3 levels maximum)
- Don't overuse bold formatting in lists - use sparingly for emphasis only
- Write flowing paragraphs instead of choppy bullet-heavy sections
- Keep formatting clean and readable - prefer natural text over visual noise
- Use numbered lists for procedures, simple bullets for feature lists
- Example: "Navigate to Network → Interfaces" not "**Navigate** to **Network** → **Interfaces**"
### Git Workflow
1. Create feature branches from `master`
2. Make atomic commits with clear messages
@ -132,10 +139,6 @@ shellcheck *.sh
- Too many tasks to fix immediately (113+)
- Focus on new code having proper names
### 2. FreeBSD rc Script Warnings
- Variables like `rcvar`, `start_cmd` appear unused to shellcheck
- These are used by the rc.subr framework
- Safe to ignore these specific warnings
### 3. Jinja2 Template Complexity
- Many templates use Ansible-specific filters
@ -177,7 +180,6 @@ shellcheck *.sh
### Operating Systems
- **Primary**: Ubuntu 20.04/22.04 LTS
- **Secondary**: Debian 11/12
- **Special**: FreeBSD (requires platform-specific code)
- **Clients**: Windows, macOS, iOS, Android, Linux
### Cloud Providers

1
README.md
View file

@ -196,7 +196,6 @@ After the process completes, new configuration files will be generated in the `c
* Deploy from [Ansible](docs/deploy-from-ansible.md) non-interactively
* Deploy onto a [cloud server at time of creation with shell script or cloud-init](docs/deploy-from-script-or-cloud-init-to-localhost.md)
* Deploy to an [unsupported cloud provider](docs/deploy-to-unsupported-cloud.md)
* Deploy to your own [FreeBSD](docs/deploy-to-freebsd.md) server
If you've read all the documentation and have further questions, [create a new discussion](https://github.com/trailofbits/algo/discussions).

4
docs/client-apple-ipsec.md
View file

@ -6,10 +6,10 @@ Find the corresponding `mobileconfig` (Apple Profile) for each user and send it
## Enable the VPN
On iOS, connect to the VPN by opening **Settings** and clicking the toggle next to "VPN" near the top of the list. If using WireGuard, you can also enable the VPN from the WireGuard app. On macOS, connect to the VPN by opening **System Preferences** -> **Network**, finding the Algo VPN in the left column, and clicking "Connect." Check "Show VPN status in menu bar" to easily connect and disconnect from the menu bar.
On iOS, connect to the VPN by opening **Settings** and clicking the toggle next to "VPN" near the top of the list. If using WireGuard, you can also enable the VPN from the WireGuard app. On macOS, connect to the VPN by opening **System Settings** -> **Network** (or **VPN** on macOS Sequoia 15.0+), finding the Algo VPN in the left column, and clicking "Connect." Check "Show VPN status in menu bar" to easily connect and disconnect from the menu bar.
## Managing "Connect On Demand"
If you enable "Connect On Demand", the VPN will connect automatically whenever it is able. Most Apple users will want to enable "Connect On Demand", but if you do then simply disabling the VPN will not cause it to stay disabled; it will just "Connect On Demand" again. To disable the VPN you'll need to disable "Connect On Demand".
On iOS, you can turn off "Connect On Demand" in **Settings** by clicking the (i) next to the entry for your Algo VPN and toggling off "Connect On Demand." On macOS, you can turn off "Connect On Demand" by opening **System Preferences** -> **Network**, finding the Algo VPN in the left column, unchecking the box for "Connect on demand", and clicking Apply.
On iOS, you can turn off "Connect On Demand" in **Settings** by clicking the (i) next to the entry for your Algo VPN and toggling off "Connect On Demand." On macOS, you can turn off "Connect On Demand" by opening **System Settings** -> **Network** (or **VPN** on macOS Sequoia 15.0+), finding the Algo VPN in the left column, unchecking the box for "Connect on demand", and clicking Apply.

2
docs/client-linux-ipsec.md
View file

@ -4,7 +4,7 @@ Install strongSwan, then copy the included ipsec_user.conf, ipsec_user.secrets,
## Ubuntu Server example
1. `sudo apt-get install strongswan libstrongswan-standard-plugins`: install strongSwan
1. `sudo apt install strongswan libstrongswan-standard-plugins`: install strongSwan
2. `/etc/ipsec.d/certs`: copy `<name>.crt` from `algo-master/configs/<server_ip>/ipsec/.pki/certs/<name>.crt`
3. `/etc/ipsec.d/private`: copy `<name>.key` from `algo-master/configs/<server_ip>/ipsec/.pki/private/<name>.key`
4. `/etc/ipsec.d/cacerts`: copy `cacert.pem` from `algo-master/configs/<server_ip>/ipsec/manual/cacert.pem`

2
docs/client-linux-wireguard.md
View file

@ -13,7 +13,7 @@ sudo apt update && sudo apt upgrade
# Install WireGuard:
sudo apt install wireguard
# Note: openresolv is no longer needed on Ubuntu 22.10+
# Note: openresolv is no longer needed on Ubuntu 22.04 LTS+
```
For installation on other Linux distributions, see the [Installation](https://www.wireguard.com/install/) page on the WireGuard site.

242
docs/client-openwrt-router-wireguard.md
View file

@ -1,88 +1,190 @@
# Using Router with OpenWRT as a Client with WireGuard
This scenario is useful in case you want to use vpn with devices which has no vpn capability like smart tv, or make vpn connection available via router for multiple devices.
This is a tested, working scenario with following environment:
# OpenWrt Router as WireGuard Client
- algo installed ubuntu at digitalocean
- client side router "TP-Link TL-WR1043ND" with openwrt ver. 21.02.1. [Openwrt Install instructions](https://openwrt.org/toh/tp-link/tl-wr1043nd)
- or client side router "TP-Link Archer C20i AC750" with openwrt ver. 21.02.1. [Openwrt install instructions](https://openwrt.org/toh/tp-link/archer_c20i)
see compatible device list at https://openwrt.org/toh/start . Theoretically, any of the devices on the list should work
This guide explains how to configure an OpenWrt router as a WireGuard VPN client, allowing all devices connected to your network to route traffic through your Algo VPN automatically. This setup is ideal for devices that don't support VPN natively (smart TVs, IoT devices, game consoles) or when you want seamless VPN access for all network clients.
## Use Cases
- Connect devices without native VPN support (smart TVs, gaming consoles, IoT devices)
- Automatically route all connected devices through the VPN
- Create a secure connection when traveling with multiple devices
- Configure VPN once at the router level instead of per-device
## Router setup
Make sure that you have
- router with openwrt installed,
- router is connected to internet,
- router and device in front of router do not have the same IP. By default, OpenWrt has 192.168.1.1 if so change it to something like 192.168.2.1
### Install required packages(WebUI)
- Open router web UI (mostly http://192.168.1.1)
- Login. (by default username: root, password:<empty>
- System -> Software, click "Update lists"
- Install following packages wireguard-tools, kmod-wireguard, luci-app-wireguard, wireguard, kmod-crypto-sha256, kmod-crypto-sha1, kmod-crypto-md5
- restart router
## Prerequisites
### Alternative Install required packages(ssh)
- Open router web UI (mostly http://192.168.1.1)
- ssh root@192.168.1.1
- opkg update
- opkg install wireguard-tools, kmod-wireguard, luci-app-wireguard, wireguard, kmod-crypto-sha256, kmod-crypto-sha1, kmod-crypto-md5
- reboot
You'll need an OpenWrt-compatible router with sufficient RAM (minimum 64MB recommended) and OpenWrt 23.05 or later installed. Your Algo VPN server must be deployed and running, and you'll need the WireGuard configuration file from your Algo deployment.
### Create an Interface(WebUI)
- Open router web UI
- Navigate Network -> Interface
- Click "Add new interface"
- Give a Name. e.g. `AlgoVpn`
- Select Protocol. `Wireguard VPN`
- click `Create Interface`
- In *General Settings* tab
- `Bring up on boot` *checked*
- Private key: `Interface -> Private Key` from algo config file
- Ip Address: `Interface -> Address` from algo config file
- In *Peers* tab
- Click add
- Name `algo`
- Public key: `[Peer]->PublicKey` from algo config file
- Preshared key: `[Peer]->PresharedKey` from algo config file
- Allowed IPs: 0.0.0.0/0
- Route Allowed IPs: checked
- Endpoint Host: `[Peer]->Endpoint` ip from algo config file
- Endpoint Port: `[Peer]->Endpoint` port from algo config file
- Persistent Keep Alive: `25`
- Click Save & Save Apply
Ensure your router's LAN subnet doesn't conflict with upstream networks. The default OpenWrt IP is `192.168.1.1` - change to `192.168.2.1` if conflicts exist.
### Configure Firewall(WebUI)
- Open router web UI
- Navigate to Network -> Firewall
- Click `Add configuration`:
- Name: e.g. ivpn_fw
- Input: Reject
- Output: Accept
- Forward: Reject
- Masquerading: Checked
- MSS clamping: Checked
- Covered networks: Select created VPN interface
- Allow forward to destination zones - Unspecified
- Allow forward from source zones - lan
- Click Save & Save Apply
- Reboot router
This configuration has been verified on TP-Link TL-WR1043ND and TP-Link Archer C20i AC750 with OpenWrt 23.05+. For compatibility with other devices, check the [OpenWrt Table of Hardware](https://openwrt.org/toh/start).
## Install Required Packages
There may be additional configuration required depending on environment like dns configuration.
### Web Interface Method
You can also verify the configuration using ssh. /etc/config/network. It should look like
1. Access your router's web interface (typically `http://192.168.1.1`)
2. Login with your credentials (default: username `root`, no password)
3. Navigate to System → Software
4. Click "Update lists" to refresh the package database
5. Search for and install these packages:
- `wireguard-tools`
- `kmod-wireguard`
- `luci-app-wireguard`
- `wireguard`
- `kmod-crypto-sha256`
- `kmod-crypto-sha1`
- `kmod-crypto-md5`
6. Restart the router after installation completes
### SSH Method
1. SSH into your router: `ssh root@192.168.1.1`
2. Update the package list:
```bash
opkg update
```
3. Install required packages:
```bash
opkg install wireguard-tools kmod-wireguard luci-app-wireguard wireguard kmod-crypto-sha256 kmod-crypto-sha1 kmod-crypto-md5
```
4. Reboot the router:
```bash
reboot
```
## Locate Your WireGuard Configuration
Before proceeding, locate your WireGuard configuration file from your Algo deployment. This file is typically located at:
```
configs/<server_ip>/wireguard/<username>.conf
```
config interface 'algo'
option proto 'wireguard'
list addresses '10.0.0.2/32'
option private_key '......' # The private key generated by itself just now
config wireguard_wg0
option public_key '......' # Server's public key
Your configuration file should look similar to:
```ini
[Interface]
PrivateKey = <your_private_key>
Address = 10.49.0.2/16
DNS = 172.16.0.1
[Peer]
PublicKey = <server_public_key>
PresharedKey = <preshared_key>
AllowedIPs = 0.0.0.0/0, ::/0
Endpoint = <server_ip>:51820
PersistentKeepalive = 25
```
## Configure WireGuard Interface
1. In the OpenWrt web interface, navigate to Network → Interfaces
2. Click "Add new interface..."
3. Set the name to `AlgoVPN` (or your preferred name) and select "WireGuard VPN" as the protocol
4. Click "Create interface"
In the General Settings tab:
- Check "Bring up on boot"
- Enter your private key from the Algo config file
- Add your IP address from the Algo config file (e.g., `10.49.0.2/16`)
Switch to the Peers tab and click "Add peer":
- Description: `Algo Server`
- Public Key: Copy from the `[Peer]` section of your config
- Preshared Key: Copy from the `[Peer]` section of your config
- Allowed IPs: `0.0.0.0/0, ::/0` (routes all traffic through VPN)
- Route Allowed IPs: Check this box
- Endpoint Host: Extract the IP address from the `Endpoint` line
- Endpoint Port: Extract the port from the `Endpoint` line (typically `51820`)
- Persistent Keep Alive: `25`
Click "Save & Apply".
## Configure Firewall Rules
1. Navigate to Network → Firewall
2. Click "Add" to create a new zone
3. Configure the firewall zone:
- Name: `vpn`
- Input: `Reject`
- Output: `Accept`
- Forward: `Reject`
- Masquerading: Check this box
- MSS clamping: Check this box
- Covered networks: Select your WireGuard interface (`AlgoVPN`)
4. In the Inter-Zone Forwarding section:
- Allow forward from source zones: Select `lan`
- Allow forward to destination zones: Leave unspecified
5. Click "Save & Apply"
6. Reboot your router to ensure all changes take effect
## Verification and Testing
Navigate to Network → Interfaces and verify your WireGuard interface shows as "Connected" with a green status. Check that it has received the correct IP address.
From a device connected to your router, visit https://whatismyipaddress.com/. Your public IP should match your Algo VPN server's IP address. Test DNS resolution to ensure it's working through the VPN.
For command line verification, SSH into your router and check:
```bash
# Check interface status
wg show
# Check routing table
ip route
# Test connectivity
ping 8.8.8.8
```
## Configuration File Reference
Your OpenWrt network configuration (`/etc/config/network`) should include sections similar to:
```uci
config interface 'AlgoVPN'
option proto 'wireguard'
list addresses '10.49.0.2/16'
option private_key '<your_private_key>'
config wireguard_AlgoVPN
option public_key '<server_public_key>'
option preshared_key '<preshared_key>'
option route_allowed_ips '1'
list allowed_ips '0.0.0.0/0'
option endpoint_host '......' # Server's public ip address
list allowed_ips '::/0'
option endpoint_host '<server_ip>'
option endpoint_port '51820'
option persistent_keepalive '25'
```
## Troubleshooting
If the interface won't connect, verify all keys are correctly copied with no extra spaces or line breaks. Check that your Algo server is running and accessible, and confirm the endpoint IP and port are correct.
If you have no internet access after connecting, verify firewall rules allow forwarding from LAN to VPN zone. Check that masquerading is enabled on the VPN zone and ensure MSS clamping is enabled.
If some websites don't work, try disabling MSS clamping temporarily to test. Verify DNS is working by testing `nslookup google.com` and check that IPv6 is properly configured if used.
For DNS resolution issues, configure custom DNS servers in Network → DHCP and DNS. Consider using your Algo server's DNS (typically `172.16.0.1`).
Check system logs for WireGuard-related errors:
```bash
# View system logs
logread | grep -i wireguard
# Check kernel messages
dmesg | grep -i wireguard
```
## Advanced Configuration
For split tunneling (routing only specific traffic through the VPN), change "Allowed IPs" in the peer configuration to specific subnets and add custom routing rules for desired traffic.
If your Algo server supports IPv6, add the IPv6 address to your interface configuration and include `::/0` in "Allowed IPs" for the peer.
For optimal privacy, configure your router to use your Algo server's DNS by navigating to Network → DHCP and DNS and adding your Algo DNS server IP (typically `172.16.0.1`) to the DNS forwardings.
## Security Notes
Store your private keys securely and never share them. Keep OpenWrt and packages updated for security patches. Regularly check VPN connectivity to ensure ongoing protection, and save your configuration before making changes.
This configuration routes ALL traffic from your router through the VPN. If you need selective routing or have specific requirements, consider consulting the [OpenWrt WireGuard documentation](https://openwrt.org/docs/guide-user/services/vpn/wireguard/start) for advanced configurations.

116
docs/cloud-amazon-ec2.md
View file

@ -1,64 +1,81 @@
# Amazon EC2 cloud setup
# Amazon EC2 Cloud Setup
## AWS account creation
This guide walks you through setting up Algo VPN on Amazon EC2, including account creation, permissions configuration, and deployment process.
Creating an Amazon AWS account requires giving Amazon a phone number that can receive a call and has a number pad to enter a PIN challenge displayed in the browser. This phone system prompt occasionally fails to correctly validate input, but try again (request a new PIN in the browser) until you succeed.
## AWS Account Creation
### Select an EC2 plan
Creating an Amazon AWS account requires providing a phone number that can receive automated calls with PIN verification. The phone verification system occasionally fails, but you can request a new PIN and try again until it succeeds.
The cheapest EC2 plan you can choose is the "Free Plan" a.k.a. the ["AWS Free Tier"](https://aws.amazon.com/free/). It is only available to new AWS customers, it has limits on usage, and it converts to standard pricing after 12 months (the "introductory period"). After you exceed the usage limits, after the 12 month period, or if you are an existing AWS customer, then you will pay standard pay-as-you-go service prices.
## Choose Your EC2 Plan
*Note*: Your Algo instance will not stop working when you hit the bandwidth limit, you will just start accumulating service charges on your AWS account.
### AWS Free Tier
As of the time of this writing (June 2024), the Free Tier limits include "750 hours of Amazon EC2 Linux t2.micro (some regions like the Middle East (Bahrain) region and the EU (Stockholm) region [do not offer t2.micro instances](https://aws.amazon.com/free/free-tier-faqs/)) or t3.micro instance usage" per month, [100 GB of bandwidth (outbound) per month](https://repost.aws/questions/QUAT1NfOeZSAK5z8KXXO9jgA/do-amazon-aws-ec2-free-tier-have-a-bandwidth-limit#ANNZSAFFk3T0Kv7ZHnZwf9Mw) from [November 2021](https://aws.amazon.com/blogs/aws/aws-free-tier-data-transfer-expansion-100-gb-from-regions-and-1-tb-from-amazon-cloudfront-per-month/), and 30 GB of cloud storage. Algo will not even use 1% of the storage limit, but you may have to monitor your bandwidth usage or keep an eye out for the email from Amazon when you are about to exceed the Free Tier limits.
The most cost-effective option for new AWS customers is the [AWS Free Tier](https://aws.amazon.com/free/), which provides:
If you are not eligible for the free tier plan or have passed the 12 months of the introductory period, you can switch to [AWS Graviton](https://aws.amazon.com/ec2/graviton/) instances that are generally cheaper. To use the graviton instances, make the following changes in the ec2 section of your `config.cfg` file:
* Set the `size` to `t4g.nano`
* Set the `arch` to `arm64`
- 750 hours of Amazon EC2 Linux t2.micro or t3.micro instance usage per month
- 100 GB of outbound data transfer per month
- 30 GB of cloud storage
> Currently, among all the instance sizes available on AWS, the t4g.nano instance is the least expensive option that does not require any promotional offers. However, AWS is currently running a promotion that provides a free trial of the `t4g.small` instance until December 31, 2023, which is available to all customers. For more information about this promotion, please refer to the [documentation](https://aws.amazon.com/ec2/faqs/#t4g-instances).
The Free Tier is available for 12 months from account creation. Some regions like Middle East (Bahrain) and EU (Stockholm) don't offer t2.micro instances, but t3.micro is available as an alternative.
Additional configurations are documented in the [EC2 section of the deploy from ansible guide](https://github.com/trailofbits/algo/blob/master/docs/deploy-from-ansible.md#amazon-ec2)
Note that your Algo instance will continue working if you exceed bandwidth limits - you'll just start accruing standard charges on your AWS account.
### Create an AWS permissions policy
### Cost-Effective Alternatives
In the AWS console, find the policies menu: click Services > IAM > Policies. Click Create Policy.
If you're not eligible for the Free Tier or prefer more predictable costs, consider AWS Graviton instances. To use Graviton instances, modify your `config.cfg` file:
Here, you have the policy editor. Switch to the JSON tab and copy-paste over the existing empty policy with [the minimum required AWS policy needed for Algo deployment](https://github.com/trailofbits/algo/blob/master/docs/deploy-from-ansible.md#minimum-required-iam-permissions-for-deployment).
```yaml
ec2:
size: t4g.nano
arch: arm64
```
When prompted to name the policy, name it `AlgoVPN_Provisioning`.
The t4g.nano instance is currently the least expensive option without promotional requirements. AWS is also running a promotion offering free t4g.small instances until December 31, 2025 - see the [AWS documentation](https://aws.amazon.com/ec2/faqs/#t4g-instances) for details.
For additional EC2 configuration options, see the [deploy from ansible guide](https://github.com/trailofbits/algo/blob/master/docs/deploy-from-ansible.md#amazon-ec2).
## Set Up IAM Permissions
### Create IAM Policy
1. In the AWS console, navigate to Services → IAM → Policies
2. Click "Create Policy"
3. Switch to the JSON tab
4. Replace the default content with the [minimum required AWS policy for Algo deployment](https://github.com/trailofbits/algo/blob/master/docs/deploy-from-ansible.md#minimum-required-iam-permissions-for-deployment)
5. Name the policy `AlgoVPN_Provisioning`
![Creating a new permissions policy in the AWS console.](/docs/images/aws-ec2-new-policy.png)
### Set up an AWS user
### Create IAM User
In the AWS console, find the users (“Identity and Access Management”, a.k.a. IAM users) menu: click Services > IAM.
Activate multi-factor authentication (MFA) on your root account. The simplest choice is the mobile app "Google Authenticator." A hardware U2F token is ideal (less prone to a phishing attack), but a TOTP authenticator like this is good enough.
1. Navigate to Services → IAM → Users
2. Enable multi-factor authentication (MFA) on your root account using Google Authenticator or a hardware token
3. Click "Add User" and create a username (e.g., `algovpn`)
4. Select "Programmatic access"
5. Click "Next: Permissions"
![The new user screen in the AWS console.](/docs/images/aws-ec2-new-user.png)
Now "Create individual IAM users" and click Add User. Create a user name. I chose “algovpn”. Then click the box next to Programmatic Access. Then click Next.
![The IAM user naming screen in the AWS console.](/docs/images/aws-ec2-new-user-name.png)
Next, click “Attach existing policies directly.” Type “Algo” in the search box to filter the policies. Find “AlgoVPN_Provisioning” (the policy you created) and click the checkbox next to that. Click Next when you’re done.
6. Choose "Attach existing policies directly"
7. Search for "Algo" and select the `AlgoVPN_Provisioning` policy you created
8. Click "Next: Tags" (optional), then "Next: Review"
![Attaching a policy to an IAM user in the AWS console.](/docs/images/aws-ec2-attach-policy.png)
The user creation confirmation screen should look like this if you've done everything correctly.
![New user creation confirmation screen in the AWS console.](/docs/images/aws-ec2-new-user-confirm.png)
On the final screen, click the Download CSV button. This file includes the AWS access keys you’ll need during the Algo set-up process. Click Close, and you’re all set.
9. Review your settings and click "Create user"
10. Download the CSV file containing your access credentials - you'll need these for Algo deployment
![Downloading the credentials for an AWS IAM user.](/docs/images/aws-ec2-new-user-csv.png)
## Using EC2 during Algo setup
Keep the CSV file secure as it contains sensitive credentials that grant access to your AWS account.
After you have downloaded Algo and installed its dependencies, the next step is running Algo to provision the VPN server on your AWS account.
## Deploy with Algo
First, you will be asked which server type to setup. You would want to enter "3" to use Amazon EC2.
Once you've installed Algo and its dependencies, you can deploy your VPN server to EC2.
### Provider Selection
Run `./algo` and select Amazon EC2 when prompted:
```
$ ./algo
@ -81,14 +98,15 @@ Enter the number of your desired provider
: 3
```
Next, Algo will need your AWS credentials. If you have already configured AWS CLI with `aws configure`, Algo will automatically use those credentials. Otherwise, you will be asked for the AWS Access Key (Access Key ID) and AWS Secret Key (Secret Access Key) that you received in the CSV file when you setup the account (don't worry if you don't see your text entered in the console; the key input is hidden here by Algo).
### AWS Credentials
Algo will automatically detect AWS credentials in this order:
**Automatic credential detection**: Algo will check for credentials in this order:
1. Command-line variables
2. Environment variables (`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`)
3. AWS credentials file (`~/.aws/credentials`)
If none are found, you'll see these prompts:
If no credentials are found, you'll be prompted to enter them manually:
```
Enter your aws_access_key (http://docs.aws.amazon.com/general/latest/gr/managing-aws-access-keys.html)
@ -101,16 +119,18 @@ Enter your aws_secret_key (http://docs.aws.amazon.com/general/latest/gr/managing
[ABCD...]:
```
For more details on credential configuration, see the [AWS Credentials guide](aws-credentials.md).
For detailed credential configuration options, see the [AWS Credentials guide](aws-credentials.md).
You will be prompted for the server name to enter. Feel free to leave this as the default ("algo") if you are not certain how this will affect your setup. Here we chose to call it "algovpn".
### Server Configuration
You'll be prompted to name your server (default is "algo"):
```
Name the vpn server:
[algo]: algovpn
```
After entering the server name, the script ask which region you wish to setup your new Algo instance in. Enter the number next to name of the region.
Next, select your preferred AWS region:
```
What region should the server be located in?
@ -137,8 +157,20 @@ Enter the number of your desired region
:
```
You will then be asked the remainder of the standard Algo setup questions.
Choose a region close to your location for optimal performance, keeping in mind that some regions may have different pricing or instance availability.
## Cleanup
After region selection, Algo will continue with the standard setup questions for user configuration and VPN options.
If you've installed Algo onto EC2 multiple times, your AWS account may become cluttered with unused or deleted resources e.g. instances, VPCs, subnets, etc. This may cause future installs to fail. The easiest way to clean up after you're done with a server is to go to "CloudFormation" from the console and delete the CloudFormation stack associated with that server. Please note that unless you've enabled termination protection on your instance, deleting the stack this way will delete your instance without warning, so be sure you are deleting the correct stack.
## Resource Cleanup
If you deploy Algo to EC2 multiple times, unused resources (instances, VPCs, subnets) may accumulate and potentially cause future deployment issues.
The cleanest way to remove an Algo deployment is through CloudFormation:
1. Go to the AWS console and navigate to CloudFormation
2. Find the stack associated with your Algo server
3. Delete the entire stack
Warning: Deleting a CloudFormation stack will permanently delete your EC2 instance and all associated resources unless you've enabled termination protection. Make sure you're deleting the correct stack and have backed up any important data.
This approach ensures all related AWS resources are properly cleaned up, preventing resource conflicts in future deployments.

32
docs/deploy-to-freebsd.md
View file

@ -1,32 +0,0 @@
# FreeBSD / HardenedBSD server setup
FreeBSD server support is a work in progress. For now, it is only possible to install Algo on existing FreeBSD 11 systems.
## System preparation
Ensure that the following kernel options are enabled:
```
# sysctl kern.conftxt | grep -iE "IPSEC|crypto"
options IPSEC
options IPSEC_NAT_T
device crypto
```
## Available roles
* vpn
* ssh_tunneling
* dns_adblocking
## Additional variables
* rebuild_kernel - set to `true` if you want to let Algo to rebuild your kernel if needed (takes a lot of time)
## Installation
```shell
ansible-playbook main.yml -e "provider=local"
```
And follow the instructions

83
docs/deploy-to-unsupported-cloud.md
View file

@ -1,20 +1,81 @@
# Unsupported Cloud Providers
# Deploying to Unsupported Cloud Providers
Algo officially supports the [cloud providers listed here](https://github.com/trailofbits/algo/blob/master/README.md#deploy-the-algo-server). If you want to deploy Algo on another virtual hosting provider, that provider must support:
Algo officially supports the [cloud providers listed in the README](https://github.com/trailofbits/algo/blob/master/README.md#deploy-the-algo-server). If you want to deploy Algo on another cloud provider, that provider must meet specific technical requirements for compatibility.
1. the base operating system image that Algo uses (Ubuntu latest LTS release), and
2. a minimum of certain kernel modules required for the strongSwan IPsec server.
## Technical Requirements
Please see the [Required Kernel Modules](https://wiki.strongswan.org/projects/strongswan/wiki/KernelModules) documentation from strongSwan for a list of the specific required modules and a script to check for them. As a first step, we recommend running their shell script to determine initial compatibility with your new hosting provider.
Your cloud provider must support:
If you want Algo to officially support your new cloud provider then it must have an Ansible [cloud module](https://docs.ansible.com/ansible/list_of_cloud_modules.html) available. If no module is available for your provider, search Ansible's [open issues](https://github.com/ansible/ansible/issues) and [pull requests](https://github.com/ansible/ansible/pulls) for existing efforts to add it. If none are available, then you may want to develop the module yourself. Reference the [Ansible module developer documentation](https://docs.ansible.com/ansible/dev_guide/developing_modules.html) and the API documentation for your hosting provider.
1. **Ubuntu 22.04 LTS** - Algo exclusively supports Ubuntu 22.04 LTS as the base operating system
2. **Required kernel modules** - Specific modules needed for strongSwan IPsec and WireGuard VPN functionality
3. **Network capabilities** - Full networking stack access, not containerized environments
## IPsec in userland
## Compatibility Testing
Hosting providers that rely on OpenVZ or Docker cannot be used by Algo since they cannot load the required kernel modules or access the required network interfaces. For more information, see the strongSwan documentation on [Cloud Platforms](https://wiki.strongswan.org/projects/strongswan/wiki/Cloudplatforms).
Before attempting to deploy Algo on an unsupported provider, test compatibility using strongSwan's kernel module checker:
In order to address this issue, strongSwan has developed the [kernel-libipsec](https://wiki.strongswan.org/projects/strongswan/wiki/Kernel-libipsec) plugin which provides an IPsec backend that works entirely in userland. `libipsec` bundles its own IPsec implementation and uses TUN devices to route packets. For example, `libipsec` is used by the Android strongSwan app to address Android's lack of a functional IPsec stack.
1. Deploy a basic Ubuntu 22.04 LTS instance on your target provider
2. Run the [kernel module compatibility script](https://wiki.strongswan.org/projects/strongswan/wiki/KernelModules) from strongSwan
3. Verify all required modules are available and loadable
Use of `libipsec` is not supported by Algo. It has known performance issues since it buffers each packet in memory. On certain systems with insufficient processor power, such as many cloud hosting providers, using `libipsec` can lead to an out of memory condition, crash the charon daemon, or lock up the entire host.
The script will identify any missing kernel modules that would prevent Algo from functioning properly.
Further, `libipsec` introduces unknown security risks. The code in `libipsec` has not been scrutinized to the same level as the code in the Linux or FreeBSD kernel that it replaces. This additional code introduces new complexity to the Algo server that we want to avoid at this time. We recommend moving to a hosting provider that does not require libipsec and can load the required kernel modules.
## Adding Official Support
For Algo to officially support a new cloud provider, the provider must have:
- An available Ansible [cloud module](https://docs.ansible.com/ansible/list_of_cloud_modules.html)
- Reliable API for programmatic instance management
- Consistent Ubuntu 22.04 LTS image availability
If no Ansible module exists for your provider:
1. Check Ansible's [open issues](https://github.com/ansible/ansible/issues) and [pull requests](https://github.com/ansible/ansible/pulls) for existing development efforts
2. Consider developing the module yourself using the [Ansible module developer documentation](https://docs.ansible.com/ansible/dev_guide/developing_modules.html)
3. Reference your provider's API documentation for implementation details
## Unsupported Environments
### Container-Based Hosting
Providers using **OpenVZ**, **Docker containers**, or other **containerized environments** cannot run Algo because:
- Container environments don't provide access to kernel modules
- VPN functionality requires low-level network interface access
- IPsec and WireGuard need direct kernel interaction
For more details, see strongSwan's [Cloud Platforms documentation](https://wiki.strongswan.org/projects/strongswan/wiki/Cloudplatforms).
### Userland IPsec (libipsec)
Some providers attempt to work around kernel limitations using strongSwan's [kernel-libipsec](https://wiki.strongswan.org/projects/strongswan/wiki/Kernel-libipsec) plugin, which implements IPsec entirely in userspace.
**Algo does not support libipsec** for these reasons:
- **Performance issues** - Buffers each packet in memory, causing performance degradation
- **Resource consumption** - Can cause out-of-memory conditions on resource-constrained systems
- **Stability concerns** - May crash the charon daemon or lock up the host system
- **Security implications** - Less thoroughly audited than kernel implementations
- **Added complexity** - Introduces additional code paths that increase attack surface
We strongly recommend choosing a provider that supports native kernel modules rather than attempting workarounds.
## Alternative Deployment Options
If your preferred provider doesn't support Algo's requirements:
1. **Use a supported provider** - Deploy on AWS, DigitalOcean, Azure, GCP, or another [officially supported provider](https://github.com/trailofbits/algo/blob/master/README.md#deploy-the-algo-server)
2. **Deploy locally** - Use the [Ubuntu server deployment option](deploy-to-ubuntu.md) on your own hardware
3. **Hybrid approach** - Deploy the VPN server on a supported provider while using your preferred provider for other services
## Contributing Support
If you successfully deploy Algo on an unsupported provider and want to contribute official support:
1. Ensure the provider meets all technical requirements
2. Verify consistent deployment success across multiple regions
3. Create an Ansible module or verify existing module compatibility
4. Document the deployment process and any provider-specific considerations
5. Submit a pull request with your implementation
Community contributions to expand provider support are welcome, provided they meet Algo's security and reliability standards.

6
docs/faq.md
View file

@ -6,7 +6,7 @@
* [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)
* [Why aren't you using Alpine Linux or OpenBSD?](#why-arent-you-using-alpine-linux-or-openbsd)
* [I deployed an Algo server. Can you update it with new features?](#i-deployed-an-algo-server-can-you-update-it-with-new-features)
* [Where did the name "Algo" come from?](#where-did-the-name-algo-come-from)
* [Can DNS filtering be disabled?](#can-dns-filtering-be-disabled)
@ -39,9 +39,9 @@ I would, but I don't know of any [suitable ones](https://github.com/trailofbits/
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](https://arstechnica.com/security/2016/08/new-attack-can-pluck-secrets-from-1-of-https-traffic-affects-top-sites/) and its [implementations](https://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/).
## Why aren't you using Alpine Linux, OpenBSD, or HardenedBSD?
## Why aren't you using Alpine Linux or OpenBSD?
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).
Alpine Linux is not supported out-of-the-box by any major cloud provider. While we considered BSD variants in the past, Algo now focuses exclusively on Ubuntu LTS for consistency, security, and maintainability.
## I deployed an Algo server. Can you update it with new features?

1
docs/index.md
View file

@ -24,7 +24,6 @@
- Configure [CloudStack](cloud-cloudstack.md)
- Configure [Hetzner Cloud](cloud-hetzner.md)
* Advanced Deployment
- Deploy to your own [FreeBSD](deploy-to-freebsd.md) server
- Deploy to your own [Ubuntu](deploy-to-ubuntu.md) server, and road warrior setup
- Deploy to an [unsupported cloud provider](deploy-to-unsupported-cloud.md)
* [FAQ](faq.md)

88
docs/linting.md
View file

@ -1,88 +0,0 @@
# Linting and Code Quality
This document describes the linting and code quality checks used in the Algo VPN project.
## Overview
The project uses multiple linters to ensure code quality across different file types:
- **Ansible** playbooks and roles
- **Python** library modules and tests
- **Shell** scripts
- **YAML** configuration files
## Linters in Use
### 1. Ansible Linting
- **Tool**: `ansible-lint`
- **Config**: `.ansible-lint`
- **Checks**: Best practices, security issues, deprecated syntax
- **Key Rules**:
- `no-log-password`: Ensure passwords aren't logged
- `no-same-owner`: File ownership should be explicit
- `partial-become`: Avoid unnecessary privilege escalation
### 2. Python Linting
- **Tool**: `ruff` - Fast Python linter (replaces flake8, isort, etc.)
- **Config**: `pyproject.toml`
- **Style**: 120 character line length, Python 3.10+
- **Checks**: Syntax errors, imports, code style
### 3. Shell Script Linting
- **Tool**: `shellcheck`
- **Checks**: All `.sh` files in the repository
- **Catches**: Common shell scripting errors and pitfalls
### 4. YAML Linting
- **Tool**: `yamllint`
- **Config**: `.yamllint`
- **Rules**: Extended from default with custom line length
### 5. GitHub Actions Security
- **Tool**: `zizmor` - GitHub Actions security (run separately)
## CI/CD Integration
### Main Workflow (`main.yml`)
- **syntax-check**: Validates Ansible playbook syntax
- **basic-tests**: Runs unit tests including validation tests
### Lint Workflow (`lint.yml`)
Separate workflow with parallel jobs:
- **ansible-lint**: Ansible best practices
- **yaml-lint**: YAML formatting
- **python-lint**: Python code quality
- **shellcheck**: Shell script validation
## Running Linters Locally
```bash
# Ansible
ansible-lint -v *.yml roles/{local,cloud-*}/*/*.yml
# Python
ruff check .
# Shell
find . -name "*.sh" -exec shellcheck {} \;
# YAML
yamllint .
```
## Current Status
Most linters are configured to warn rather than fail (`|| true`) to allow gradual adoption. As code quality improves, these should be changed to hard failures.
### Known Issues to Address:
1. Python library modules need formatting updates
2. Some Ansible tasks missing `changed_when` conditions
3. YAML files have inconsistent indentation
4. Shell scripts could use more error handling
## Contributing
When adding new code:
1. Run relevant linters before committing
2. Fix any errors (not just warnings)
3. Add linting exceptions only with good justification
4. Update linter configs if adding new file types

114
docs/troubleshooting.md
View file

@ -1,14 +1,10 @@
# Troubleshooting
First of all, check [this](https://github.com/trailofbits/algo#features) and ensure that you are deploying to the supported ubuntu version.
First of all, check [this](https://github.com/trailofbits/algo#features) and ensure that you are deploying to Ubuntu 22.04 LTS, the only supported server platform.
* [Installation Problems](#installation-problems)
* [Error: "You have not agreed to the Xcode license agreements"](#error-you-have-not-agreed-to-the-xcode-license-agreements)
* [Error: checking whether the C compiler works... no](#error-checking-whether-the-c-compiler-works-no)
* [Error: "fatal error: 'openssl/opensslv.h' file not found"](#error-fatal-error-opensslopensslvh-file-not-found)
* [Error: "TypeError: must be str, not bytes"](#error-typeerror-must-be-str-not-bytes)
* [Python version is not supported](#python-version-is-not-supported)
* [Error: "ansible-playbook: command not found"](#error-ansible-playbook-command-not-found)
* [Error: "Could not fetch URL ... TLSV1_ALERT_PROTOCOL_VERSION](#could-not-fetch-url--tlsv1_alert_protocol_version)
* [Fatal: "Failed to validate the SSL certificate for ..."](#fatal-failed-to-validate-the-SSL-certificate)
* [Bad owner or permissions on .ssh](#bad-owner-or-permissions-on-ssh)
* [The region you want is not available](#the-region-you-want-is-not-available)
@ -31,7 +27,6 @@ First of all, check [this](https://github.com/trailofbits/algo#features) and ens
* [Error: "The VPN Service payload could not be installed."](#error-the-vpn-service-payload-could-not-be-installed)
* [Little Snitch is broken when connected to the VPN](#little-snitch-is-broken-when-connected-to-the-vpn)
* [I can't get my router to connect to the Algo server](#i-cant-get-my-router-to-connect-to-the-algo-server)
* [I can't get Network Manager to connect to the Algo server](#i-cant-get-network-manager-to-connect-to-the-algo-server)
* [Various websites appear to be offline through the VPN](#various-websites-appear-to-be-offline-through-the-vpn)
* [Clients appear stuck in a reconnection loop](#clients-appear-stuck-in-a-reconnection-loop)
* [Wireguard: clients can connect on Wifi but not LTE](#wireguard-clients-can-connect-on-wifi-but-not-lte)
@ -44,84 +39,13 @@ Look here if you have a problem running the installer to set up a new Algo serve
### Python version is not supported
The minimum Python version required to run Algo is 3.8. Most modern operation systems should have it by default, but if the OS you are using doesn't meet the requirements, you have to upgrade. See the official documentation for your OS, or manual download it from https://www.python.org/downloads/. Otherwise, you may [deploy from docker](deploy-from-docker.md)
### Error: "You have not agreed to the Xcode license agreements"
On macOS, you tried to install the dependencies with pip and encountered the following error:
```
Downloading cffi-1.9.1.tar.gz (407kB): 407kB downloaded
Running setup.py (path:/private/tmp/pip_build_root/cffi/setup.py) egg_info for package cffi
You have not agreed to the Xcode license agreements, please run 'xcodebuild -license' (for user-level acceptance) or 'sudo xcodebuild -license' (for system-wide acceptance) from within a Terminal window to review and agree to the Xcode license agreements.
No working compiler found, or bogus compiler options
passed to the compiler from Python's distutils module.
See the error messages above.
----------------------------------------
Cleaning up...
Command python setup.py egg_info failed with error code 1 in /private/tmp/pip_build_root/cffi
Storing debug log for failure in /Users/algore/Library/Logs/pip.log
```
The Xcode compiler is installed but requires you to accept its license agreement prior to using it. Run `xcodebuild -license` to agree and then retry installing the dependencies.
### Error: checking whether the C compiler works... no
On macOS, you tried to install the dependencies with pip and encountered the following error:
```
Failed building wheel for pycrypto
Running setup.py clean for pycrypto
Failed to build pycrypto
...
copying lib/Crypto/Signature/PKCS1_v1_5.py -> build/lib.macosx-10.6-intel-2.7/Crypto/Signature
running build_ext
running build_configure
checking for gcc... gcc
checking whether the C compiler works... no
configure: error: in '/private/var/folders/3f/q33hl6_x6_nfyjg29fcl9qdr0000gp/T/pip-build-DB5VZp/pycrypto': configure: error: C compiler cannot create executables See config.log for more details
Traceback (most recent call last):
File "", line 1, in
...
cmd_obj.run()
File "/private/var/folders/3f/q33hl6_x6_nfyjg29fcl9qdr0000gp/T/pip-build-DB5VZp/pycrypto/setup.py", line 278, in run
raise RuntimeError("autoconf error")
RuntimeError: autoconf error
```
You don't have a working compiler installed. You should install the XCode compiler by opening your terminal and running `xcode-select --install`.
### Error: "fatal error: 'openssl/opensslv.h' file not found"
On macOS, you tried to install `cryptography` and encountered the following error:
```
build/temp.macosx-10.12-intel-2.7/_openssl.c:434:10: fatal error: 'openssl/opensslv.h' file not found
#include <openssl/opensslv.h>
^
1 error generated.
error: command 'cc' failed with exit status 1
----------------------------------------
Cleaning up...
Command /usr/bin/python -c "import setuptools, tokenize;__file__='/private/tmp/pip_build_root/cryptography/setup.py';exec(compile(getattr(tokenize, 'open', open)(__file__).read().replace('\r\n', '\n'), __file__, 'exec'))" install --record /tmp/pip-sREEE5-record/install-record.txt --single-version-externally-managed --compile failed with error code 1 in /private/tmp/pip_build_root/cryptography
Storing debug log for failure in /Users/algore/Library/Logs/pip.log
```
You are running an old version of `pip` that cannot download the binary `cryptography` dependency. Upgrade to a new version of `pip` by running `sudo python3 -m pip install -U pip`.
The minimum Python version required to run Algo is 3.11. Most modern operation systems should have it by default, but if the OS you are using doesn't meet the requirements, you have to upgrade. See the official documentation for your OS, or manual download it from https://www.python.org/downloads/. Otherwise, you may [deploy from docker](deploy-from-docker.md)
### Error: "ansible-playbook: command not found"
You tried to install Algo and you see an error that reads "ansible-playbook: command not found."
You did not finish the installation instructions, "[Install Algo's remaining dependencies](https://github.com/trailofbits/algo#deploy-the-algo-server)." Algo depends on [Ansible](https://github.com/ansible/ansible), an automation framework, and this error indicates that you do not have Ansible installed. Dependencies are managed by uv and installed automatically when you run `./algo`. You must complete the installation instructions to run the Algo server deployment process.
This indicates that Ansible is not installed or not available in your PATH. Algo automatically installs all dependencies (including Ansible) using uv when you run `./algo` for the first time. If you're seeing this error, try running `./algo` again - it should automatically install the required Python environment and dependencies. If the issue persists, ensure you're running `./algo` from the Algo project directory.
### Fatal: "Failed to validate the SSL certificate"
@ -130,23 +54,7 @@ You received a message like this:
fatal: [localhost]: FAILED! => {"changed": false, "msg": "Failed to validate the SSL certificate for api.digitalocean.com:443. Make sure your managed systems have a valid CA certificate installed. You can use validate_certs=False if you do not need to confirm the servers identity but this is unsafe and not recommended. Paths checked for this platform: /etc/ssl/certs, /etc/ansible, /usr/local/etc/openssl. The exception msg was: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1076).", "status": -1, "url": "https://api.digitalocean.com/v2/regions"}
```
Your local system does not have a CA certificate that can validate the cloud provider's API. Are you using MacPorts instead of Homebrew? The MacPorts openssl installation does not include a CA certificate, but you can fix this by installing the [curl-ca-bundle](https://andatche.com/articles/2012/02/fixing-ssl-ca-certificates-with-openssl-from-macports/) port with `port install curl-ca-bundle`. That should do the trick.
### Could not fetch URL ... TLSV1_ALERT_PROTOCOL_VERSION
You tried to install Algo and you received an error like this one:
```
Could not fetch URL https://pypi.python.org/simple/secretstorage/: There was a problem confirming the ssl certificate: [SSL: TLSV1_ALERT_PROTOCOL_VERSION] tlsv1 alert protocol version (_ssl.c:590) - skipping
Could not find a version that satisfies the requirement SecretStorage<3 (from pyproject.toml dependencies) (from versions: )
No matching distribution found for SecretStorage<3 (from pyproject.toml dependencies)
```
It's time to upgrade your python.
`brew upgrade python3`
You can also download python 3.7.x from python.org.
Your local system does not have a CA certificate that can validate the cloud provider's API. This typically occurs with custom Python installations. Try reinstalling Python using Homebrew (`brew install python3`) or ensure your system has proper CA certificates installed.
### Bad owner or permissions on .ssh
@ -235,9 +143,9 @@ The error is caused because Digital Ocean changed its API to treat the tag argum
An exception occurred during task execution. To see the full traceback, use -vvv.
The error was: FileNotFoundError: [Errno 2] No such file or directory: '/home/ubuntu/.azure/azureProfile.json'
fatal: [localhost]: FAILED! => {"changed": false, "module_stderr": "Traceback (most recent call last):
File \"/usr/local/lib/python3.6/dist-packages/azure/cli/core/_session.py\", line 39, in load
File \"/usr/local/lib/python3.11/dist-packages/azure/cli/core/_session.py\", line 39, in load
with codecs_open(self.filename, 'r', encoding=self._encoding) as f:
File \"/usr/lib/python3.6/codecs.py\", line 897, in open\n file = builtins.open(filename, mode, buffering)
File \"/usr/lib/python3.11/codecs.py\", line 897, in open\n file = builtins.open(filename, mode, buffering)
FileNotFoundError: [Errno 2] No such file or directory: '/home/ubuntu/.azure/azureProfile.json'
", "module_stdout": "", "msg": "MODULE FAILURE
See stdout/stderr for the exact error", "rc": 1}
@ -377,7 +285,7 @@ TASK [wireguard : Generate public keys] ****************************************
fatal: [localhost]: FAILED! => {"msg": "An unhandled exception occurred while running the lookup plugin 'file'. Error was a <class 'ansible.errors.AnsibleError'>, original message: could not locate file in lookup: configs/xxx.xxx.xxx.xxx/wireguard//private/dan"}
```
This error is usually hit when using the local install option on a server that isn't Ubuntu 18.04 or later. You should upgrade your server to Ubuntu 18.04 or later. If this doesn't work, try removing files in /etc/wireguard/ and the configs directories as follows:
This error is usually hit when using the local install option on an unsupported server. Algo requires Ubuntu 22.04 LTS. You should upgrade your server to Ubuntu 22.04 LTS. If this doesn't work, try removing files in /etc/wireguard/ and the configs directories as follows:
```ssh
sudo rm -rf /etc/wireguard/*
@ -456,10 +364,6 @@ Little Snitch is not compatible with IPSEC VPNs due to a known bug in macOS and
In order to connect to the Algo VPN server, your router must support IKEv2, ECC certificate-based authentication, and the cipher suite we use. See the ipsec.conf files we generate in the `config` folder for more information. Note that we do not officially support routers as clients for Algo VPN at this time, though patches and documentation for them are welcome (for example, see open issues for [Ubiquiti](https://github.com/trailofbits/algo/issues/307) and [pfSense](https://github.com/trailofbits/algo/issues/292)).
### I can't get Network Manager to connect to the Algo server
You're trying to connect Ubuntu or Debian to the Algo server through the Network Manager GUI but it's not working. Many versions of Ubuntu and some older versions of Debian bundle a [broken version of Network Manager](https://github.com/trailofbits/algo/issues/263) without support for modern standards or the strongSwan server. You must upgrade to Ubuntu 17.04 or Debian 9 Stretch, each of which contain the required minimum version of Network Manager.
### Various websites appear to be offline through the VPN
This issue appears occasionally due to issues with [MTU](https://en.wikipedia.org/wiki/Maximum_transmission_unit) size. Different networks may require the MTU to be within a specific range to correctly pass traffic. We made an effort to set the MTU to the most conservative, most compatible size by default but problems may still occur.
@ -531,7 +435,7 @@ For IPsec on Linux you can change the MTU of your network interface to match the
```
sudo ifconfig eth0 mtu 1440
```
To make the change take affect after a reboot, on Ubuntu 18.04 and later edit the relevant file in the `/etc/netplan` directory (see `man netplan`).
To make the change take effect after a reboot, on Ubuntu 22.04 LTS edit the relevant file in the `/etc/netplan` directory (see `man netplan`).
#### Note for WireGuard iOS users

82
roles/common/tasks/freebsd.yml
View file

@ -1,82 +0,0 @@
---
- name: FreeBSD | Install prerequisites
package:
name:
- python3
- sudo
vars:
ansible_python_interpreter: /usr/local/bin/python2.7
- name: Set python3 as the interpreter to use
set_fact:
ansible_python_interpreter: /usr/local/bin/python3
- name: Gather facts
setup:
- name: Gather additional facts
import_tasks: facts.yml
- name: Fix IPv6 address selection on BSD
import_tasks: bsd_ipv6_facts.yml
when: ipv6_support | default(false) | bool
- name: Set OS specific facts
set_fact:
config_prefix: /usr/local/
strongswan_shell: /usr/sbin/nologin
strongswan_home: /var/empty
root_group: wheel
ssh_service_name: sshd
apparmor_enabled: false
strongswan_additional_plugins:
- kernel-pfroute
- kernel-pfkey
tools:
- git
- subversion
- screen
- coreutils
- openssl
- bash
- wget
sysctl:
- item: net.inet.ip.forwarding
value: 1
- item: "{{ 'net.inet6.ip6.forwarding' if ipv6_support else none }}"
value: 1
- name: Install tools
package: name="{{ item }}" state=present
with_items:
- "{{ tools|default([]) }}"
- name: Loopback included into the rc config
blockinfile:
dest: /etc/rc.conf
create: true
block: |
cloned_interfaces="lo100"
ifconfig_lo100="inet {{ local_service_ip }} netmask 255.255.255.255"
ifconfig_lo100_ipv6="inet6 {{ local_service_ipv6 }}/128"
notify:
- restart loopback bsd
- name: Enable the gateway features
lineinfile: dest=/etc/rc.conf regexp='^{{ item.param }}.*' line='{{ item.param }}={{ item.value }}'
with_items:
- { param: firewall_enable, value: '"YES"' }
- { param: firewall_type, value: '"open"' }
- { param: gateway_enable, value: '"YES"' }
- { param: natd_enable, value: '"YES"' }
- { param: natd_interface, value: '"{{ ansible_default_ipv4.device|default() }}"' }
- { param: natd_flags, value: '"-dynamic -m"' }
notify:
- restart ipfw
- name: FreeBSD | Activate IPFW
shell: >
kldstat -n ipfw.ko || kldload ipfw ; sysctl net.inet.ip.fw.enable=0 &&
bash /etc/rc.firewall && sysctl net.inet.ip.fw.enable=1
changed_when: false
- meta: flush_handlers

4
roles/common/tasks/main.yml
View file

@ -14,10 +14,6 @@
tags:
- update-users
- include_tasks: freebsd.yml
when: '"FreeBSD" in OS.stdout'
tags:
- update-users
- name: Sysctl tuning
sysctl: name="{{ item.item }}" value="{{ item.value }}"

5
roles/dns/handlers/main.yml
View file

@ -10,8 +10,3 @@
daemon_reload: true
when: ansible_distribution == 'Ubuntu'
- name: restart dnscrypt-proxy
service:
name: dnscrypt-proxy
state: restarted
when: ansible_distribution == 'FreeBSD'

9
roles/dns/tasks/freebsd.yml
View file

@ -1,9 +0,0 @@
---
- name: Install dnscrypt-proxy
package:
name: dnscrypt-proxy2
- name: Enable mac_portacl
lineinfile:
path: /etc/rc.conf
line: dnscrypt_proxy_mac_portacl_enable="YES"

3
roles/dns/tasks/main.yml
View file

@ -3,9 +3,6 @@
include_tasks: ubuntu.yml
when: ansible_distribution == 'Debian' or ansible_distribution == 'Ubuntu'
- name: Include tasks for FreeBSD
include_tasks: freebsd.yml
when: ansible_distribution == 'FreeBSD'
- name: dnscrypt-proxy ip-blacklist configured
template:

2
roles/dns/templates/dnscrypt-proxy.toml.j2
View file

@ -200,7 +200,7 @@ tls_disable_session_tickets = true
## People in China may need to use 114.114.114.114:53 here.
## Other popular options include 8.8.8.8 and 1.1.1.1.
fallback_resolver = '{% if ansible_distribution == "FreeBSD" %}{{ ansible_dns.nameservers.0 }}:53{% else %}127.0.0.53:53{% endif %}'
fallback_resolver = '127.0.0.53:53'
## Never let dnscrypt-proxy try to use the system DNS settings;

12
roles/strongswan/templates/strongswan.conf.j2
View file

@ -11,18 +11,6 @@ charon {
}
user = strongswan
group = nogroup
{% if ansible_distribution == 'FreeBSD' %}
filelog {
charon {
path = /var/log/charon.log
time_format = %b %e %T
ike_name = yes
append = no
default = 1
flush_line = yes
}
}
{% endif %}
}
include strongswan.d/*.conf

17
roles/wireguard/tasks/freebsd.yml
View file

@ -1,17 +0,0 @@
---
- name: BSD | WireGuard installed
package:
name: wireguard
state: present
- name: Set OS specific facts
set_fact:
service_name: wireguard
tags: always
- name: BSD | Configure rc script
copy:
src: wireguard.sh
dest: /usr/local/etc/rc.d/wireguard
mode: "0755"
notify: restart wireguard

4
roles/wireguard/tasks/main.yml
View file

@ -18,10 +18,6 @@
when: ansible_distribution == 'Debian' or ansible_distribution == 'Ubuntu'
tags: always
- name: Include tasks for FreeBSD
include_tasks: freebsd.yml
when: ansible_distribution == 'FreeBSD'
tags: always
- name: Generate keys
import_tasks: keys.yml