Repository files navigation

OpenVPN server in a Docker container complete with an EasyRSA PKI CA.Originally this waskylemanna/docker-openvpn with an armhf base image; now that the alpine image in the library works on armhf the difference is largely the first section of this readme.

On a Raspberry Pi 3 I get about 8Mbps up and down.

To install as a service:

docker run -v ovpn-data-mje:/etc/openvpn -d -p 1194:1194/udp --cap-add=NET_ADMIN --name openvpn --restart unless-stopped mjenz/rpi-openvpn

To make clients use local DNS (e.g. so they can resolve local hostnames), edit the config file:

docker run -v $OVPN_DATA:/etc/openvpn --rm -it arm32v6/alpine vi /etc/openvpn/openvpn.conf

and change the the DNS settings to:

push "dhcp-option DNS 192.168.1.1"

The rest of this readme is unchanged from upstream, change "kylemanna/openvpn" to "mjenz/rpi-openvpn" to use the commands.

• Pick a name for the$OVPN_DATA data volume container. It's recommended touse theovpn-data- prefix to operate seamlessly with the reference systemdservice. Users are encourage to replaceexample with a descriptive name oftheir choosing.

    OVPN_DATA="ovpn-data-example"

• Initialize the$OVPN_DATA container that will hold the configuration filesand certificates. The container will prompt for a passphrase to protect theprivate key used by the newly generated certificate authority.

    docker volume create --name $OVPN_DATA  docker run -v $OVPN_DATA:/etc/openvpn --rm kylemanna/openvpn ovpn_genconfig -u udp://VPN.SERVERNAME.COM  docker run -v $OVPN_DATA:/etc/openvpn --rm -it kylemanna/openvpn ovpn_initpki

• Start OpenVPN server process

    docker run -v $OVPN_DATA:/etc/openvpn -d -p 1194:1194/udp --cap-add=NET_ADMIN kylemanna/openvpn

• Generate a client certificate without a passphrase

    docker run -v $OVPN_DATA:/etc/openvpn --rm -it kylemanna/openvpn easyrsa build-client-full CLIENTNAME nopass

• Retrieve the client configuration with embedded certificates

    docker run -v $OVPN_DATA:/etc/openvpn --rm kylemanna/openvpn ovpn_getclient CLIENTNAME > CLIENTNAME.ovpn

Miscellaneous write-ups for advanced configurations are available in thedocs folder.

Asystemd init script is available to manage the OpenVPN container. It willstart the container on system boot, restart the container if it exitsunexpectedly, and pull updates from Docker Hub to keep itself up to date.

Please refer to thesystemd documentation to learn more.

If you prefer to usedocker-compose please refer to thedocumentation.

• Create an environment variable with the name DEBUG and value of 1 to enable debug output (using "docker -e").

    docker run -v $OVPN_DATA:/etc/openvpn -p 1194:1194/udp --privileged -e DEBUG=1 kylemanna/openvpn

• Test using a client that has openvpn installed correctly

    $ openvpn --config CLIENTNAME.ovpn

• Run through a barrage of debugging checks on the client if things don't just work

    $ ping 8.8.8.8    # checks connectivity without touching name resolution  $ dig google.com  # won't use the search directives in resolv.conf  $ nslookup google.com # will use search

• Consider setting up asystemd service for automaticstart-up at boot time and restart in the event the OpenVPN daemon or Dockercrashes.

Initialize the volume container using thekylemanna/openvpn image with theincluded scripts to automatically generate:

• Diffie-Hellman parameters
• a private key
• a self-certificate matching the private key for the OpenVPN server
• an EasyRSA CA key and certificate
• a TLS auth key from HMAC security

The OpenVPN server is started with the default run cmd ofovpn_run

The configuration is located in/etc/openvpn, and the Dockerfiledeclares that directory as a volume. It means that you can start anothercontainer with the-v argument, and access the configuration.The volume also holds the PKI keys and certs so that it could be backed up.

To generate a client certificate,kylemanna/openvpn uses EasyRSA via theeasyrsa command in the container's path. TheEASYRSA_* environmentalvariables place the PKI CA under/etc/openvpn/pki.

Conveniently,kylemanna/openvpn comes with a script calledovpn_getclient,which dumps an inline OpenVPN client configuration file. This single file canthen be given to a client for access to the VPN.

To enable Two Factor Authentication for clients (a.k.a. OTP) seethis document.

We usetun mode, because it works on the widest range of devices.tap mode, for instance, does not work on Android, except if the deviceis rooted.

The topology used isnet30, because it works on the widest range of OS.p2p, for instance, does not work on Windows.

The UDP server uses192.168.255.0/24 for dynamic clients by default.

The client profile specifiesredirect-gateway def1, meaning that afterestablishing the VPN connection, all traffic will go through the VPN.This might cause problems if you use local DNS recursors which are notdirectly reachable, since you will try to reach them through the VPNand they might not answer to you. If that happens, use public DNSresolvers like those of Google (8.8.4.4 and 8.8.8.8) or OpenDNS(208.67.222.222 and 208.67.220.220).

The Docker container runs its own EasyRSA PKI Certificate Authority. This waschosen as a good way to compromise on security and convenience. The containerruns under the assumption that the OpenVPN container is running on a securehost, that is to say that an adversary does not have access to the PKI filesunder/etc/openvpn/pki. This is a fairly reasonable compromise because if anadversary had access to these files, the adversary could manipulate thefunction of the OpenVPN server itself (sniff packets, create a new PKI CA, MITMpackets, etc).

• The certificate authority key is kept in the container by default forsimplicity. It's highly recommended to secure the CA key with somepassphrase to protect against a filesystem compromise. A more secure systemwould put the EasyRSA PKI CA on an offline system (can use the same Dockerimage and the scriptovpn_copy_server_files to accomplish this).
• It would be impossible for an adversary to sign bad or forged certificateswithout first cracking the key's passphase should the adversary have rootaccess to the filesystem.
• The EasyRSAbuild-client-full command will generate and leave keys on theserver, again possible to compromise and steal the keys. The keys generatedneed to be signed by the CA which the user hopefully configured with a passphraseas described above.
• Assuming the rest of the Docker container's filesystem is secure, TLS + PKIsecurity should prevent any malicious host from using the VPN.

This means that it will function correctly (after Docker itself is setup) onall distributions Linux distributions such as: Ubuntu, Arch, Debian, Fedora,etc. Furthermore, an old stable server can run a bleeding edge OpenVPN serverwithout having to install/muck with library dependencies (i.e. run latestOpenVPN with latest OpenSSL on Ubuntu 12.04 LTS).

Everything for the Docker container is contained in two images: the ephemeralrun time image (kylemanna/openvpn) and the$OVPN_DATA data volume. To removeit, remove the corresponding containers,$OVPN_DATA data volume and Dockerimage and it's completely removed. This also makes it easier to run multipleservers since each lives in the bubble of the container (of course multiple IPsor separate ports are needed to communicate with the world).

At the simplest level compromising the container may prevent additionalcompromise of the server. There are many arguments surrounding this, but thetake away is that it certainly makes it more difficult to break out of thecontainer. People are actively working on Linux containers to make this moreof a guarantee in the future.

• No longer uses serveconfig to distribute the configuration via https
• Proper PKI support integrated into image
• OpenVPN config files, PKI keys and certs are stored on a storagevolume for re-use across containers
• Addition of tls-auth for HMAC security

• Docker hosts:
  • server aDigital Ocean Droplet with 512 MB RAM running Ubuntu 14.04
• Clients
  • Android App OpenVPN Connect 1.1.14 (built 56)
    • OpenVPN core 3.0 android armv7a thumb2 32-bit
  • OS X Mavericks with Tunnelblick 3.4beta26 (build 3828) using openvpn-2.3.4
  • ArchLinux OpenVPN pkg 2.3.4-1