{"id":15638040,"url":"https://github.com/dumrauf/openvpn-terraform-install","last_synced_at":"2025-04-13T09:51:06.468Z","repository":{"id":40345882,"uuid":"208129377","full_name":"dumrauf/openvpn-terraform-install","owner":"dumrauf","description":"A one-stop Terraform module that creates an OpenVPN server in AWS readily provisioned with access by the users defined in the input","archived":false,"fork":false,"pushed_at":"2024-05-21T15:38:16.000Z","size":16,"stargazers_count":136,"open_issues_count":7,"forks_count":72,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-27T01:12:21.505Z","etag":null,"topics":["aws","bash","openvpn-server","provisioning","terraform"],"latest_commit_sha":null,"homepage":null,"language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dumrauf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-12T19:23:02.000Z","updated_at":"2025-03-19T14:31:16.000Z","dependencies_parsed_at":"2024-10-22T19:52:37.811Z","dependency_job_id":null,"html_url":"https://github.com/dumrauf/openvpn-terraform-install","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dumrauf%2Fopenvpn-terraform-install","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dumrauf%2Fopenvpn-terraform-install/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dumrauf%2Fopenvpn-terraform-install/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dumrauf%2Fopenvpn-terraform-install/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dumrauf","download_url":"https://codeload.github.com/dumrauf/openvpn-terraform-install/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248695300,"owners_count":21146952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","bash","openvpn-server","provisioning","terraform"],"created_at":"2024-10-03T11:17:02.287Z","updated_at":"2025-04-13T09:51:06.440Z","avatar_url":"https://github.com/dumrauf.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# A Comprehensive OpenVPN Server Solution in AWS with Terraform\n\nThis repository contains a one-stop Terraform module that creates a single node [OpenVPN Server](https://en.wikipedia.org/wiki/OpenVPN) cluster in a dedicated AWS VPC and subnet. The OpenVPN server is configured to be readily accessible by the users supplied in the Terraform input file. The same Terraform input file can be used to subsequently update the list of authorised users.\n\n\u003e For further information, see the corresponding article on [Ready to Use OpenVPN Servers in AWS For Everyone](https://www.how-hard-can-it.be/openvpn-server-install-terraform-aws/?utm_source=GitHub\u0026utm_medium=social\u0026utm_campaign=README) on [How Hard Can It Be?!](https://www.how-hard-can-it.be/?utm_source=GitHub\u0026utm_medium=social\u0026utm_campaign=README).\n\nThe master branch in this repository is compliant with [Terraform v0.12](https://www.terraform.io/upgrade-guides/0-12.html); a legacy version that is compatible with [Terraform v0.11](https://www.terraform.io/upgrade-guides/0-11.html) is available on branch [terraform@0.11](https://github.com/dumrauf/openvpn-terraform-install/tree/terraform%400.11).\n\n\n## You Have\n\nBefore you can use the Terraform module in this repository out of the box, you need\n\n - an [AWS account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html)\n - a [Terraform](https://www.terraform.io/intro/getting-started/install.html) CLI\n - a list of users to provision with OpenVPN access\n\nMoreover, you probably had enough of people snooping on you and want some privacy back or just prefer to have a long lived static IP.\n\n\n## You Want\n\nAfter running the Terraform module in this repository you get\n - an EC2 node running in a dedicated VPC and subnet\n - an OpenVPN server bootstrapped on the EC2 node by the excellent [openvpn-install.sh](https://github.com/angristan/openvpn-install/blob/master/openvpn-install.sh) Bash script from [https://github.com/angristan/openvpn-install](https://github.com/angristan/openvpn-install)\n - SSH access to the OpenVPN sever locked down to the IP address of the machine executing the Terraform module (see the FAQs for how to handle drift over time)\n - the list of users supplied as input to the Terraform module readily provisioned on the OpenVPN server\n - the configuration of each user supplied in the Terraform configuration downloaded onto the local machine and ready for use\n - the option to provision and revoke users from the OpenVPN server by simply re-running the Terraform module \n\n\n## Setup\n\nThe minimal setup leverages as much of the default settings in [variables.tf](variables.tf) as possible. However some input is required.\n\n### Providing SSH Keys\n\nIn order to bootstrap as well as manage the OpenVPN server, the Terraform module needs to SSH into the EC2 node. By default, it uses the public key in `settings/openvpn.pub` and the private key in `settings/openvpn`. Both can be created by executing the following command from the root directory of this repository\n```\ncd settings\nssh-keygen -f openvpn -t rsa\n```\nHere, hit return when prompted for a password in order to make the SSH keys passwordless.\n\n### Configuring Your Settings\n\nThe minimum input variables for the module are defined in [settings/example.tfvars](settings/example.tfvars) to be\n```hcl\naws_region = \"\u003cyour-region\u003e\"\n\nshared_credentials_file = \"/path/to/.aws/credentials\"\n\nprofile = \"\u003cyour-profile\u003e\"\n\novpn_users = [\"userOne\", \"userTwo\", \"userThree\"]\n```\nHere, you need to replace the example values with your settings.\n\nMoreover, note that users `userOne`, `userTwo`, and `userThree` will be provisioned with access to the OpenVPN sever and their configurations downloaded to the default location `generated/ovpn-config`.\n\n\u003e Each user provisioned via input `ovpn_users` should preferably be defined as a single word (i.e., no whitespace), _consisting only of ASCII letters and numbers with underscores as delimiters_; in technical terms, each user should adhere to `^[a-zA-Z0-9_]+$`.\n\n## Execution\n\nAll Terraform interactions are wrapped in helper Bash scripts for convenience.\n\n### Initialising Terraform\n\nInitialise Terraform by running\n```\n./terraform-bootstrap.sh\n```\n\n### Applying the Terraform Configuration\n\nThe OpenVPN server can be created and updated by running\n```\n./terraform-apply.sh \u003cinput-file-name\u003e\n```\nwhere `\u003cinput-file-name\u003e` references input file `settings/\u003cinput-file-name\u003e.tfvars`.\nWhen using input file [settings/example.tfvars](settings/example.tfvars) configured above, the command becomes\n```\n./terraform-apply.sh example\n```\nUnder the bonnet, the `terraform-apply.sh` Bash script with input `example`\n - selects or creates a new workspace called `example`\n - executes `terraform apply` where the inputs are taken from input file `settings/example.tfvars`\n - does not ask for permission to proceed as it uses `-auto-approve` when running the underlying `terraform apply` command\n\n\n## Terraform Outputs\n\nBy default, all `.ovpn` configurations for the users provisioned with access to the OpenVPN server in input `ovpn_users` are automatically downloaded to `generated/ovpn-config`.\n\nAdditionally, the Terraform module also outputs\n - the `ec2_instance_dns`\n - the `ec2_instance_ip` and\n - a `connection_string` that can be used to SSH into the EC2 node \n\n## Deletion\n\nThe OpenVPN server can be deleted by running\n```\n./terraform-destroy.sh \u003cinput-file-name\u003e\n```\nwhere `\u003cinput-file-name\u003e` again references input file `settings/\u003cinput-file-name\u003e.tfvars`.\nWhen using input file [settings/example.tfvars](settings/example.tfvars) configured above, the command becomes\n```\n./terraform-destroy.sh example\n```\n\nUnder the bonnet, the `terraform-destroy.sh` Bash script with input `example`\n - selects the `example` workspace\n - executes `terraform destroy` where the inputs are taken from file `settings/example.tfvars`\n - _does ask for permission_ to proceed when running the `terraform apply` command\n\n\n## Testing VPN Connectivity\n\nOnce the Terraform module execution has successfully completed, the connection to the OpenVPN can be tested as follows. \n\n\u003e While below instructions are specific to a recent Mac using [Homebrew](https://brew.sh/) as a package manager, the actual underlying `openvpn` command should be fairly transferable to other platforms as well.\n\nIf not already present, install `openvpn` via `brew` by executing\n```\nbrew install openvpn\n```\nFollow the instructions on screen and if the installation may need a little final nudge, try running\n```\nsudo brew services start openvpn\n```\nIn case `openvpn` isn't readily available from the terminal after the installation above, a [StackOverflow answer](https://apple.stackexchange.com/a/233221) suggests to add the `openvpn` executable to the `$PATH` environment variable by executing\n```\nexport PATH=$(brew --prefix openvpn)/sbin:$PATH\n```\nAssuming a valid OpenVPN configuration has been downloaded to `generated/ovpn-config/userOne.ovpn `, the connection can be tested by initiating the actual `openvpn` connection by running\n```\nsudo openvpn --config generated/ovpn-config/userOne.ovpn \n```\n\u003e Note that the above command will actually change your network settings and hence public IP.\n\n\n## Credits\n\nThis repository relies on the great [openvpn-install.sh](https://github.com/angristan/openvpn-install/blob/master/openvpn-install.sh) Bash script from [https://github.com/angristan/openvpn-install](https://github.com/angristan/openvpn-install) to do the OpenVPN plumbing under the bonnet. Keep up the good work, Stanislas Lange, aka [angristan](https://angristan.xyz/)!\n\n\n## FAQs\n\nBelow is a list of frequently asked questions.\n\n### I Cannot SSH Into the OpenVPN Server Any Longer!\n\nMost likely, the IP address of your machine executing the Terraform module has changed since the original installation. The security groups for the OpenVPN server are designed to only permit SSH access from a single predefined IP address. As this has drifted from the original value, you are being refused SSH access. But this scenario has been incorporated into the design of the Terraform module.\n\nJust re-run the `./terraform-apply.sh` Bash script again with your `\u003cinput-file-name\u003e`. Terraform should pick up your new IP address and update the ingress rules for the security groups accordingly.\n\n### Why Is There no Route 53/DNS Support for Custom Domains?\n\nCustom domains are great for running an OpenVPN server at [vpn.how-hard-can-it.be](vpn.how-hard-can-it.be). However, depending on the domain, its age, and many other factors, a provider may choose to _not resolve_ the domain which leaves the OpenVPN server unreachable when it may be needed the most.\n\nStandard AWS URLs such as [ec2-1-2-3-4.eu-west-2.compute.amazonaws.com](ec2-1-2-3-4.eu-west-2.compute.amazonaws.com) tend to be resolved by most providers. It's probably not the most memorable URL but it tends to work in the places I personally care about.\n\n### How Do I Configure OpenVPN Access on My Mac?\n\nPlease refer to the excellent guide on [Downloading and Installing Tunnelblick](https://tunnelblick.net/cInstall.html).\n\n### How Do I Configure OpenVPN Access On My iPhone?\n\nPlease refer to the excellent guide on how to [Install OpenVPN on iOS](https://www.ovpn.com/en/guides/ios).\nFor transferring `.ovpn` configurations onto your iPhone, please refer to [Transfer Files to Your Mobile By Scanning a QR Code](https://www.how-hard-can-it.be/transfer-files-to-your-mobile-by-scanning-a-qr-code/).\n\n### How Do I Configure OpenVPN Access On My Android phone?\n\nPlease refer to the excellent [Guide to install OpenVPN Connect for Android](https://www.ovpn.com/en/guides/android).\nFor transferring `.ovpn` configurations onto your Android phone, please refer to [Transfer Files to Your Mobile By Scanning a QR Code](https://www.how-hard-can-it.be/transfer-files-to-your-mobile-by-scanning-a-qr-code/).\n \n### How do I Add or Remove Users from a Provisioned OpenVPN Server?\n\nSimply add or remove the users from the list of `ovpn_users` in your `settings/\u003cinput-file-name\u003e.tfvars` input file and re-run `./terraform-apply.sh \u003cinput-file-name\u003e` as described above.\n\n### Why is There no Load Balancing?\n\nThis Terraform module has been deliberately kept simple. It's intended for personal use and to reclaim some lost privacy, security, and freedom. If you require professional or enterprise level VPN services, then there is a sheer abundance of [commercial VPN providers](https://en.wikipedia.org/wiki/Comparison_of_virtual_private_network_services) to choose from.\n\nThis isn't to say that it wouldn't be a fun project to put the OpenVPN servers behind ASGs and ALBs and spin up bastion hosts on demand. However, this makes the key handling a bit more complicated. If you're interested, reach out and we can discuss over a pint.\n\nOn a side note: From personal experience, a single node OpenVPN cluster has served my digital family with a handful of more of less permanently connected devices well on a daily base over the course of the past six months. And running.\n\n### Why Is Terraform Also Being Used for User Provisioning and Maintenance?\n\nIn one word: simplicity.\n\nTerraform is great for provisioning (fairly static) infrastructure but there are more sophisticated tools out there for provisioning and maintaining elastic infrastructure at scale, let alone user provisioning and maintenance. For sake of simplicity, Terraform is being used as the single tool of choice in this case.\n\n### Wait — There's a Pint Bounty in the Code?!\n\nYes. Find it. Solve it. Bag your reward. I'm looking forward to your solutions! Teach me something new!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdumrauf%2Fopenvpn-terraform-install","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdumrauf%2Fopenvpn-terraform-install","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdumrauf%2Fopenvpn-terraform-install/lists"}