OpenVPN for Docker
OpenVPN server in a Docker container complete with an EasyRSA PKI CA.
Extensively tested on Digital Ocean.
$OVPN_DATAvolume container, i.e.
docker run --name $OVPN_DATA -v /etc/openvpn busybox
$OVPN_DATAcontainer that will hold the configuration files and certificates
docker run --volumes-from $OVPN_DATA --rm kylemanna/openvpn ovpn_genconfig -u udp://VPN.SERVERNAME.COM:1194 docker run --volumes-from $OVPN_DATA --rm -it kylemanna/openvpn ovpn_initpki
Start OpenVPN server process
On Docker version 1.2 and newer
docker run --volumes-from $OVPN_DATA -d -p 1194:1194/udp --cap-add=NET_ADMIN kylemanna/openvpn
On Docker older than 1.2 version
docker run --volumes-from $OVPN_DATA -d -p 1194:1194/udp --privileged kylemanna/openvpn
Generate a client certificate without a passphrase
docker run --volumes-from $OVPN_DATA --rm -it kylemanna/openvpn easyrsa build-client-full CLIENTNAME nopass
Retrieve the client configuration with embedded certificates
docker run --volumes-from $OVPN_DATA --rm kylemanna/openvpn ovpn_getclient CLIENTNAME > CLIENTNAME.ovpn
How Does It Work?
Initialize the volume container using the
kylemanna/openvpn image with the
included 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 of
The configuration is located in
/etc/openvpn, and the Dockerfile
declares that directory as a volume. It means that you can start another
container with the
--volumes-from flag, 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 the
easyrsa command in the container's path. The
variables place the PKI CA under
kylemanna/openvpn comes with a script called
which dumps an inline OpenVPN client configuration file. This single file can
then be given to a client for access to the VPN.
tun mode, because it works on the widest range of devices.
tap mode, for instance, does not work on Android, except if the device
The topology used is
net30, because it works on the widest range of OS.
p2p, for instance, does not work on Windows.
The UDP server uses
192.168.255.0/24 for dynamic clients by default.
The client profile specifies
redirect-gateway def1, meaning that after
establishing the VPN connection, all traffic will go through the VPN.
This might cause problems if you use local DNS recursors which are not
directly reachable, since you will try to reach them through the VPN
and they might not answer to you. If that happens, use public DNS
resolvers like those of Google (184.108.40.206 and 220.127.116.11) or OpenDNS
(18.104.22.168 and 22.214.171.124).
The Docker container runs its own EasyRSA PKI Certificate Authority. This was
chosen as a good way to compromise on security and convenience. The container
runs under the assumption that the OpenVPN container is running on a secure
host, that is to say that an adversary does not have access to the PKI files
/etc/openvpn/pki. This is a fairly reasonable compromise because if an
adversary had access to these files, the adversary could manipulate the
function of the OpenVPN server itself (sniff packets, create a new PKI CA, MITM
- The certificate authority key is kept in the container by default for
simplicity. It's highly recommended to secure the CA key with some
passphrase to protect against a filesystem compromise. A more secure system
would put the EasyRSA PKI CA on an offline system (can use the same Docker
image to accomplish this).
- It would be impossible for an adversary to sign bad or forged certificates
without first cracking the key's passphase should the adversary have root
access to the filesystem.
- The EasyRSA
build-client-fullcommand will generate and leave keys on the
server, again possible to compromise and steal the keys. The keys generated
need to signed by the CA which the user hopefully configured with a passphrase
as described above.
- Assuming the rest of the Docker container's filesystem is secure, TLS + PKI
security should prevent any malicious host from using the VPN.
Differences from jpetazzo/dockvpn
- 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 storage
volume for re-use across containers
- Only offer UDP support for now, I don't have a good use case for TCP
- Addition of tls-auth for HMAC security
- Docker hosts:
- server a Digital Ocean Droplet with 512 MB RAM running Ubuntu 14.04
- 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
- Android App OpenVPN Connect 1.1.14 (built 56)