You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+35-4Lines changed: 35 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -43,7 +43,7 @@ The easiest way to get an Algo server running is to run it on your local system
43
43
-**macOS:** Apple does not provide a suitable version of Python 3 with macOS. Here are two ways to obtain one:
44
44
* Use the [Homebrew](https://brew.sh) package manager. After installing Homebrew install Python 3 by running `brew install python3`.
45
45
46
-
* Download and install the latest stable [Python 3.7.x package](https://www.python.org/downloads/mac-osx/) (currently Python 3.8 will not work). Be sure to run the included *Install Certificates* command from Finder.
46
+
* Download and install the latest stable [Python package](https://www.python.org/downloads/mac-osx/). Be sure to run the included *Install Certificates* command from Finder.
47
47
48
48
See [Deploy from macOS](docs/deploy-from-macos.md) for more detailed information on installing Python 3 on macOS.
49
49
@@ -190,11 +190,42 @@ _If you chose to save the CA key during the deploy process,_ then Algo's own scr
190
190
After this process completes, the Algo VPN server will contain only the users listed in the `config.cfg` file.
191
191
192
192
## Additional Documentation
193
-
* [Deployment instructions, cloud provider setup instructions, and further client setup instructions available here.](docs/index.md)
194
193
* [FAQ](docs/faq.md)
195
194
* [Troubleshooting](docs/troubleshooting.md)
196
-
197
-
If you read all the documentation and have further questions, [join the chat on Gitter](https://gitter.im/trailofbits/algo).
195
+
* How Algo uses [Firewalls](docs/firewalls.md)
196
+
197
+
### Setup Instructions for Specific Cloud Providers
Copy file name to clipboardExpand all lines: docs/client-linux-wireguard.md
+6-11Lines changed: 6 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,18 +2,16 @@
2
2
3
3
## Install WireGuard
4
4
5
-
To connect to your AlgoVPN using [WireGuard](https://www.wireguard.com) from Ubuntu, first install WireGuard:
5
+
To connect to your AlgoVPN using [WireGuard](https://www.wireguard.com) from Ubuntu, make sure your system is up-to-date then install WireGuard:
6
6
7
7
```shell
8
-
# Ubuntu 19.04 and earlier:
9
-
# Add the WireGuard repository
10
-
sudo add-apt-repository ppa:wireguard/wireguard
8
+
# Update your system:
9
+
sudo apt update && sudo apt upgrade
11
10
12
-
# Ubuntu 17.10 and earlier:
13
-
# Update the list of available packages
14
-
sudo apt update
11
+
# If the file /var/run/reboot-required exists then reboot:
12
+
[ -e /var/run/reboot-required ] && sudo reboot
15
13
16
-
# Install the tools and kernel module:
14
+
# Install WireGuard:
17
15
sudo apt install wireguard openresolv
18
16
```
19
17
@@ -62,6 +60,3 @@ search mydomain.com
62
60
nameserver 172.27.153.31
63
61
nameserver fd00::b:991f
64
62
```
65
-
If you're using the version of WireGuard included with Ubuntu as of 19.10 it might be from before this feature was added. To use the latest version of WireGuard add the PPA repository as shown above.
66
-
67
-
Note that using the PPA repository on Ubuntu 20.04 LTS instead of the WireGuard modules shipped in the kernel package may cause the installation of about 40 additional packages in order to compile the kernel module.
Copy file name to clipboardExpand all lines: docs/deploy-from-macos.md
+4-6Lines changed: 4 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,8 +6,6 @@ Algo uses [Ansible](https://www.ansible.com) which requires Python 3. macOS does
6
6
7
7
You'll need to install Python 3 before you can run Algo. Python 3 is available from several different packagers, three of which are listed below.
8
8
9
-
**IMPORTANT:** At this time you **cannot** use Python 3.8 or later with Ansible on macOS. Choose a recent version of Python 3.7 instead.
10
-
11
9
## macOS 10.15 Catalina
12
10
13
11
Catalina comes with `/usr/bin/python3` installed. This file, and certain others like `/usr/bin/git`, start out as stub files that prompt you to install the Developer Command Line Tools the first time you run them. Having `git` installed can be useful but whether or not you choose to install the Command Line Tools you **cannot** use this version of Python 3 with Algo at this time. Instead install one of the versions below.
@@ -47,11 +45,11 @@ If you don't want to install a package manager you can download a Python package
47
45
48
46
#### Installation
49
47
50
-
Download the most recent version of Python 3.7 and install it like any other macOS package. Then initialize the CA certificate store from Finder by double-clicking on the file `Install Certificates.command` found in the `/Applications/Python 3.7` folder.
48
+
Download the most recent version of Python and install it like any other macOS package. Then initialize the CA certificate store from Finder by double-clicking on the file `Install Certificates.command` found in the `/Applications/Python 3.8` folder.
51
49
52
50
When you double-click on `Install Certificates.command` a new Terminal window will open. If the window remains blank then the command has not run correctly. This can happen if you've changed the default shell in Terminal Preferences. Try changing it back to the default and run `Install Certificates.command` again.
53
51
54
-
After installation open a new tab or window in Terminal and verify that the command `which python3` returns either `/usr/local/bin/python3` or `/Library/Frameworks/Python.framework/Versions/3.7/bin/python3`.
52
+
After installation open a new tab or window in Terminal and verify that the command `which python3` returns either `/usr/local/bin/python3` or `/Library/Frameworks/Python.framework/Versions/3.8/bin/python3`.
55
53
56
54
#### Removal
57
55
@@ -73,13 +71,13 @@ In addition to installing Python you'll need to install the package containing t
73
71
74
72
#### Installation
75
73
```
76
-
sudo port install python37
74
+
sudo port install python38
77
75
sudo port install curl-ca-bundle
78
76
```
79
77
After installation open a new tab or window in Terminal and verify that the command `which python3` returns `/opt/local/bin/python3`.
Copy file name to clipboardExpand all lines: docs/deploy-from-windows.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Deploy from Windows
2
2
3
-
The Algo scripts can't be run directly on Windows, but you can use the Windows Subsystem for Linux (WSL) to run a copy of Ubuntu Linux right on your Windows system.
3
+
The Algo scripts can't be run directly on Windows, but you can use the Windows Subsystem for Linux (WSL) to run a copy of Ubuntu Linux right on your Windows system. You can then run Algo to deploy a VPN server to a supported cloud provider, though you can't turn the instance of Ubuntu running under WSL into a VPN server.
4
4
5
5
To run WSL you will need:
6
6
@@ -21,7 +21,7 @@ Wait a minute for Windows to install a few things in the background (it will eve
21
21
2. Click on 'Turn Windows features on or off'
22
22
3. Scroll down and check 'Windows Subsystem for Linux', and then click OK.
23
23
4. The subsystem will be installed, then Windows will require a restart.
24
-
5. Restart Windows and then [install Ubuntu from the Windows Store](https://www.microsoft.com/p/ubuntu/9nblggh4msv6).
24
+
5. Restart Windows and then [install Ubuntu 18.04 LTS from the Windows Store](https://www.microsoft.com/p/ubuntu-1804-lts/9n9tngvndl3q) (at this time Ubuntu 20.04 LTS does not work with Algo when running under WSL).
25
25
6. Run Ubuntu from the Start menu. It will take a few minutes to install. It will have you create a separate user account for the Linux subsystem. Once that's done, you will finally have Ubuntu running somewhat integrated with Windows.
Copy file name to clipboardExpand all lines: docs/faq.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,7 +21,7 @@ No. This project is under active development. We're happy to [accept and fix iss
21
21
22
22
## What's the current status of WireGuard?
23
23
24
-
[WireGuard is a work in progress](https://www.wireguard.com/#work-in-progress). It has undergone [substantial](https://www.wireguard.com/formal-verification/) security review, however, its authors are appropriately cautious about its safety and the protocol is subject to change. As a result, WireGuard does not yet have a "stable" 1.0 release. Releases are tagged with their build date -- "0.0.YYYYMMDD" -- and users should be advised to apply new updates when they are available. Your Algo server will automatically upgrade and restart WireGuard from the [official WireGuard PPA for Ubuntu](https://launchpad.net/~wireguard/+archive/ubuntu/wireguard) by default.
24
+
[WireGuard reached "stable" 1.0.0 release](https://lists.zx2c4.com/pipermail/wireguard/2020-March/005206.html) in Spring 2020. It has undergone [substantial](https://www.wireguard.com/formal-verification/) security review.
Copy file name to clipboardExpand all lines: docs/troubleshooting.md
+57-2Lines changed: 57 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,8 +16,10 @@ First of all, check [this](https://github.com/trailofbits/algo#features) and ens
16
16
*[AWS: "Deploy the template" fails with CREATE_FAILED](#aws-deploy-the-template-fails-with-create_failed)
17
17
*[AWS: not authorized to perform: cloudformation:UpdateStack](#aws-not-authorized-to-perform-cloudformationupdatestack)
18
18
*[DigitalOcean: error tagging resource 'xxxxxxxx': param is missing or the value is empty: resources](#digitalocean-error-tagging-resource)
19
+
*[Azure: The client xxx with object id xxx does not have authorization to perform action Microsoft.Resources/subscriptions/resourcegroups/write' over scope](#azure-deployment-permissions-error)
19
20
*[Windows: The value of parameter linuxConfiguration.ssh.publicKeys.keyData is invalid](#windows-the-value-of-parameter-linuxconfigurationsshpublickeyskeydata-is-invalid)
20
21
*[Docker: Failed to connect to the host via ssh](#docker-failed-to-connect-to-the-host-via-ssh)
22
+
*[Error: Failed to create symlinks for deploying to localhost](#error-failed-to-create-symlinks-for-deploying-to-localhost)
21
23
*[Wireguard: Unable to find 'configs/...' in expected paths](#wireguard-unable-to-find-configs-in-expected-paths)
22
24
*[Ubuntu Error: "unable to write 'random state'" when generating CA password](#ubuntu-error-unable-to-write-random-state-when-generating-ca-password)
23
25
*[Connection Problems](#connection-problems)
@@ -240,6 +242,23 @@ See stdout/stderr for the exact error", "rc": 1}
240
242
241
243
It happens when your machine is not authenticated in the azure cloud, follow this [guide](https://trailofbits.github.io/algo/cloud-azure.html) to configure your environment
242
244
245
+
### Azure: Deployment Permissions Error
246
+
247
+
The AAD Application Registration (aka, the 'Service Principal', where you got the ClientId) needs permission to create the resources for the subscription. Otherwise, you will get the following error when you run the Ansible deploy script:
248
+
249
+
```
250
+
fatal: [localhost]: FAILED! => {"changed": false, "msg": "Resource group create_or_update failed with status code: 403 and message: The client 'xxxxx' with object id 'THE_OBJECT_ID' does not have authorization to perform action 'Microsoft.Resources/subscriptions/resourcegroups/write' over scope '/subscriptions/THE_SUBSCRIPTION_ID/resourcegroups/algo' or the scope is invalid. If access was recently granted, please refresh your credentials."}
251
+
```
252
+
253
+
The solution for this is to open the Azure CLI and run the following command to grant contributor role to the Service Principal:
254
+
255
+
```
256
+
az role assignment create --assignee-object-id THE_OBJECT_ID --scope subscriptions/THE_SUBSCRIPTION_ID --role contributor
257
+
```
258
+
259
+
After this is applied, the Service Principal has permissions to create the resources and you can re-run `ansible-playbook main.yml` to complete the deployment.
260
+
261
+
243
262
### Windows: The value of parameter linuxConfiguration.ssh.publicKeys.keyData is invalid
244
263
245
264
You tried to deploy Algo from Windows and you received an error like this one:
@@ -273,6 +292,41 @@ You need to add the following to the ansible.cfg in repo root:
273
292
control_path_dir=/dev/shm/ansible_control_path
274
293
```
275
294
295
+
### Error: Failed to create symlinks for deploying to localhost
296
+
297
+
You tried to run Algo and you received an error like this one:
298
+
299
+
```
300
+
TASK [Create a symlink if deploying to localhost] ********************************************************************
301
+
fatal: [localhost]: FAILED! => {"changed": false, "gid": 1000, "group": "ubuntu", "mode": "0775", "msg": "the directory configs/localhost is not empty, refusing to convert it", "owner": "ubuntu", "path": "configs/localhost", "size": 4096, "state": "directory", "uid": 1000}
302
+
included: /home/ubuntu/algo-master/playbooks/rescue.yml for localhost
TASK [Fail the installation] *****************************************************************************************
314
+
```
315
+
This error is usually encountered when using the local install option and `localhost` is provided in answer to this question, which is expecting an IP address or domain name of your server:
316
+
```
317
+
Enter the public IP address or domain name of your server: (IMPORTANT! This is used to verify the certificate)
318
+
[localhost]
319
+
:
320
+
```
321
+
322
+
You should remove the files in /etc/wireguard/ and configs/ as follows:
323
+
```ssh
324
+
sudo rm -rf /etc/wireguard/*
325
+
rm -rf configs/*
326
+
```
327
+
328
+
And then immediately re-run `./algo` and provide a domain name or IP address in response to the question referenced above.
329
+
276
330
### Wireguard: Unable to find 'configs/...' in expected paths
277
331
278
332
You tried to run Algo and you received an error like this one:
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"}
285
339
```
286
-
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 `*.lock`files at /etc/wireguard/ as follows:
340
+
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:
0 commit comments