Tutorial: Migrate an Access Server Failover Deployment to New Infrastructure⁠

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.

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

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⁠

Sign in to the Admin Web UI on the MASTER node.
Navigate to VPN Server → Failover.
Select Disable Failover.

Disable failover using the Web API⁠

All commands in this section run on the MASTER node.

Connect to the MASTER node and get root privileges.

Disable failover:

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

Example output:
```
null
```

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"}
```

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.

Connect to the MASTER node and get root privileges.

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

Restart Access Server on the MASTER node:
```
systemctl restart openvpnas
```

Deploy two new Access Server nodes in the target environment:
- One node for the new MASTER.
- One node for the new BACKUP.
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.
Ensure both new nodes meet the Access Server system and network requirements before restoring the configuration.

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

Connect to the new MASTER node and get root privileges.
Restore the configuration backup. Follow Tutorial: How to Recover a Server with SQLite3 Dump Backup Files for the restoration procedure.
Verify that Access Server starts successfully and the expected configuration is present before configuring the new failover pair.

Re-create failover on the new MASTER and BACKUP nodes. Follow Tutorial: How To Set Up Failover Mode to configure the new failover deployment.
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.

Configure failover from CLI⁠

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

Complete the prerequisite configuration described in Steps 1-6 of Tutorial: How To Set Up Failover Mode.
Continue with Tutorial: Manage Failover Settings Using the Access Server CLI.

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.

Identify the DNS A record used for VPN client connections.
Remove the old failover IP from the DNS record.
Add the new failover IP.
If appropriate, temporarily lower the DNS TTL. For example: 60-300 seconds.

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

Verify from multiple locations that the hostname resolves to the new failover IP.
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.

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

Stop Access Server on each old node:
```
systemctl stop openvpnas
```
Confirm that no VPN client traffic reaches the old failover deployment.
Remove or archive the old server instances according to your organization's infrastructure policies.
Update firewall rules, monitoring systems, DNS configuration, and infrastructure automation to remove references to the old nodes.
Confirm that the new failover deployment handles all production VPN sessions.

Can't find what you're looking for?

Our support team will be happy to assist you.

Contact Support Schedule a Demo

Tutorial: Migrate an Access Server Failover Deployment to New Infrastructure⁠

Overview⁠

Prerequisites⁠

Placeholder values used in this tutorial⁠

Was this information helpful?