Launch Access Server on Docker

Upgrade to Latest Version

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

Once installed, Access Server includes three components:

  • The VPN server software built on the popular OpenVPN open-source software.
  • User-friendly and intuitive web interfaces.
  • Client software for Windows, macOS, Android, iOS, and Linux.

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.

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.

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

Important: You can run Access Server on a Docker container with a self-hosted server, but not all cloud providers grant admin privileges on their services. On a self-hosted server, the --cap-add=NET_ADMIN gives the container the necessary admin privileges on network capabilities.

Refer to the section below for other limitations and known issues with 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.

  1. Run the Docker container based on the Access Server image with these parameters:
    docker run -d \
    --name=openvpn-as --cap-add=NET_ADMIN \
    -p 943:943 -p 443:443 -p 1194:1194/udp \
    -v <path to data>:/openvpn \
    openvpn/openvpn-as
    cap-add: This is for interacting with the network stack.
    port 943: This opens up the Admin Web UI port.
    port 443: This opens the necessary TCP port.
    port 1194: This opens the necessary UDP port.
    <path to data>: This is where you want to store Access Server configuration files (replace with your preferred file path).
    • 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. Important: Ensure you use https in the URL.
    • A security warning displays. Access Server uses a self-signed SSL certificate. We recommend replacing it with a signed certificate.
  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.
  4. Click Save Settings and Update Running Server.

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

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