{"id":13464944,"url":"https://github.com/kylemanna/docker-openvpn","last_synced_at":"2025-04-29T21:25:51.469Z","repository":{"id":17664165,"uuid":"20468810","full_name":"kylemanna/docker-openvpn","owner":"kylemanna","description":"🔒 OpenVPN server in a Docker container complete with an EasyRSA PKI CA","archived":false,"fork":false,"pushed_at":"2024-03-03T09:59:37.000Z","size":385,"stargazers_count":8905,"open_issues_count":306,"forks_count":2416,"subscribers_count":156,"default_branch":"master","last_synced_at":"2025-04-10T15:56:16.115Z","etag":null,"topics":["docker","docker-container","docker-openvpn","easyrsa-pki","openvpn","openvpn-server","pki"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/kylemanna/openvpn/","language":"Shell","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/kylemanna.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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":"2014-06-04T03:26:38.000Z","updated_at":"2025-04-09T04:51:17.000Z","dependencies_parsed_at":"2023-02-19T01:45:48.783Z","dependency_job_id":"9ae8cd46-2907-4e5f-a1dd-1b017188a0eb","html_url":"https://github.com/kylemanna/docker-openvpn","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylemanna%2Fdocker-openvpn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylemanna%2Fdocker-openvpn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylemanna%2Fdocker-openvpn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylemanna%2Fdocker-openvpn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kylemanna","download_url":"https://codeload.github.com/kylemanna/docker-openvpn/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251362144,"owners_count":21577400,"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":["docker","docker-container","docker-openvpn","easyrsa-pki","openvpn","openvpn-server","pki"],"created_at":"2024-07-31T14:00:53.196Z","updated_at":"2025-04-28T18:01:26.424Z","avatar_url":"https://github.com/kylemanna.png","language":"Shell","readme":"# OpenVPN for Docker\n\n[![Build Status](https://travis-ci.org/kylemanna/docker-openvpn.svg)](https://travis-ci.org/kylemanna/docker-openvpn)\n[![Docker Stars](https://img.shields.io/docker/stars/kylemanna/openvpn.svg)](https://hub.docker.com/r/kylemanna/openvpn/)\n[![Docker Pulls](https://img.shields.io/docker/pulls/kylemanna/openvpn.svg)](https://hub.docker.com/r/kylemanna/openvpn/)\n[![ImageLayers](https://images.microbadger.com/badges/image/kylemanna/openvpn.svg)](https://microbadger.com/#/images/kylemanna/openvpn)\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fkylemanna%2Fdocker-openvpn.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fkylemanna%2Fdocker-openvpn?ref=badge_shield)\n\n\nOpenVPN server in a Docker container complete with an EasyRSA PKI CA.\n\nExtensively tested on [Digital Ocean $5/mo node](http://bit.ly/1C7cKr3) and has\na corresponding [Digital Ocean Community Tutorial](http://bit.ly/1AGUZkq).\n\n#### Upstream Links\n\n* Docker Registry @ [kylemanna/openvpn](https://hub.docker.com/r/kylemanna/openvpn/)\n* GitHub @ [kylemanna/docker-openvpn](https://github.com/kylemanna/docker-openvpn)\n\n## Quick Start\n\n* Pick a name for the `$OVPN_DATA` data volume container. It's recommended to\n  use the `ovpn-data-` prefix to operate seamlessly with the reference systemd\n  service.  Users are encourage to replace `example` with a descriptive name of\n  their choosing.\n\n      OVPN_DATA=\"ovpn-data-example\"\n\n* Initialize the `$OVPN_DATA` container that will hold the configuration files\n  and certificates.  The container will prompt for a passphrase to protect the\n  private key used by the newly generated certificate authority.\n\n      docker volume create --name $OVPN_DATA\n      docker run -v $OVPN_DATA:/etc/openvpn --rm kylemanna/openvpn ovpn_genconfig -u udp://VPN.SERVERNAME.COM\n      docker run -v $OVPN_DATA:/etc/openvpn --rm -it kylemanna/openvpn ovpn_initpki\n\n* Start OpenVPN server process\n\n      docker run -v $OVPN_DATA:/etc/openvpn -d -p 1194:1194/udp --cap-add=NET_ADMIN kylemanna/openvpn\n\n* Generate a client certificate without a passphrase\n\n      docker run -v $OVPN_DATA:/etc/openvpn --rm -it kylemanna/openvpn easyrsa build-client-full CLIENTNAME nopass\n\n* Retrieve the client configuration with embedded certificates\n\n      docker run -v $OVPN_DATA:/etc/openvpn --rm kylemanna/openvpn ovpn_getclient CLIENTNAME \u003e CLIENTNAME.ovpn\n\n## Next Steps\n\n### More Reading\n\nMiscellaneous write-ups for advanced configurations are available in the\n[docs](docs) folder.\n\n### Systemd Init Scripts\n\nA `systemd` init script is available to manage the OpenVPN container.  It will\nstart the container on system boot, restart the container if it exits\nunexpectedly, and pull updates from Docker Hub to keep itself up to date.\n\nPlease refer to the [systemd documentation](docs/systemd.md) to learn more.\n\n### Docker Compose\n\nIf you prefer to use `docker-compose` please refer to the [documentation](docs/docker-compose.md).\n\n## Debugging Tips\n\n* Create an environment variable with the name DEBUG and value of 1 to enable debug output (using \"docker -e\").\n\n        docker run -v $OVPN_DATA:/etc/openvpn -p 1194:1194/udp --cap-add=NET_ADMIN -e DEBUG=1 kylemanna/openvpn\n\n* Test using a client that has openvpn installed correctly\n\n        $ openvpn --config CLIENTNAME.ovpn\n\n* Run through a barrage of debugging checks on the client if things don't just work\n\n        $ ping 8.8.8.8    # checks connectivity without touching name resolution\n        $ dig google.com  # won't use the search directives in resolv.conf\n        $ nslookup google.com # will use search\n\n* Consider setting up a [systemd service](/docs/systemd.md) for automatic\n  start-up at boot time and restart in the event the OpenVPN daemon or Docker\n  crashes.\n\n## How Does It Work?\n\nInitialize the volume container using the `kylemanna/openvpn` image with the\nincluded scripts to automatically generate:\n\n- Diffie-Hellman parameters\n- a private key\n- a self-certificate matching the private key for the OpenVPN server\n- an EasyRSA CA key and certificate\n- a TLS auth key from HMAC security\n\nThe OpenVPN server is started with the default run cmd of `ovpn_run`\n\nThe configuration is located in `/etc/openvpn`, and the Dockerfile\ndeclares that directory as a volume. It means that you can start another\ncontainer with the `-v` argument, and access the configuration.\nThe volume also holds the PKI keys and certs so that it could be backed up.\n\nTo generate a client certificate, `kylemanna/openvpn` uses EasyRSA via the\n`easyrsa` command in the container's path.  The `EASYRSA_*` environmental\nvariables place the PKI CA under `/etc/openvpn/pki`.\n\nConveniently, `kylemanna/openvpn` comes with a script called `ovpn_getclient`,\nwhich dumps an inline OpenVPN client configuration file.  This single file can\nthen be given to a client for access to the VPN.\n\nTo enable Two Factor Authentication for clients (a.k.a. OTP) see [this document](/docs/otp.md).\n\n## OpenVPN Details\n\nWe use `tun` mode, because it works on the widest range of devices.\n`tap` mode, for instance, does not work on Android, except if the device\nis rooted.\n\nThe topology used is `net30`, because it works on the widest range of OS.\n`p2p`, for instance, does not work on Windows.\n\nThe UDP server uses`192.168.255.0/24` for dynamic clients by default.\n\nThe client profile specifies `redirect-gateway def1`, meaning that after\nestablishing the VPN connection, all traffic will go through the VPN.\nThis might cause problems if you use local DNS recursors which are not\ndirectly reachable, since you will try to reach them through the VPN\nand they might not answer to you. If that happens, use public DNS\nresolvers like those of Google (8.8.4.4 and 8.8.8.8) or OpenDNS\n(208.67.222.222 and 208.67.220.220).\n\n\n## Security Discussion\n\nThe Docker container runs its own EasyRSA PKI Certificate Authority.  This was\nchosen as a good way to compromise on security and convenience.  The container\nruns under the assumption that the OpenVPN container is running on a secure\nhost, that is to say that an adversary does not have access to the PKI files\nunder `/etc/openvpn/pki`.  This is a fairly reasonable compromise because if an\nadversary had access to these files, the adversary could manipulate the\nfunction of the OpenVPN server itself (sniff packets, create a new PKI CA, MITM\npackets, etc).\n\n* The certificate authority key is kept in the container by default for\n  simplicity.  It's highly recommended to secure the CA key with some\n  passphrase to protect against a filesystem compromise.  A more secure system\n  would put the EasyRSA PKI CA on an offline system (can use the same Docker\n  image and the script [`ovpn_copy_server_files`](/docs/paranoid.md) to accomplish this).\n* It would be impossible for an adversary to sign bad or forged certificates\n  without first cracking the key's passphase should the adversary have root\n  access to the filesystem.\n* The EasyRSA `build-client-full` command will generate and leave keys on the\n  server, again possible to compromise and steal the keys.  The keys generated\n  need to be signed by the CA which the user hopefully configured with a passphrase\n  as described above.\n* Assuming the rest of the Docker container's filesystem is secure, TLS + PKI\n  security should prevent any malicious host from using the VPN.\n\n\n## Benefits of Running Inside a Docker Container\n\n### The Entire Daemon and Dependencies are in the Docker Image\n\nThis means that it will function correctly (after Docker itself is setup) on\nall distributions Linux distributions such as: Ubuntu, Arch, Debian, Fedora,\netc.  Furthermore, an old stable server can run a bleeding edge OpenVPN server\nwithout having to install/muck with library dependencies (i.e. run latest\nOpenVPN with latest OpenSSL on Ubuntu 12.04 LTS).\n\n### It Doesn't Stomp All Over the Server's Filesystem\n\nEverything for the Docker container is contained in two images: the ephemeral\nrun time image (kylemanna/openvpn) and the `$OVPN_DATA` data volume. To remove\nit, remove the corresponding containers, `$OVPN_DATA` data volume and Docker\nimage and it's completely removed.  This also makes it easier to run multiple\nservers since each lives in the bubble of the container (of course multiple IPs\nor separate ports are needed to communicate with the world).\n\n### Some (arguable) Security Benefits\n\nAt the simplest level compromising the container may prevent additional\ncompromise of the server.  There are many arguments surrounding this, but the\ntake away is that it certainly makes it more difficult to break out of the\ncontainer.  People are actively working on Linux containers to make this more\nof a guarantee in the future.\n\n## Differences from jpetazzo/dockvpn\n\n* No longer uses serveconfig to distribute the configuration via https\n* Proper PKI support integrated into image\n* OpenVPN config files, PKI keys and certs are stored on a storage\n  volume for re-use across containers\n* Addition of tls-auth for HMAC security\n\n## Originally Tested On\n\n* Docker hosts:\n  * server a [Digital Ocean](https://www.digitalocean.com/?refcode=d19f7fe88c94) Droplet with 512 MB RAM running Ubuntu 14.04\n* Clients\n  * Android App OpenVPN Connect 1.1.14 (built 56)\n     * OpenVPN core 3.0 android armv7a thumb2 32-bit\n  * OS X Mavericks with Tunnelblick 3.4beta26 (build 3828) using openvpn-2.3.4\n  * ArchLinux OpenVPN pkg 2.3.4-1\n\n\n## License\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fkylemanna%2Fdocker-openvpn.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fkylemanna%2Fdocker-openvpn?ref=badge_large)\n","funding_links":[],"categories":["Shell","docker","CLI tools","Security"],"sub_categories":["Networking"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkylemanna%2Fdocker-openvpn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkylemanna%2Fdocker-openvpn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkylemanna%2Fdocker-openvpn/lists"}