This module is used to initialize the OpenVPN server, its Public Key Infrastructure (PKI), Certificate Authority
(CA) and configuration on a server that has been installed using the install-openvpn module.
How do you use this module?
Example
See the example for an example of how to use this module.
You can configure several options to control the behavior of OpenVPN.
Option
Description
Required
Default
--s3-bucket-name
The name of an S3 bucket that will be used to backup the PKI
Required
--kms-key-id
The id of a KMS key that will used to encrypt/decrypt the PKI when stored in S3
Required
--email
The e-mail address of the administrator. Used in the CA configuration
Required
--org-unit
The name of the unit, department, or scope within your organization for which this CA certificate will be used
Required
--org
The name of your organization (e.g. Gruntwork)
Required
--locality
The locality name (e.g. city or town name) where your organization is located
Required
--state
The state or province name where your organization is located. Use the full, unabbreviated name. E.g. New Jersey
Required
--country
The two-letter country name where your organization is located (see https://www.digicert.com/ssl-certificate-country-codes.htm)
Required
--vpn-subnet
The subnet the vpn clients will be assigned addresses from, in subnet mask format. Eg, "10.1.14.0 255.255.255.0"
Required
--vpn-route
Routes to subnets that will be protected by the VPN and will be pushed to the VPN clients, in [subnet] [mask] format. Eg, "10.100.0.0 255.255.255.0". Can be specified multiple times.
Required
--key-size
The key size (in bits) for server and client certificates
Optional
4096
--ca-expiration-days
The number of days the CA root certificate will be valid for
Optional
3650 (10 years)
--cert-expiration-days
The number of days a server or user certificate issued by the CA will be valid for
Optional
3650 (10 years)
--crl-expiration-days
The number of days the CA Certificate Revocation List (CRL) will be valid for
Optional
3650 (10 years)
Configure the OpenVPN Package on your EC2 Instances
In order for the EC2 Instance to run OpenVPN sucessfully, it needs certain data from the EC2 instance.
When your EC2 Instances are booting up, they should run the init-openvpn script, which will configure
OpenVPN on your instance.
The best way to run a script during boot is to put it in User
Data. Here's an example:
The initial generation of PKI is very CPU intensive and can take a long time (30+ minutes), especially on baseline/burst
type instances such as the t2 family. See here
for additional information.
Questions? Ask away.
We're here to talk about our services, answer any questions, give advice, or just to chat.
{"treedata":{"name":"root","toggled":true,"children":[{"name":".circleci","children":[{"name":"config.yml","path":".circleci/config.yml","sha":"fee13868ddb9ad5868f643b026ec1116a38595d6"}]},{"name":".gitignore","path":".gitignore","sha":"e02f16ef8063fc8d9d24ad92b30536beb06aba44"},{"name":".pre-commit-config.yaml","path":".pre-commit-config.yaml","sha":"f1c2078a2f571b67d25e7ab70e8c68a7e2d3cb2e"},{"name":"CODEOWNERS","path":"CODEOWNERS","sha":"15d972adbfebfa5a892db95c9938f37f78e7e212"},{"name":"LICENSE.txt","path":"LICENSE.txt","sha":"5ae97660cb6e3a07b61c971f1a25edf402e90f53"},{"name":"README.md","path":"README.md","sha":"a29328189fe4c3156b35faffa409c8c734b621f6"},{"name":"examples","children":[{"name":"openvpn-host-duo","children":[{"name":"README.md","path":"examples/openvpn-host-duo/README.md","sha":"1a3065f058745f0f03fd74844ac4e872d52538de"},{"name":"main.tf","path":"examples/openvpn-host-duo/main.tf","sha":"b448f71a0dbdca141fd433817558aee4d89bd9ad"},{"name":"outputs.tf","path":"examples/openvpn-host-duo/outputs.tf","sha":"f527145f657a5a99d32c301c591f461f2230e3b9"},{"name":"user-data","children":[{"name":"user-data.sh","path":"examples/openvpn-host-duo/user-data/user-data.sh","sha":"83cc9cc2145089141c3e7c58b3c930eeeb609c42"}]},{"name":"vars.tf","path":"examples/openvpn-host-duo/vars.tf","sha":"971f40f327c39879381f708f592c8523d452a021"}]},{"name":"openvpn-host","children":[{"name":"README.md","path":"examples/openvpn-host/README.md","sha":"a9a87d6764976a5828c1eb5318dc956dd08c68b7"},{"name":"main.tf","path":"examples/openvpn-host/main.tf","sha":"5f495ea6eb3728b628488bd31ed0da9d16d71def"},{"name":"outputs.tf","path":"examples/openvpn-host/outputs.tf","sha":"f527145f657a5a99d32c301c591f461f2230e3b9"},{"name":"user-data","children":[{"name":"user-data.sh","path":"examples/openvpn-host/user-data/user-data.sh","sha":"04787c97e63d89c1ac32fb1f91f0398800f83074"}]},{"name":"vars.tf","path":"examples/openvpn-host/vars.tf","sha":"0a491410951acdf4342e7cf25fc66a78f23e92a5"}]},{"name":"packer-duo","children":[{"name":"README.md","path":"examples/packer-duo/README.md","sha":"d885b8114f2af50fb01d4707e56bb81ae79da798"},{"name":"build.json","path":"examples/packer-duo/build.json","sha":"fbe8a2f7313660c93da99868810ee6ff18f162d9"}]},{"name":"packer","children":[{"name":"README.md","path":"examples/packer/README.md","sha":"de54777e323364919ee79bbf2f2c5d942de9e7dd"},{"name":"build.json","path":"examples/packer/build.json","sha":"ebbac8539250663fc075fe8c0e73c1dc84128894"}]}]},{"name":"modules","children":[{"name":"backup-openvpn-pki","children":[{"name":"README.md","path":"modules/backup-openvpn-pki/README.md","sha":"c853b20534e6e86c36074f55e1a29b98d9379800"},{"name":"bin","children":[{"name":"backup-openvpn-pki","path":"modules/backup-openvpn-pki/bin/backup-openvpn-pki","sha":"ac4b49684ea0dc776449f786473975fc98db79b5"}]},{"name":"install.sh","path":"modules/backup-openvpn-pki/install.sh","sha":"af225b1dcd43eaab802a9e8040b3d39e25dd46a0"}]},{"name":"init-openvpn","children":[{"name":"README.md","path":"modules/init-openvpn/README.md","sha":"5da988bb51256e80eed3a73208f21b0735e49dd5","toggled":true},{"name":"bin","children":[{"name":"init-openvpn","path":"modules/init-openvpn/bin/init-openvpn","sha":"58e820ac74a38a8581c354d2cf0a49964d8ea8e4"}]},{"name":"install.sh","path":"modules/init-openvpn/install.sh","sha":"9a41f990f62b2a9b526edfa813075cff277e1312"}],"toggled":true},{"name":"install-openvpn","children":[{"name":"README.md","path":"modules/install-openvpn/README.md","sha":"2a41a29b9919a83e642e13a1b92d521d94e5ac8f"},{"name":"bin","children":[{"name":"install-openvpn","path":"modules/install-openvpn/bin/install-openvpn","sha":"4e263e78be4ae4179d32e9d2b09c48d09c52a1c5"}]},{"name":"files","children":[{"name":"before.rules","path":"modules/install-openvpn/files/before.rules","sha":"e9f11106dda0d258910a36d88b3cac05c0d85146"},{"name":"openvpn-client.ovpn","path":"modules/install-openvpn/files/openvpn-client.ovpn","sha":"3fe8af5d74c724399d2b2acaaac3e5d07889912f"},{"name":"ufw-default","path":"modules/install-openvpn/files/ufw-default","sha":"ff5e7f69b1f65a2760579d4aa7575b278273e56b"},{"name":"vars.local","path":"modules/install-openvpn/files/vars.local","sha":"b19ce7da2758a7792a05d7563201127f8b1542c9"}]},{"name":"install.sh","path":"modules/install-openvpn/install.sh","sha":"65c8ed227131e94e7db76f47093f05b953950d07"},{"name":"scripts","children":[{"name":"generate-wrapper.sh","path":"modules/install-openvpn/scripts/generate-wrapper.sh","sha":"34d49724be9c3555a886d3cf00cf9cdbcb2a43bf"},{"name":"revoke-wrapper.sh","path":"modules/install-openvpn/scripts/revoke-wrapper.sh","sha":"d158a871cdd70cfed92418b6618d81c6bef08bd7"}]}]},{"name":"openvpn-admin","children":[{"name":".dockerignore","path":"modules/openvpn-admin/.dockerignore","sha":"a725465aee245635a2bd129af54858ed32c84cb8"},{"name":"Dockerfile","path":"modules/openvpn-admin/Dockerfile","sha":"e55bdd58b77185ca43d18487c5a0f55f0e7c8c4d"},{"name":"Gopkg.lock","path":"modules/openvpn-admin/Gopkg.lock","sha":"920292f49271fe4edbed14f95a945d442732318c"},{"name":"Gopkg.toml","path":"modules/openvpn-admin/Gopkg.toml","sha":"1b8610838c12961d53800706b55e88d2a4a8c935"},{"name":"README.md","path":"modules/openvpn-admin/README.md","sha":"e8e5fbeaa6a6ff9099bca567cb7f0843a6d21b12"},{"name":"_ci","children":[{"name":"build-and-test.sh","path":"modules/openvpn-admin/_ci/build-and-test.sh","sha":"7b57f49d2a5cbce5f3e833c6e3dac767a90a92fa"},{"name":"test.sh","path":"modules/openvpn-admin/_ci/test.sh","sha":"ba48b9b10f31ca3f2e41ee3ce85e04d6ae289657"}]},{"name":"docker-compose.yml","path":"modules/openvpn-admin/docker-compose.yml","sha":"6c025d5d3a2b74cfb8f64bd822af25f7d5b1ddce"},{"name":"openvpn-request-flow-diagram.svg","path":"modules/openvpn-admin/openvpn-request-flow-diagram.svg","sha":"4c170df3fd6cf76d4c8e0bed7e1f2dbd98c08942"},{"name":"openvpn-revoke-flow-diagram.svg","path":"modules/openvpn-admin/openvpn-revoke-flow-diagram.svg","sha":"488101bcb015fee6de88b69ad8291b8a8daaf2d4"},{"name":"scripts","children":[{"name":"build-linux-binary.sh","path":"modules/openvpn-admin/scripts/build-linux-binary.sh","sha":"3dfe844499b28878ebbb177453887bc786aec4de"},{"name":"run.sh","path":"modules/openvpn-admin/scripts/run.sh","sha":"bbcb7f9bdf8578561226954669cdb3e886093fcb"}]},{"name":"src","children":[{"name":"app","children":[{"name":"app.go","path":"modules/openvpn-admin/src/app/app.go","sha":"a44005b1646dd00356abba832f13ff35bc23cbf5"},{"name":"cert_helpers.go","path":"modules/openvpn-admin/src/app/cert_helpers.go","sha":"04d9a2d6c1b517affbece3b803965d2b3ae43877"},{"name":"cmd_process_certificate_requests.go","path":"modules/openvpn-admin/src/app/cmd_process_certificate_requests.go","sha":"1c8827858631988f18f51f4d94106dc39d81ecaa"},{"name":"cmd_process_certificate_revocation_requests.go","path":"modules/openvpn-admin/src/app/cmd_process_certificate_revocation_requests.go","sha":"6ea3fec1a916d8c839aefd32deb6f68663def406"},{"name":"cmd_request_new_certificate.go","path":"modules/openvpn-admin/src/app/cmd_request_new_certificate.go","sha":"eb001cc71d0eeb9f7bdb29b9061a1d697a824d43"},{"name":"cmd_revoke_certificate.go","path":"modules/openvpn-admin/src/app/cmd_revoke_certificate.go","sha":"455056232c13fb93ec8b90bdc891ab38a0f35eb5"},{"name":"common.go","path":"modules/openvpn-admin/src/app/common.go","sha":"fb65408ed46425bf8677b97500de5f82933ee811"},{"name":"flags.go","path":"modules/openvpn-admin/src/app/flags.go","sha":"c0e210efcb43e275d3acf88f12ce03ad8767a6bb"}]},{"name":"aws_helpers","children":[{"name":"iam.go","path":"modules/openvpn-admin/src/aws_helpers/iam.go","sha":"f9ad47acc0a23d3a9f6e9ffdeeee23659bb302a5"},{"name":"sqs.go","path":"modules/openvpn-admin/src/aws_helpers/sqs.go","sha":"9e61c8cedf3daab50a28f7d958fb65624fb0b9a5"}]},{"name":"main.go","path":"modules/openvpn-admin/src/main.go","sha":"1f17d4255393abff481c4a355ccff24faebbccf2"}]}]},{"name":"openvpn-server","children":[{"name":"README.md","path":"modules/openvpn-server/README.md","sha":"5059439e763295779f0ece5bbe8afaa52d533367"},{"name":"main.tf","path":"modules/openvpn-server/main.tf","sha":"01f9fc88a7fcf9e2517a79bfab2fe596315e0dac"},{"name":"outputs.tf","path":"modules/openvpn-server/outputs.tf","sha":"86430ff0de800dd8847db8973eeb396e0b688f77"},{"name":"vars.tf","path":"modules/openvpn-server/vars.tf","sha":"6e47622e591207af9623c0dd55d4309e51ca21f9"}]},{"name":"start-openvpn-admin","children":[{"name":"README.md","path":"modules/start-openvpn-admin/README.md","sha":"0c9902a49939a60e80a57fa0f39bfbb50eafd40a"},{"name":"bin","children":[{"name":"run-process-requests","path":"modules/start-openvpn-admin/bin/run-process-requests","sha":"6c8c52b3a6b6d58fd9cedfa40212071a27cc703c"},{"name":"run-process-revokes","path":"modules/start-openvpn-admin/bin/run-process-revokes","sha":"cffcbe2dcc9f16dd6989a68153e81edede8c0cb2"}]},{"name":"install.sh","path":"modules/start-openvpn-admin/install.sh","sha":"2af5af7f24c40136b22d50cb8cec47f7a9d2b2ac"}]}],"toggled":true},{"name":"test","children":[{"name":"Gopkg.lock","path":"test/Gopkg.lock","sha":"68381d1bad78e20ebbedba92aaee6b08144d2c26"},{"name":"Gopkg.toml","path":"test/Gopkg.toml","sha":"5bcec2bb558fa00fab495be3fe48307a5d513902"},{"name":"README.md","path":"test/README.md","sha":"6c2e79488468f407d805afb5c83a41b523a16195"},{"name":"local-test","children":[{"name":"docker-compose.yml","path":"test/local-test/docker-compose.yml","sha":"e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"}]},{"name":"openvpn_test.go","path":"test/openvpn_test.go","sha":"85e9af0ad3e7fde2c226c3f4845c518f6f2c4e18"}]}]},"detailsContent":"<h1 class=\"preview__body--title\" id=\"init-open-vpn-module\">Init OpenVPN Module</h1><div class=\"preview__body--border\"></div><p>This module is used to initialize the OpenVPN server, its Public Key Infrastructure (PKI), Certificate Authority\n(CA) and configuration on a server that has been installed using the <a href=\"/repos/v0.9.10/package-openvpn/modules/install-openvpn\" class=\"preview__body--description--blue\">install-openvpn</a> module.</p>\n<h2 class=\"preview__body--subtitle\" id=\"how-do-you-use-this-module\">How do you use this module?</h2>\n<h4 id=\"example\">Example</h4>\n<p>See the <a href=\"/repos/v0.9.10/package-openvpn/examples/openvpn-host\" class=\"preview__body--description--blue\">example</a> for an example of how to use this module.</p>\n<h4 id=\"installation\">Installation</h4>\n<pre>gruntwork-install <span class=\"hljs-params\">--module-name</span> init-openvpn <span class=\"hljs-params\">--tag</span> v0.4.0 <span class=\"hljs-params\">--repo</span> https:<span class=\"hljs-string\">//github.com/gruntwork-io/package-openvpn</span>\n</pre>\n<h4 id=\"configuration-options\">Configuration Options</h4>\n<p>You can configure several options to control the behavior of OpenVPN.</p>\n<table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Description</th>\n<th>Required</th>\n<th>Default</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>--s3-bucket-name</td>\n<td>The name of an S3 bucket that will be used to backup the PKI</td>\n<td>Required</td>\n<td></td>\n</tr>\n<tr>\n<td>--kms-key-id</td>\n<td>The id of a KMS key that will used to encrypt/decrypt the PKI when stored in S3</td>\n<td>Required</td>\n<td></td>\n</tr>\n<tr>\n<td>--email</td>\n<td>The e-mail address of the administrator. Used in the CA configuration</td>\n<td>Required</td>\n<td></td>\n</tr>\n<tr>\n<td>--org-unit</td>\n<td>The name of the unit, department, or scope within your organization for which this CA certificate will be used</td>\n<td>Required</td>\n<td></td>\n</tr>\n<tr>\n<td>--org</td>\n<td>The name of your organization (e.g. Gruntwork)</td>\n<td>Required</td>\n<td></td>\n</tr>\n<tr>\n<td>--locality</td>\n<td>The locality name (e.g. city or town name) where your organization is located</td>\n<td>Required</td>\n<td></td>\n</tr>\n<tr>\n<td>--state</td>\n<td>The state or province name where your organization is located. Use the full, unabbreviated name. E.g. New Jersey</td>\n<td>Required</td>\n<td></td>\n</tr>\n<tr>\n<td>--country</td>\n<td>The two-letter country name where your organization is located (see https://www.digicert.com/ssl-certificate-country-codes.htm)</td>\n<td>Required</td>\n<td></td>\n</tr>\n<tr>\n<td>--vpn-subnet</td>\n<td>The subnet the vpn clients will be assigned addresses from, in subnet mask format. Eg, "10.1.14.0 255.255.255.0"</td>\n<td>Required</td>\n<td></td>\n</tr>\n<tr>\n<td>--vpn-route</td>\n<td>Routes to subnets that will be protected by the VPN and will be pushed to the VPN clients, in [subnet] [mask] format. Eg, "10.100.0.0 255.255.255.0". Can be specified multiple times.</td>\n<td>Required</td>\n<td></td>\n</tr>\n<tr>\n<td>--key-size</td>\n<td>The key size (in bits) for server and client certificates</td>\n<td>Optional</td>\n<td>4096</td>\n</tr>\n<tr>\n<td>--ca-expiration-days</td>\n<td>The number of days the CA root certificate will be valid for</td>\n<td>Optional</td>\n<td>3650 (10 years)</td>\n</tr>\n<tr>\n<td>--cert-expiration-days</td>\n<td>The number of days a server or user certificate issued by the CA will be valid for</td>\n<td>Optional</td>\n<td>3650 (10 years)</td>\n</tr>\n<tr>\n<td>--crl-expiration-days</td>\n<td>The number of days the CA Certificate Revocation List (CRL) will be valid for</td>\n<td>Optional</td>\n<td>3650 (10 years)</td>\n</tr>\n</tbody>\n</table>\n<h4 id=\"configure-the-open-vpn-package-on-your-ec-2-instances\">Configure the OpenVPN Package on your EC2 Instances</h4>\n<p>In order for the EC2 Instance to run OpenVPN sucessfully, it needs certain data from the EC2 instance.</p>\n<p>When your EC2 Instances are booting up, they should run the <code>init-openvpn</code> script, which will configure\nOpenVPN on your instance.</p>\n<p>The best way to run a script during boot is to put it in <a href=\"http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html#user-data-shell-scripts\" class=\"preview__body--description--blue\" target=\"_blank\">User\nData</a>. Here's an example:</p>\n<pre><span class=\"hljs-comment\">#!/bin/bash</span>\n<span class=\"hljs-keyword\">echo</span> 'Initializing PKI and Copying OpenVPN config into place.<span class=\"hljs-string\">..</span>'\nsudo init-openvpn \\\n <span class=\"hljs-params\">--country</span> <span class=\"hljs-string\">\"US\"</span> \\\n <span class=\"hljs-params\">--state</span> <span class=\"hljs-string\">\"NJ\"</span> \\\n <span class=\"hljs-params\">--locality</span> <span class=\"hljs-string\">\"Marlboro\"</span> \\\n <span class=\"hljs-params\">--org</span> <span class=\"hljs-string\">\"Acme\"</span> \\\n <span class=\"hljs-params\">--org-unit</span> <span class=\"hljs-string\">\"OpenVPN\"</span> \\\n <span class=\"hljs-params\">--email</span> <span class=\"hljs-string\">\"itsupport@acme.none\"</span> \\\n <span class=\"hljs-params\">--s3-bucket-name</span> <span class=\"hljs-string\">\"acme-openvpn-backups\"</span> \\\n <span class=\"hljs-params\">--kms-key-id</span> <span class=\"hljs-string\">\"fd805ce5-2d70-4144-9370-2d9d2ed265fb\"</span> \\\n <span class=\"hljs-params\">--key-size</span> <span class=\"hljs-string\">\"4096\"</span> \\\n <span class=\"hljs-params\">--ca-expiration-days</span> <span class=\"hljs-string\">\"3650\"</span> \\\n <span class=\"hljs-params\">--cert-expiration-days</span> <span class=\"hljs-string\">\"3650\"</span> \\\n <span class=\"hljs-params\">--crl-expiration-days</span> <span class=\"hljs-string\">\"3650\"</span> \\\n <span class=\"hljs-params\">--vpn-subnet</span> <span class=\"hljs-string\">\"10.1.14.0 255.255.255.0\"</span> \\\n <span class=\"hljs-params\">--vpn-route</span> <span class=\"hljs-string\">\"10.100.0.0 255.255.0.0\"</span> \\ \n <span class=\"hljs-params\">--vpn-route</span> <span class=\"hljs-string\">\"10.101.0.0 255.255.0.0\"</span> \\\n <span class=\"hljs-params\">--vpn-route</span> <span class=\"hljs-string\">\"10.102.0.0 255.255.0.0\"</span>\n</pre>\n<h4 id=\"note\">Note</h4>\n<p>The initial generation of PKI is very CPU intensive and can take a long time (30+ minutes), especially on baseline/burst\ntype instances such as the <code>t2</code> family. See <a href=\"http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/t2-instances.html#t2-instances-cpu-credits\" class=\"preview__body--description--blue\" target=\"_blank\">here</a>\nfor additional information.</p>\n","repoName":"package-openvpn","repoRef":"v0.9.9","serviceDescriptor":{"serviceName":"OpenVPN","serviceRepoName":"package-openvpn","serviceRepoOrg":"gruntwork-io","cloudProviders":["aws"],"description":"Deploy an OpenVPN server. Supports auto healing, public key infrastructure (PKI), cert backup, and managing user accounts using IAM groups.","imageUrl":"openvpn.png","licenseType":"subscriber","technologies":["Terraform","Bash","Go"],"compliance":[],"tags":[""]},"serviceCategoryName":"Client VPN access","fileName":"README.md","filePath":"/modules/init-openvpn","title":"Repo Browser: OpenVPN","description":"Browse the repos in the Gruntwork Infrastructure as Code Library."}
.circleci
install.sh
