Skip to main content

Official Docker VPN Server with Access Server | OpenVPN

This guide walks you through launching Access Server in a Docker container.

Docker is a tool that a sysadmin can use to deploy an application in a sandbox, called a container, to run on a host operating system. Using a Docker container has a lower overhead than a virtual machine.

Access Server gives you the following benefits:

Prerequisites

Before you can proceed with the steps here, ensure you have the following on your preferred host system:

  • Docker Engine installed.

    Note

    We recommend using Docker CE for headless Linux environments. For desktop (GUI) environments, Docker Desktop is available on Windows, macOS, or Linux.

  • A public IP address or domain name pointed to the public IP address.

Tip

We recommend you review the Access Server hardware requirements as well.

Follow the next sections to run Docker commands from the terminal.

Important

You can run an Access Server on a Docker container with a self-hosted server, but not all cloud providers grant admin privileges to their services. On a self-hosted server, the Docker container requires specific privileges to interact with the network stack. To ensure proper functionality, use the following options:

  • --cap-add=NET_ADMIN — Grants the container the necessary network administration capabilities.

  • --cap-add=MKNOD — Allows the container to create device nodes.

  • --device /dev/net/tun — Provides access to the TUN device for VPN traffic.

Refer to the section below for other limitations and known issues when running Access Server in a Docker container.

Add Access Server image to your system

The first step is to add the Access Server image to your system.

  1. Run the following in the terminal:

    docker pull openvpn/openvpn-as

    Tip

    If you see a permission denied error, prefix your commands with sudo on Linux, or create a docker group to resolve the issue.

    • The pull command gets the openvpn-as image from the Docker registry and saves it to your system.

  2. If you want to see all the images on your system, use the docker images command.

    % docker images
REPOSITORY         TAG        IMAGE ID        CREATED       SIZE
openvpn/openvpn-as latest     22785eb5796a    12 days ago   657MB

Run the Docker container

Now you can run a Docker container based on the openvpn-as image.

  • Run the Docker container based on the Access Server image with these parameters:

    • The Docker client loads the openvpn/openvpn-as image in a container. You can see the running container in the Docker Desktop app or with the command docker ps.

Tip

If you want to set the container to start automatically, you can include the --restart parameter in your docker run command. For details about the flags available for that parameter, refer to Docker's documentation, Start containers automatically.

Sign in to the Admin Web UI

You've installed Access Server, and the container is running. You can now sign in to the Admin Web UI, a web-based GUI for managing your VPN server, with or without Linux knowledge.

The Admin Web UI is available at https://DOCKER-HOST-IP:943/admin.

Find the temporary password

The default user is openvpn and you can find the temporary password created with the initial Access Server configuration in the container logs:

  1. With the container running, display the logs with this command:

    docker logs -f openvpn-as

    • The Access Server Initial Configuration Tool output displays.

  2. Scroll to find the line, Auto-generated pass = "<password>". Setting in db...

  3. Use the generated password with the openvpn username to sign in to the Admin Web UI.

Sign in as an administrator

To access and sign in to the Admin Web UI:

  1. Open a web browser.

  2. Enter the Admin Web UI URL, available at https://DOCKER-HOST-IP:943/admin.

    • A security warning displays. Access Server uses a self-signed SSL certificate. We recommend replacing it with a signed certificate. Refer to SSL Certificates.

    Important

    Ensure you use https in the URL.

  3. Click through the security warning.

    • The Admin Login displays.

  4. Enter the openvpn username with the temporary password and click Sign In.

    • The EULA displays for you to read through, accept, and proceed to the Admin Web UI configuration pages.

Update the IP address/hostname

For your devices to properly connect to your VPN server, you need to update the domain or public IP address:

  1. Sign in to the Admin Web UI.

  2. Click Configuration > Network Settings.

  3. Change the Hostname or IP Address field to a public IP address or your domain name.

    Note

    Access Server likely has a private IP address populated in this field. Clients need a public IP to access from outside the network, or a domain name mapped with an A record. We recommend using a domain name.

Limitations and known issues

The following are known issues or limitations if you deploy Access Server from a Docker image:

  • Failover mode: This feature isn't supported.

  • Layer 2 (bridging): This mode isn't supported.

  • Fixed license keys: This license key model isn't supported. Using fixed keys can cause license invalidation because the hardware specification fingerprint isn't persistent.

  • DCO: You can enable DCO with Access Server if you install and load it on the host Linux system.

  • Clustering: You can use Access Servers, deployed from Docker images, to build cluster functionality with the following limitations:

    • You must expose port TCP945 for internode communication.

    • You can only run one cluster node per Host system at a time.

    • Hosts must be available directly from the internet, not via a load balancer, proxy, or ingress controller.

  • Performance: The additional abstraction layer can cause performance degradation and increase latency. We don't recommend deploying highly loaded installations using Docker.

  • PAM authentication method: We recommend avoiding PAM as your authentication method because user credentials stored inside the container aren't persistent.

  • Logs: Access Server forwards logs to Docker, so it can't handle logging in the Access Server configuration. See the Docker logging documentation to set up rotation, forwarding, etc.

  • IPv6: We don't recommend Access Server inside a Docker container if you plan to use IPv6 for VPN clients because IPv6 support in the Docker network toolset is limited/experimental.

Troubleshooting

Expand the section below to help you find your answer, or contact our support team for help.

How can I replace the Access Server image?

You can replace your Docker container with a new Access Server image, but you must first save your configuration data outside of the Docker image.

Access Server stores the configuration files on a defined volume/folder. To move to a new image, you need to copy the files from that location or use the same volume/folder to run a new Access Server image. The specific steps depend on the defined folder directory for storing these files as set in the docker run command, -v <path to data>:/openvpn. That folder on the host contains the /etc directory, making upgrades and rollbacks possible.

My temporary password isn't working

If you need to reset the openvpn admin user password, you can do so with Access Server's sacli tool, which you can do from an interactive shell.

  1. From the host system, open an interactive shell:

    docker exec -it openvpn-as /bin/bash

  2. Reset the openvpn admin password:

    sacli --user openvpn --new_pass <PASSWORD> SetLocalPassword
sacli start

Upgrading

When upgrading to the latest Access Server version, refer to our tutorial:

In this section: