diff --git a/src/commcare_cloud/terraform/README.md b/src/commcare_cloud/terraform/README.md index f6f13d3ac1..07cb655792 100644 --- a/src/commcare_cloud/terraform/README.md +++ b/src/commcare_cloud/terraform/README.md @@ -72,155 +72,3 @@ run terraform (to create the gateway), look up its id at https://console.aws.amazon.com/vpc/home?#VpnGateways:sort=VpnGatewayId, and edit `external_routes` to hardcode the gateway, and then run terraform again. - -## VPN Setup - -### Create the OpenVPN EC2 instance with Terraform -The first time you run `cchq terraform apply`, -it will fail with a link to a terms of service you need to accept. -To do so: -1. First, make sure you are logged into https://console.aws.amazon.com/console/home - _under the correct account_. - (Each environment is it's own linked account, - so be careful you're not logged into the - e.g. staging account if you're doing this for production) -2. Then click on the link in the output -3. Accept the terms and click "Continue to Subscribe". - - -### Gain temporary SSH access via your own IP -Once the VM is created, you still need to create a VPN user before you can use the VPN. -To do this, go into the console, find the vpn ec2 instance, go to its security group, -and click Inbound Traffic > Edit > Add Rule. Select Type "SSH" and Source "My IP", -and click Save. - -Now you will be able to SSH into the VM. - -To make a cert, you'll also need to open port 80, so click Add Rule again, -select Type HTTP, **Source "Anywhere"** (needs to be publicly accessible), -and click Save. - -Finally, make sure to run - -```bash -cchq aws-fill-inventory -``` - -which will auto-generate an `[openvpn]` section to your inventory.ini. -For this to work, make sure you're using the inventory templating style. If you aren't, -you can just move `inventory.ini` to `inventory.ini.j2` before running that command, -and it'll generate `inventory.ini` for you. You can (can should) commit `inventory.ini`. - -In order to log in from the public IP address, you'll need to uncomment the ansible_host -variable of `[openvpn]`. (Don't commit this change with the file!) - -### Run the ovpn-init script - -``` -cchq ssh openvpnas@openvpn -sudo ovpn-init --ec2 -... -Please enter 'DELETE' to delete existing configuration:DELETE -... -Please enter 'yes' to indicate your agreement [no]: yes -... -``` -Make sure to type `yes` for the first prompt, and then just hit enter until it's done. -Then set a password with -``` -sudo passwd openvpn -``` -This is the password you'll use to enter the admin web UI. - -### Give others SSH access to the VPN machine -To give others SSH access to the VPN machine -(right now your access is because terraform created the VM with your public key) - -``` -cchq bootstrap-users --limit openvpn -u openvpnas -cchq deploy-stack --limit openvpn --skip-check -``` - -If this gives you any trouble, try ssh'ing in again and running - -``` -sudo apt update -sudo apt install python -``` - -to install python. - -### Set up DNS and HTTPS cert - -By whatever means you have, make a DNS entry that points a subdomain name -to the openvpn machine's public IP. The subdomain should be called `vpn.{{ SITE_HOST }}`, -e.g. if the site is at www.mycchqsite.org, it should be vpn.www.mycchqsite.org - -Then run -``` -cchq ansible-playbook openvpn_playbooks/create_openvpn_cert.yml --skip-check -vvv -e certificate_email=youremail@example.com -``` - -### Enable PAM in the web Admin UI - -OpenVPN has a number authentication modes, and we're going to use -[PAM](https://docs.openvpn.net/command-line/authentication-options-and-command-line-configuration/#PAM_authentication), -which make VPN usernames and passwords mirror linux system user usernames and passwords. -In PAM authentication mode, -enabling a user just requires setting their linux user's password with `passwd`. - -Go to `https:///admin` in your browser and log in with `openvpn`/``. -Then navigate to /admin/pam_configuration and click Use PAM, -and then click Update Running Server. - -### Activate your user - -To activate a user, run - -``` -cchq openvpn-activate-user -``` - -and then have the user (in this case, yourself) -claim the user and set their password with - -``` -cchq openvpn-claim-user -``` - -providing first the ansible sudo user password, and then the new (secure!) password -as prompted. - -### Connect to the VPN -Download the openvpn client and connect to the public IP with your username and password. - -### Un-whitelist SSH traffic from your IP address -Finally once you've proven you can get on the VPN and log into VMs with their private IPs, -and once you've created a cert, -run `cchq terraform apply` again to undo the temporary change you made via the console -that allowed you to SSH into the openvpn machine from the public internet, -and that allowed letsencrypt to make a request to port 80. - -From here on out if you need to ssh into the VPN machine, -you can either manually whitelist yourself again, or else you'll have to connect to the VPN -and use the VPN machine's private IP address. Note that if you are using the private IP -and you run `sudo service openvpnas stop`, it will disconnect you from the VPN and you -won't be able to connect again. Then you will be forced to whitelist your IP -and use the public IP to ssh in and bring it back up. - -Finally, re-comment the ansible_host variable of `[openvpn]` -(or just `git checkout -- ...` this change). - -### Make sure everything works - -Now that you've turned off your special access, make sure you can -log on to the VPN again and then run - -``` -cchq ssh openvpn -``` - -to make sure you can ssh onto the machine. - -All done! Now to activate the other users, you can run the steps from "Activate your user" -above as users ask for access.