diff --git a/README.md b/README.md index d3ecd45..eb85415 100644 --- a/README.md +++ b/README.md @@ -40,12 +40,15 @@ The easiest way to get an Algo server running is to run it on your local system 3. **Install Algo's core dependencies.** Algo requires that **Python 3.6 or later** and at least one supporting package are installed on your system. - - **macOS:** Apple does not provide Python 3 with macOS. There are two ways to obtain it: + - **macOS:** Apple does not provide a suitable version of Python 3 with macOS. Here are two ways to obtain one: * Use the [Homebrew](https://brew.sh) package manager. After installing Homebrew install Python 3 by running `brew install python3`. * Download and install the latest stable [Python 3.7.x package](https://www.python.org/downloads/mac-osx/) (currently Python 3.8 will not work). Be sure to run the included *Install Certificates* command from Finder. + See [Deploy from macOS](docs/deploy-from-macos.md) for more detailed information on installing Python 3 on macOS. + Once Python 3 is installed on your Mac, from Terminal run: + ```bash python3 -m pip install --upgrade virtualenv ``` diff --git a/docs/client-linux-wireguard.md b/docs/client-linux-wireguard.md index 96455e1..dcf2ace 100644 --- a/docs/client-linux-wireguard.md +++ b/docs/client-linux-wireguard.md @@ -5,10 +5,12 @@ To connect to your AlgoVPN using [WireGuard](https://www.wireguard.com) from Ubuntu, first install WireGuard: ```shell -# Add the WireGuard repository: +# Ubuntu 19.04 and earlier: +# Add the WireGuard repository sudo add-apt-repository ppa:wireguard/wireguard -# Update the list of available packages (not necessary on 18.04 or later): +# Ubuntu 17.10 and earlier: +# Update the list of available packages sudo apt update # Install the tools and kernel module: diff --git a/docs/deploy-from-macos.md b/docs/deploy-from-macos.md new file mode 100644 index 0000000..6a4c17a --- /dev/null +++ b/docs/deploy-from-macos.md @@ -0,0 +1,85 @@ +# Deploy from macOS + +While you can't turn a macOS system in an AlgoVPN, you can install the Algo scripts on a macOS system and use them to deploy your AlgoVPN to a cloud provider. + +Algo uses [Ansible](https://www.ansible.com) which requires Python 3. macOS does not include a version of Python 3 that you can use with Algo. (It does include an obsolete version of Python 2 installed as `/usr/bin/python` which you should ignore.) + +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. + +**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. + +## macOS 10.15 Catalina + +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. + +## Ansible and SSL Validation + +Ansible validates SSL network connections using OpenSSL but macOS includes LibreSSL which behaves differently. Therefore each version of Python below includes or depends on its own copy of OpenSSL. + +OpenSSL needs access to a list of trusted CA certificates in order to validate SSL connections. Each packager handles initializing this certificate store differently. If you see the error `CERTIFICATE_VERIFY_FAILED` when running Algo make sure you've followed the packager-specific instructions correctly, and that you're not inadvertently running Catalina's `/usr/bin/python3`. + +## Install Python 3 + +Choose one of the packagers below as your source for Python 3. Avoid installing versions from multiple packagers on the same Mac as you may encounter conflicts. In particular they might fight over creating symbolic links in `/usr/local/bin`. + +### Option 1: Install using the Homebrew package manager + +If you're comfortable using the command line in Terminal the [Homebrew](https://brew.sh) project is a great source of software for macOS. + +First install Homebrew using the instructions on the [Homebrew](https://brew.sh) page. + +The install command below takes care of initializing the CA certificate store. + +#### Installation +``` +brew install python3 +``` +After installation open a new tab or window in Terminal and verify that the command `which python3` returns `/usr/local/bin/python3`. + +#### Removal +``` +brew uninstall python3 +``` + +### Option 2: Install a package from Python.org + +If you don't want to install a package manager you can download a Python package for macOS from [python.org](https://www.python.org/downloads/mac-osx/). + +#### Installation + +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. + +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. + +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`. + +#### Removal + +Unfortunately the python.org package does not include an uninstaller and removing it requires several steps: + +1. In Finder, delete the package folder found in `/Applications`. +2. In Finder, delete the *rest* of the package found under ` /Library/Frameworks/Python.framework/Versions`. +3. In Terminal, undo the changes to your `PATH` by running: +```mv ~/.bash_profile.pysave ~/.bash_profile``` +4. In Terminal, remove the dozen or so symbolic links the package created in `/usr/local/bin`. Or just leave them because installing another version of Python will overwrite most of them. + +### Option 3: Install using the Macports package manager + +[Macports](https://www.macports.org) is another command line based package manager like Homebrew. Most users will find Macports far more complex than Homebrew, but developers might find Macports more flexible. If you search for "Macports vs. Homebrew" you will find many opinions. + +First install Macports per the [instructions](https://www.macports.org/install.php). + +In addition to installing Python you'll need to install the package containing the CA certificates. + +#### Installation +``` +sudo port install python37 +sudo port install curl-ca-bundle +``` +After installation open a new tab or window in Terminal and verify that the command `which python3` returns `/opt/local/bin/python3`. + +#### Removal +``` +sudo port uninstall python37 +sudo port uninstall curl-ca-bundle +``` diff --git a/docs/deploy-from-windows.md b/docs/deploy-from-windows.md index 8166d6e..41a91e4 100644 --- a/docs/deploy-from-windows.md +++ b/docs/deploy-from-windows.md @@ -1,8 +1,15 @@ -# Windows client prerequisite +# Deploy from Windows +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. + +To run WSL you will need: + +* A 64-bit system * 64-bit Windows 10 (Anniversary update or later version) -Once you verify your system is 64-bit (32-bit is not supported) and up to date, you have to do a few manual steps to enable the 'Windows Subsystem for Linux': +## Install WSL + +Enable the 'Windows Subsystem for Linux': 1. Open 'Settings' 2. Click 'Update & Security', then click the 'For developers' option on the left. @@ -17,17 +24,25 @@ Wait a minute for Windows to install a few things in the background (it will eve 5. Restart Windows and then [install Ubuntu from the Windows Store](https://www.microsoft.com/p/ubuntu/9nblggh4msv6). 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. +## Install Algo -Install additional packages: +Run these commands in the Ubuntu Terminal to install a prerequisite package and download the Algo scripts to your home directory. Note that when using WSL you should **not** install Algo in the `/mnt/c` directory due to problems with file permissions. + +You may need to follow [these directions](https://devblogs.microsoft.com/commandline/copy-and-paste-arrives-for-linuxwsl-consoles/) in order to paste commands into the Ubuntu Terminal. ```shell -sudo apt-get update && sudo apt-get install git build-essential libssl-dev libffi-dev python3-dev python3-pip python3-setuptools python3-virtualenv -y +cd +umask 0002 +sudo apt update +sudo apt install -y python3-virtualenv +git clone https://github.com/trailofbits/algo +cd algo ``` -Clone the Algo repository: +Now you can continue by following the [README](https://github.com/trailofbits/algo#deploy-the-algo-server) from the 4th step to deploy your Algo server! +You'll be instructed to edit the file `config.cfg` in order to specify the Algo user accounts to be created. If you're new to Linux the simplest editor to use is `nano`. To edit the file while in the `algo` directory, run: ```shell -cd ~ && git clone https://github.com/trailofbits/algo && cd algo +nano config.cfg ``` - -Now, you can go through the [README](https://github.com/trailofbits/algo#deploy-the-algo-server) (start from the 4th step) and deploy your Algo server! +Once `./algo` has finished you can use the `cp` command to copy the configuration files from the `configs` directory into your Windows directory under `/mnt/c/Users` for easier access. diff --git a/docs/index.md b/docs/index.md index 3c6e9ea..7c7bde6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,6 +6,7 @@ - Deploy from a [Docker container](deploy-from-docker.md) - Deploy from [Ansible](deploy-from-ansible.md) non-interactively - Deploy onto a [cloud server at time of creation with shell script or cloud-init](deploy-from-script-or-cloud-init-to-localhost.md) + - Deploy from [macOS](deploy-from-macos.md) * Client setup - Setup [Android](client-android.md) clients - Setup [Generic/Linux](client-linux.md) clients with Ansible diff --git a/input.yml b/input.yml index 781d2c6..8dd5ae7 100644 --- a/input.yml +++ b/input.yml @@ -21,7 +21,7 @@ - { name: Scaleway, alias: scaleway} - { name: OpenStack (DreamCompute optimised), alias: openstack } - { name: CloudStack (Exoscale optimised), alias: cloudstack } - - { name: Install to existing Ubuntu 18.04, 19.04, or 19.10 server (Advanced), alias: local } + - { name: "Install to existing Ubuntu 18.04, 19.04, or 19.10 server (Advanced)", alias: local } vars_files: - config.cfg