diff --git a/README.md b/README.md index 1a6c2298f..55b1bd6f1 100644 --- a/README.md +++ b/README.md @@ -180,6 +180,7 @@ After this process completes, the Algo VPN server will contains only the users l * Setup instructions - Documentation for available [Ansible roles](docs/setup-roles.md) + - Deploy from [Fedora Workstation (26)](docs/deploy-from-fedora-workstation.md) - Deploy from [RedHat/CentOS 6.x](docs/deploy-from-redhat-centos6.md) - Deploy from [Windows](docs/deploy-from-windows.md) - Deploy from [Ansible](docs/deploy-from-ansible.md) directly diff --git a/docs/client-linux.md b/docs/client-linux.md index 89e17e586..a5155501a 100644 --- a/docs/client-linux.md +++ b/docs/client-linux.md @@ -1,19 +1,78 @@ # Linux client setup +## Provision client config + After you deploy a server, you can use an included Ansible script to provision Linux clients too! Debian, Ubuntu, CentOS, and Fedora are supported. The playbook is `deploy_client.yml`. -### Required variables: +### Required variables * `client_ip` - The IP address of your client machine (You can use `localhost` in order to deploy locally) * `vpn_user` - The username. (Ensure that you have valid certificates and keys in the `configs/SERVER_ip/pki/` directory) * `ssh_user` - The username that we need to use in order to connect to the client machine via SSH (ignore if you are deploying locally) * `server_ip` - The vpn server ip address -### Example: +### Example ```shell ansible-playbook deploy_client.yml -e 'client_ip=client.com vpn_user=jack server_ip=vpn-server.com ssh_user=root' ``` -### Additional options: -If the user requires sudo password use the following argument: `--ask-become-pass` +### Additional options + +If the user requires sudo password use the following argument: `--ask-become-pass`. + +## OS Specific instructions + +Some Linux clients may require more specific and details instructions to configure a connection to the deployed Algo VPN, these are documented here. + +### Fedora Workstation + +#### (Gnome) Network Manager install + +We'll use the [rsclarke/NetworkManager-strongswan](https://copr.fedorainfracloud.org/coprs/rsclarke/NetworkManager-strongswan/) Copr repo (see [this comment](https://github.com/trailofbits/algo/issues/263#issuecomment-327820191)), this will make the `IKE` and `ESP` fields available in the Gnome Network Manager. Note that at time of writing the non-Copr repo will result in connection failures. Also note that the Copr repo *instructions are not filled in by author. Author knows what to do. Everybody else should avoid this repo*. So unless you are comfortable with using this repo, you'll want to hold out untill the patches applied in the Copr repo make it into stable. + +First remove the stable `NetworkManager-strongswan` package, ensure you have backups in place and / or take note of config backups taken during the removal of the package. + +```` +dnf remove NetworkManager-strongswan +```` + +Next, enable the Copr repo and install it along with the `NetworkManager-strongswan-gnome` package: + +```` +dnf copr enable -y rsclarke/NetworkManager-strongswan +dnf install NetworkManager-strongswan NetworkManager-strongswan-gnome +```` + +Reboot your machine: + +```` +reboot now +```` + +#### (Gnome) Network Manager configuration + +In this example we'll assume the IP of our Algo VPN server is `1.2.3.4` and the user we created is `user-name`. + +* Go to *Settings* > *Network* +* Add a new Network (`+` bottom left of the window) +* Select *IPsec/IKEv2 (strongswan)* +* Fill out the options: + * Name: your choice, e.g.: *ikev2-1.2.3.4* + * Gateway: + * Address: IP of the Algo VPN server, e.g: `1.2.3.4` + * Certificate: `cacert.pem` found at `/path/to/algo/1.2.3.4/cacert.pem` + * Client: + * Authentication: *Certificate/Private key* + * Certificate: `user-name.crt` found at `/path/to/algo/1.2.3.4/pki/certs/user-name.crt` + * Private key: `user-name.key` found at `/path/to/algo/1.2.3.4/pki/private/user-name.key` + * Options: + * Check *Request an inner IP address*, connection will fail without this option + * Optionally check *Enforce UDP encapsulation* + * Optionally check *Use IP compression* + * For the later 2 options, hover to option in the settings to see a description + * Cipher proposal: + * Check *Enable custom proposals* + * IKE: `aes128gcm16-prfsha512-ecp256,aes128-sha2_512-prfsha512-ecp256,aes128-sha2_384-prfsha384-ecp256` + * ESP: `aes128gcm16-ecp256,aes128-sha2_512-prfsha512-ecp256` +* Apply and turn the connection on, you should now be connected \ No newline at end of file diff --git a/docs/deploy-from-fedora-workstation.md b/docs/deploy-from-fedora-workstation.md new file mode 100644 index 000000000..319d74cf2 --- /dev/null +++ b/docs/deploy-from-fedora-workstation.md @@ -0,0 +1,126 @@ +# Deploy from Fedora Workstation + +These docs were written based on experience on Fedora Workstation 26. + +## Prerequisites + +### DNF counterparts of apt packages + +The following table lists `apt` packages with their `dnf` counterpart. This is purely informative. +Using `python2-*` in favour of `python3-*` as per [declared dependency](https://github.com/trailofbits/algo#deploy-the-algo-server). + +| `apt` | `dnf` | +| ----- | ----- | +| `build-essential` | `make automake gcc gcc-c++ kernel-devel` | +| `libssl-dev` | `openssl-devel` | +| `libffi-dev` | `libffi-devel` | +| `python-dev` | `python-devel` | +| `python-pip` | `python2-pip` | +| `python-setuptools` | `python2-setuptools` | +| `python-virtualenv` | `python2-virtualenv` | + +### Install requirements + +First, let's make sure our system is up-to-date: + +```` +dnf upgrade +```` + +Next, install the required packages: + +```` +dnf install -y \ + ansible \ + automake \ + gcc \ + gcc-c++ \ + kernel-devel \ + openssl-devel \ + libffi-devel \ + libselinux-python \ + python-devel \ + python2-pip \ + python2-setuptools \ + python2-virtualenv \ + make +```` + +## Get Algo + + +[Download](https://github.com/trailofbits/algo/archive/master.zip) or clone: + +```` +git clone git@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. + +### Check `pip` + +Run `pip -v` and check the python version it is using: + +```` +$ pip -V +pip 9.0.1 from /usr/lib/python2.7/site-packages (python 2.7) +```` + +`python 2.7` is what we're looking for. + +### `pip` upgrade and installs + +```` +# Upgrade pip itself +pip -q install --upgrade pip +# python-devel needed to prevent setup.py crash +pip -q install pycrypto +# pycrypto 2.7.1 needed for latest security patch +# This may need to run with sudo to complete without permission violations +pip -q install setuptools --upgrade +# virtualenv to make installing dependencies easier +pip -q install virtualenv +```` + +### Setup virtualenv and install requirements + +```` +virtualenv --system-site-packages env +source env/bin/activate +pip -q install --user -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 +```` + +Ensure to allow Windows / Linux clients when going through the config options. +Note the IP and password of the newly created Alfo 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). diff --git a/docs/index.md b/docs/index.md index 7275901f0..b9b94bb6a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,6 +2,7 @@ * Setup instructions - Documentation for available [Ansible roles](setup-roles.md) + - Deploy from [Fedora Workstation (26)](deploy-from-fedora-workstation.md) - Deploy from [RedHat/CentOS 6.x](deploy-from-redhat-centos6.md) - Deploy from [Windows](deploy-from-windows.md) - Deploy from [Ansible](deploy-from-ansible.md) directly