Skip to main content

Tutorial: Migrate an Access Server Failover Deployment to New Infrastructure

Abstract

Migrate an existing Access Server failover deployment to new infrastructure — covers disabling failover, backing up configuration, deploying new nodes, restoring the backup, recreating failover, and updating DNS records. Also covers OS upgrade scenarios.

Overview

Use this tutorial to perform a failover migration of an existing Access Server failover deployment to a new environment.

You might migrate a failover deployment when you need to:

  • Move the deployment to new infrastructure.

  • Perform an operating system upgrade, such as upgrading from Ubuntu 22.04 LTS to Ubuntu 24.04 LTS.

  • Upgrade Access Server as part of an infrastructure transition.

  • Replace or decommission existing failover nodes.

An Access Server failover deployment consists of a MASTER node and BACKUP node that use UCARP, the high-availability protocol used by Access Server failover, to manage a shared virtual IP, also referred to as the failover IP.

A failover migration requires you to preserve the Access Server configuration while replacing the underlying nodes. This tutorial walks you through disabling failover, backing up the current configuration, restoring it to new nodes, re-creating failover, updating DNS if necessary, and decommissioning the old environment.

Prerequisites

Before you begin, ensure you have:

  • An existing Access Server failover deployment.

  • Access Server 3.1.0 or newer if you plan to use the Web API method in Step 1.

  • Administrative access to the Admin Web UI.

  • Console access with root privileges on both Access Server nodes.

  • Optional: A remote system for making API requests.

Important

The failover API specification may change between Access Server releases. Always verify the API documentation for your current version. Refer to: View the API specification.

Note

In our documentation, we use example IPv4 addresses and subnets reserved for documentation, such as 192.0.2.0/24, 198.51.100.0/24, and 203.0.113.0/24.

Ensure you replace them with valid IPv4 addresses and subnets for your network(s).

Placeholder values used in this tutorial

Replace the following placeholders with values for your environment:

Placeholder

Description

<FAILOVER_IP>

Shared virtual failover IP address

<UCARP_PASSWORD>

UCARP shared secret password

<PRIMARY_IP>

IP address of the primary node

<SECONDARY_IP>

IP address of the secondary node

Tip

The UCARP secret can be any secure string. Access Server typically generates a random 16-character value containing uppercase letters, lowercase letters, and numbers.

Step 1: Disable failover on the existing nodes

Before backing up the configuration, disable failover on the current deployment. You can disable failover from the Admin Web UI, with the Web API, or with sacli.

The dbpush configuration keys used in the CLI methods control database synchronization between the failover nodes.

Disable failover from the Admin Web UI

  1. Sign in to the Admin Web UI on the MASTER node.

  2. Navigate to VPN Server → Failover.

  3. Select Disable Failover.

Disable failover using the Web API

Note

This method requires Access Server 3.1.0 or newer.

Important

This tutorial uses sacli apicall, but you can also use cURL or Swagger UI to call the Web API. Refer to Tutorial: Test the New Web API (OpenAPI) in Access Server 3.0.

All commands in this section run on the MASTER node.

  1. Connect to the MASTER node and get root privileges.

  2. Disable failover:

    sacli --method POST --url 'api/config-items/Default' --value '{"failover.mode":"none"}' apicall

    • Example output:

      null

  3. Disable the failover configuration for the BACKUP node:

    sacli --method POST --url 'api/server/failover-init' --value '{"new_config":{"failover.mode":"none","ucarp.addr":"<FAILOVER_IP>","ucarp.secret":"<UCARP_PASSWORD>","dbpush.hosts.0.enable":"true","dbpush.hosts.0.public":"<PRIMARY_IP>","dbpush.hosts.0.internal":"PRIMARY","dbpush.hosts.0.username":"root","dbpush.hosts.0.password":"","dbpush.hosts.0.ssh_port":"22","dbpush.hosts.1.enable":"true","dbpush.hosts.1.public":"<SECONDARY_IP>","dbpush.hosts.1.internal":"SECONDARY","dbpush.hosts.1.username":"root","dbpush.hosts.1.password":"","dbpush.hosts.1.ssh_port":"22"},"old_config":{"failover.mode":"ucarp","ucarp.addr":"<FAILOVER_IP>","ucarp.secret":"<UCARP_PASSWORD>","dbpush.hosts.0.enable":"true","dbpush.hosts.0.public":"<PRIMARY_IP>","dbpush.hosts.0.internal":"PRIMARY","dbpush.hosts.0.username":"root","dbpush.hosts.0.password":"","dbpush.hosts.0.ssh_port":"22","dbpush.hosts.1.enable":"true","dbpush.hosts.1.public":"<SECONDARY_IP>","dbpush.hosts.1.internal":"SECONDARY","dbpush.hosts.1.username":"root","dbpush.hosts.1.password":"","dbpush.hosts.1.ssh_port":"22"}}' apicall

    • Example output:

      {"reason":"Success"}

  4. Restart the MASTER node:

    sacli --method POST --url 'api/server/restart?restartMode=systemctl' --value '' apicall

    • Example output:

      {}

Disable failover using sacli

This method works on all supported Access Server versions. If you're new to sacli, refer to Tutorial: An Intro to the sacli Command-Line Utility.

All commands in this section run on the MASTER node.

  1. Connect to the MASTER node and get root privileges.

  2. Remove the failover and dbpush configuration:

    sacli --key "dbpush.hosts.0.enable" ConfigDel
sacli --key "dbpush.hosts.0.internal" ConfigDel
sacli --key "dbpush.hosts.0.password" ConfigDel
sacli --key "dbpush.hosts.0.public" ConfigDel
sacli --key "dbpush.hosts.0.ssh_port" ConfigDel
sacli --key "dbpush.hosts.0.username" ConfigDel
sacli --key "dbpush.hosts.1.enable" ConfigDel
sacli --key "dbpush.hosts.1.internal" ConfigDel
sacli --key "dbpush.hosts.1.password" ConfigDel
sacli --key "dbpush.hosts.1.public" ConfigDel
sacli --key "dbpush.hosts.1.ssh_port" ConfigDel
sacli --key "dbpush.hosts.1.username" ConfigDel
sacli --key "failover.mode" ConfigDel
sacli --key "ucarp.addr" ConfigDel
sacli --key "ucarp.secret" ConfigDel

  3. Restart Access Server on the MASTER node:

    systemctl restart openvpnas

Step 2: Back up the MASTER node configuration

Create a database configuration backup from the current MASTER node before deploying the replacement environment.

Important

Don't proceed until you have a verified backup of the current configuration. You'll restore this backup to the new MASTER node.

Step 3: Deploy the new failover nodes

  1. Deploy two new Access Server nodes in the target environment:

    • One node for the new MASTER.

    • One node for the new BACKUP.

  2. If this failover migration is part of an OS upgrade, install the desired supported operating system on the new nodes rather than upgrading the operating system in place on the existing failover nodes.

  3. Ensure both new nodes meet the Access Server system and network requirements before restoring the configuration.

Step 4: Restore the configuration to the new MASTER node

Restore the configuration backup from the old MASTER node to the new MASTER node.

  1. Connect to the new MASTER node and get root privileges.

  2. Restore the configuration backup. Follow Tutorial: How to Recover a Server with SQLite3 Dump Backup Files for the restoration procedure.

  3. Verify that Access Server starts successfully and the expected configuration is present before configuring the new failover pair.

Step 5: Create the new failover deployment

  1. Re-create failover on the new MASTER and BACKUP nodes. Follow Tutorial: How To Set Up Failover Mode to configure the new failover deployment.

  2. Following the tutorial, you'll configure the new:

    • MASTER node.

    • BACKUP node.

    • Shared virtual failover IP.

    • UCARP shared secret.

    • Database synchronization between the two nodes.

Important

Before directing production traffic to the new environment, verify that the MASTER and BACKUP roles are correct and test that the shared virtual IP moves successfully during failover.

Configure failover from CLI

If you prefer to configure the failover deployment from the command line:

  1. Complete the prerequisite configuration described in Steps 1-6 of Tutorial: How To Set Up Failover Mode.

  2. Continue with Tutorial: Manage Failover Settings Using the Access Server CLI.

Step 6: Update DNS records, if applicable

If VPN clients reach your failover deployment through a DNS hostname that resolves to the shared virtual IP, update the DNS record to use the new failover IP. For example, your users might connect to vpn.example.com.

Tip

Consider temporarily lowering the DNS TTL before the cutover. A lower TTL reduces how long DNS resolvers cache the old address and can speed DNS propagation during the migration window.

  1. Identify the DNS A record used for VPN client connections.

  2. Remove the old failover IP from the DNS record.

  3. Add the new failover IP.

  4. If appropriate, temporarily lower the DNS TTL. For example: 60-300 seconds.

  5. Verify DNS resolution:

    nslookup vpn.example.com

    • Example output:

      Server:         203.0.113.254
Address:        203.0.113.254#53

Non-authoritative answer:
Name:   vpn.example.com
Address: 198.51.100.10

  6. Verify from multiple locations that the hostname resolves to the new failover IP.

  7. Confirm that VPN clients can connect successfully through the hostname.

    Important

    Some clients and DNS resolvers may continue using cached DNS results until the previous TTL expires. Allow sufficient time for DNS caches to expire before permanently removing the old environment.

Step 7: Decommission the old failover deployment

After the new failover deployment is fully operational and you've confirmed that production traffic uses the new environment, decommission the old nodes.

Tip

If your operational process allows it, keep the old nodes powered off but available for a short rollback window before permanently deleting them.

  1. Stop Access Server on each old node:

    systemctl stop openvpnas

  2. Confirm that no VPN client traffic reaches the old failover deployment.

  3. Remove or archive the old server instances according to your organization's infrastructure policies.

  4. Update firewall rules, monitoring systems, DNS configuration, and infrastructure automation to remove references to the old nodes.

  5. Confirm that the new failover deployment handles all production VPN sessions.

In this section:

The VPN server software, hosted on a Linux operating system.

Access Server's web server used by the administrator to configure the VPN server.