Public | Automated Build

Last pushed: a year ago
Short Description
Fork of Kyle Manna's openvpn container
Full Description

OpenVPN for Docker

OpenVPN server in a Docker container complete with an EasyRSA PKI CA.

Forked from kylamanna/openvpn, so as to maintain a local copy for my use.

Upstream Links

Quick Start

  • Create a directory to house your configuration data & certificates. In my
    case, I used /var/docks/openvpn. Feel free to stash the bits somewhere
    else if you'd prefer.

  • Fire up the container a couple of times to generate the configuration,
    and to create the relevant certificates you'll make use of.

      docker run \
          -v /var/docks/openvpn:/etc/openvpn
          --rm \
          jcostom/openvpn \
          ovpn_genconfig -u udp://VPN.SERVERNAME.COM
      docker run \
          -v /var/docks/openvpn:/etc/openvpn \
          --rm -it \
          jcostom/openvpn \
  • Start OpenVPN server process

      docker run \
          --restart=always \
          --name=openvpn \
          -v /var/docks/openvpn:/etc/openvpn -d \
          -p 1194:1194/udp \
          --cap-add=NET_ADMIN \
  • Generate a client certificate without a passphrase

      docker run \
          -v /var/docks/openvpn:/etc/openvpn \
          --rm -it \
          easyrsa build-client-full \
          CLIENTNAME nopass
  • Retrieve the client configuration with embedded certificates

      docker run
          -v /var/docks/openvpn:/etc/openvpn -
          -rm jcostom/openvpn \
          ovpn_getclient \

Next Steps

More Reading

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

Systemd Init Scripts

A systemd init script is available to manage the OpenVPN container. It will
start the container on system boot, restart the container if it exits
unexpectedly, and pull updates from Docker Hub to keep itself up to date.

Please refer to the systemd documentation to learn more.

Docker Compose

If you prefer to use docker-compose please refer to the documentation.

Debugging Tips

  • 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 jcostom/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    # checks connectivity without touching name resolution
      $ dig  # won't use the search directives in resolv.conf
      $ nslookup # will use search
  • Consider setting up a systemd service for automatic
    start-up at boot time and restart in the event the OpenVPN daemon or Docker

How Does It Work?

Initialize the volume container using the jcostom/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 ovpn_run

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 -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, jcostom/openvpn uses EasyRSA via the
easyrsa command in the container's path. The EASYRSA_* environmental
variables place the PKI CA under /etc/openvpn/pki.

Conveniently, jcostom/openvpn comes with a script called ovpn_getclient,
which dumps an inline OpenVPN client configuration file. This single file can
then be given to a client for access to the VPN.

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

OpenVPN Details

We use tun mode, because it works on the widest range of devices.
tap mode, for instance, does not work on Android, except if the device
is rooted.

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 uses192.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 ( and or OpenDNS
( and

Docker Pull Command
Source Repository