rmasp98/openvpn-rpi repository overview

⁠OpenVPN for Docker

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

Extensively tested on Digital Ocean $5/mo node⁠ and has a corresponding Digital Ocean Community Tutorial⁠.

⁠Upstream Links

• Docker Registry @ rmasp98/openvpn-rpi⁠
• GitHub @ rmasp98/docker-openvpn⁠

⁠Quick Start

• Pick a name for the $OVPN_DATA data volume container. It's recommended to use the ovpn-data- prefix to operate seamlessly with the reference systemd service. Users are encourage to replace example with a descriptive name of their choosing.

  OVPN_DATA="ovpn-data-example"
  

  Copy

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

  docker volume create --name $OVPN_DATA
  docker run -v $OVPN_DATA:/etc/openvpn --log-driver=none --rm rmasp98/openvpn-rpi ovpn_genconfig -u udp://VPN.SERVERNAME.COM
  docker run -v $OVPN_DATA:/etc/openvpn --log-driver=none --rm -it rmasp98/openvpn-rpi ovpn_initpki
  

  Copy

• Start OpenVPN server process

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

  Copy

• Generate a client certificate without a passphrase

  docker run -v $OVPN_DATA:/etc/openvpn --log-driver=none --rm -it rmasp98/openvpn-rpi easyrsa build-client-full CLIENTNAME nopass
  

  Copy

• Retrieve the client configuration with embedded certificates

  docker run -v $OVPN_DATA:/etc/openvpn --log-driver=none --rm rmasp98/openvpn-rpi ovpn_getclient CLIENTNAME > CLIENTNAME.ovpn
  

  Copy

⁠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 rmasp98/openvpn-rpi
  

  Copy

• Test using a client that has openvpn installed correctly

    $ openvpn --config CLIENTNAME.ovpn
  

  Copy

• 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
  

  Copy

• Consider setting up a systemd service⁠ for automatic start-up at boot time and restart in the event the OpenVPN daemon or Docker crashes.

⁠How Does It Work?

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

Conveniently, rmasp98/openvpn-rpi 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 (8.8.4.4 and 8.8.8.8) or OpenDNS (208.67.222.222 and 208.67.220.220).