hbaier/openvpn repository overview

⁠Quick reference

• Maintained by: Harald Baier⁠

• Where to get help: OpenVPN man page⁠, Easy-RSA documentation⁠, or Stack Overflow⁠

• Supported architectures: (more info⁠)
  386, amd64, arm/v6, arm/v7, arm64, ppc64le, s390x

⁠Supported tags and respective Dockerfile links

• 1.0.0, 1.0, 1, latest⁠

⁠What is OpenVPN?

OpenVPN is an open-source platform independent software that implements virtual private network⁠ (VPN) techniques to create secure connections and remote access facilities. It uses SSL/TLS⁠ for key exchange and is capable of traversing network address translation⁠ (NAT) and firewalls.

⁠How to manage client certificates?

Easy-RSA, a CLI utility to build and manage a PKI⁠ CA, is integrated in the image. Therefore, you are able to generate and renew client certificates. You can still revoke certificates and publish certificate revocation lists⁠ (CRL).

⁠Architectures other than amd64?

When running from Docker Hub repository, Docker will automatically select an image variant which matches your OS and architecture. Currently 386, amd64, arm/v6, arm/v7, arm64, ppc64le and s390x are supported.

⁠Usage

Start the server in the background:

$ docker run -d --rm \
             --name openvpn \
             -e EASYRSA_ALGO=ec \
             -e OPENVPN_OPTIONS_CUSTOM="--management localhost 7505" \
             -e OPENVPN_PUSH_ROUTE="192.168.1.0/24 192.168.2.0/24 192.168.178.0/24" \
             -e OPENVPN_REMOTE_HOST=vpn.example.net \
             --cap-add=NET_ADMIN \
             -p 1194:1194/udp \
             -v $PWD/openvpn-data:/etc/openvpn \
             hbaier/openvpn

Example Compose file⁠:

version: "3"
services:
  openvpn:
    image: hbaier/openvpn
    container_name: openvpn
    environment:
      EASYRSA_ALGO: ec
      OPENVPN_OPTIONS_CUSTOM: "--management localhost 7505"
      OPENVPN_PUSH_ROUTE: "192.168.1.0/24 192.168.2.0/24 192.168.178.0/24"
      OPENVPN_REMOTE_HOST: vpn.example.net
    cap_add:
      - NET_ADMIN
    ports:
      - "1194:1194/udp"
    volumes:
      - openvpn:/etc/openvpn
    restart: unless-stopped
volumes:
  openvpn:
    driver: "local"

Generate client certificate and key without password:

$ docker exec -it openvpn easyrsa build-client-full <filename_base> nopass

Saving an ovpn client configuration file (with inline files) into the Docker host filesystem:

$ docker exec -it openvpn ovpn --print <filename_base> > <filename_base>.ovpn

Renew a client certificate that will expire soon:

$ docker exec -it openvpn easyrsa renew <filename_base>

Revoke client certificate and publish CRL:

$ docker exec -it openvpn easyrsa revoke <filename_base>
$ docker exec -it openvpn easyrsa gen-crl

Print an overview of all (valid and revoked) certificates of the PKI:

$ docker exec -it openvpn sh -c 'cat ${EASYRSA_PKI}/index.txt'

Print an overview of all connected clients:

$ docker exec -it openvpn cat /var/log/openvpn/status.log

Connect to the OpenVPN management interface:

$ docker exec -it openvpn nc localhost 7505

Note that the management interface isn't enabled by default. For more information please have a look at the possibilities of the environment variable OPENVPN_OPTIONS_CUSTOM.

⁠Environment variables

When you start the openvpn image, you can adjust the configuration of the OpenVPN server instance by passing one or more environment variables on the docker run command line.

⁠EASYRSA_ALGO

Set the crypto algorithm you want to use. Possible values are rsa and ec. The default value is rsa; ec can enable elliptic curve⁠ support.

⁠EASYRSA_CA_EXPIRE

Set the CA expiration time in days. The default value is 3650.

⁠EASYRSA_CERT_EXPIRE

Set the issued cert expiration time in days. The default value is 1080.

⁠EASYRSA_CERT_RENEW

Defines how many days before its expiration date a certificate is allowed to be renewed. The default value is 30.

⁠EASYRSA_CRL_DAYS

Set the CRL⁠ next publish time in days. The default value is 180.

⁠EASYRSA_CURVE

Defines the named elliptic curve⁠ (EC) which is used. The default value is secp521r1.

⁠EASYRSA_DN

The variable allows you to define the X.509⁠ DN mode. This is used to adjust which elements are included in the Subject field as the Distinguished Name (DN). Possible values are cn_only (use just a Common Name (CN) value) and org(use the traditional Country/Province/City/Org/OU/email/CN format). The default value is cn_only. Note that in cn_only mode the Organizational fields EASYRSA_REQ_CITY, EASYRSA_REQ_COUNTRY, EASYRSA_REQ_EMAIL, EASYRSA_REQ_ORG, EASYRSA_REQ_OU and EASYRSA_REQ_PROVINCE aren't used.

⁠EASYRSA_KEY_SIZE

Set the keysize in bits to generate keypairs. The default value is 4096. Larger keysizes will slow down TLS negotiation and make key or Diffie-Hellman⁠ parameter generation take much longer. Only used when the crypto algorithm is rsa.

⁠EASYRSA_REQ_CITY

Defines the Organizational field city/locality (used with org mode and ignored in cn_only mode).

⁠EASYRSA_REQ_COUNTRY

Defines the Organizational field country (used with org mode and ignored in cn_only mode).

⁠EASYRSA_REQ_EMAIL

Defines the Organizational field email (used with org mode and ignored in cn_only mode).

⁠EASYRSA_REQ_ORG

Defines the organization (used with org mode and ignored in cn_only mode).

⁠EASYRSA_REQ_OU

Defines the organizational unit (used with org mode and ignored in cn_only mode).

⁠EASYRSA_REQ_PROVINCE

Defines the Organizational field state/province (used with org mode and ignored in cn_only mode).

⁠OPENVPN_AUTH

This variable allows you to specify the message digest algorithm for data channel and/or control channel packets authentication. The default value is SHA512.

⁠OPENVPN_CIPHER

Defines the cipher algorithm for data channel encryption. The default value is AES-256-GCM.

⁠OPENVPN_COMPRESS

Defines the compression algorithm. Possible values are lz4, lz4-v2 and lzo. If this variable is empty (default and recommended value because of security reasons), compression will be turned off.

⁠OPENVPN_DEV

Defines the virtual network device. The default value is tun.

⁠OPENVPN_HOME

Defines the location of the OpenVPN home directory. The default value is /etc/openvpn.

⁠OPENVPN_KEEPALIVE_INTERVAL

Defines the keepalive interval on both client and server side. The default value is 10.

⁠OPENVPN_KEEPALIVE_TIMEOUT

Defines the keepalive timeout on both client and server side. The default value is 120. This argument will be twice as long on the server side.

⁠OPENVPN_MAX_CLIENTS

This variable limits the OpenVPN server to a maximum amount of concurrent clients. The default value is 1024.

⁠OPENVPN_MUTE

This variable is used to limit repetitive logging of similar message types. The default value is 0.

⁠OPENVPN_NCP_CIPHERS

Restrict the allowed ciphers to be negotiated to the ciphers in colon-separated list of ciphers. The default value is AES-256-GCM:AES-256-CBC.

⁠OPENVPN_OPTIONS_CUSTOM

This variable is used to define additional command line options to the OpenVPN server configuration. For example --management localhost 7505 enables a management interface on the desired TCP port. For more information on OpenVPN command line options please visit the OpenVPN man page⁠.

⁠OPENVPN_PROTO

Defines the network protocol for both local and remote. Possible values are tcp and udp. The default value is udp.

⁠OPENVPN_PUSH_ROUTE

Defines routes that will be pushed to the client. This variable must be specified as space separated networks in CIDR⁠ notation. For example 192.168.1.0/24 192.168.2.0/24 192.168.178.0/24 is a valid content. By default, no route is specified.

⁠OPENVPN_REMOTE_HOST

Defines the hostname or IP address that the OpenVPN client will try to connect to the server.

⁠OPENVPN_REMOTE_PORT

Defines the port number that the OpenVPN client will try to connect to the server. The default value is 1194. Note that the OpenVPN server inside the Docker container will always listen on port 1194. You can use the --publish or -p flag from the docker run command which can map the container port to another port on the Docker host.

⁠OPENVPN_SERVER

Defines the network range in which the OpenVPN server will allocate addresses to clients. Unlike the OpenVPN option --server this variable must be specified in the CIDR⁠ notation. The default value is 10.8.0.0/24.

⁠OPENVPN_TLS_VERSION_MIN

This variable allows you to specify the minimum TLS version accepted. The default value is 1.2.

⁠OPENVPN_TOPOLOGY

Configure virtual addressing topology when running in dev tun mode. This directive has no meaning in dev tap mode, which always uses a subnet topology. Possible values are net30, p2p or subnet. The default value is subnet.

⁠OPENVPN_VERB

This variable allows you to specify the output verbosity. Possible values are between 0 and 11. Each level shows all info from the previous levels. Level 0 means no output except fatal errors. Level 3 is recommended if you want a good summary of what's happening without being swamped by output. The default value is 3.

⁠Known issues

• Currently only Point-to-Site VPN connections in routed configurations are supported. Site-to-Site connections using dev tap and ethernet bridging mode may be included in later releases.