Background

In the lifetime of any server, there may come a situation where you want to move the server from one piece of physical hardware to another, or move your virtual machine from one cloud to another which can involve new names for the server and/or new IP addresses which can cause issues when trying to maintain your Avantra configuration.

This guide is to showcase a specific scenario where an Avantra installation is being moved to a new host which will have a new DNS name and IP but it is vital that the existing agents are able to continue to function without a manual reconfiguration of each agent.

Scenario

This document was written and tested with the following scenario. You have an active and productive Avantra server called "server1.intranet.corp" with a number of agents attached.

1. The local agent on the Avantra server itself (hostname is "server1")
2. An agent that acts as a gateway for other agents to communicate through (hostname is "gateway1")
3. An agent that is on another network with hostname "agent1" which cannot communicate directly to the Avantra server but instead communicates through "gateway1".

You need to migrate the Avantra server at "server1.intranet.corp" to a new server called "server2.intranet.corp" without loosing connectivity to the existing agent network.

To do this you will need to introduce a temporary DNS alias called "avantra.intranet.corp" which will initially point to "server1.intranet.corp" and eventually be switched over to point to "server2.intranet.corp" after the migration.

The process is detailed below.

You are strongly encourage you to take a full back up of your existing installation and database before performing any of the steps below. Some of the commands in this document are destructive and, if run on the wrong machine or in the wrong order, could lead to data loss. Syslink Xandria Ltd. takes no responsibility and will accept no liability for issues arising from the use of the commands or procedures in this document.

1. Establish a DNS A record

Have a new DNS record created e.g. "avantra.intranet.corp" which resolves to the same IP address as the existing Avantra server which, in the case of the scenario in this document, would be the IP address of "server1.intranet.corp" with a TTL (time to live) value of 60 seconds.

2. Update all agents to use the new DNS record

You update the configuration on the existing server "server1.intranet.corp" to tell all agents to use the new alias to contact the Avantra system. Once this is complete, run the server as normal for a period to ensure that all agents receive this configuration update and are using the new DNS name (usually at least 24 hours).

To update this configuration, in the Avantra UI, go to Administrator → Settings and go to the "Avantra Master" tab. In here, set the value of "network.masterhost" to the DNS alias you created in step 1 e.g. "avantra.intranet.corp". Finally, restart the master server services at the OS level.

For example, on linux this might be "sudo systemctl restart avantra-master" or you can use the provided RC script e.g. "/opt/avantra/master/rc.master restart".

For example, on Windows, you can restart the master server services via Windows Services Manager or from command line: "net stop lyceusm" and then "net start lyceusm".

You do not need to restart the Avantra UI or any local agent.

Once the server is running again, wait a few minutes (at least 5-10 minutes) and verify that agents are connecting OK. Please note that if you use the "send to agent" functionality as part of your testing, the first attempt WILL fail with a "CHECKSUM ERROR" as the agent will initially reject configuration with a server hostname that is different to what was expected.

3. Perform the installation of the new Avantra system on the new host

Perform a full installation of an Avantra system on your new host. This will include:

• Install Java
• Install PostgreSQL or MSSQL (if not using an externally hosted one)
• Install the Avantra server
• Install the Avantra agent

Do not proceed to configure the Avantra system via the web UI wizard as this is not necessary.

Shut down all of the Avantra services on that new machine once the installation is complete. For example:

# using systemctl
sudo su
systemctl stop avantra-master
systemctl stop avantra-ui
systemctl stop avantra-agent

# using rc scripts
sudo su avantra
/opt/avantra/master/rc.master stop
/opt/avantra/xangui/rc.xangui stop
/opt/avantra/agent/rc.agent stop

On Windows you can stop the services via Windows Services Manager or via Command Line with the following commands:

net stop xangui
net stop lyceusm
net stop sxagent

The commands in the next section are useful anyway for a manual installation so you are encouraged to review them, but they are designed for if you have used the Avantra quick installer on Linux to install your to-be or new Avantra server.

You will need to run these commands ONLY ON THE NEW SERVER to drop the newly created database and reset the local agent. Running these commands on the existing server WILL result in data loss so please do not do it!!

Those commands will be as follows from a sudo-capable user:

# Login as the Postgres user
sudo su postgres

# Run the psql command to access the DB
psql

# DO NOT RUN THIS COMMAND ON YOUR ORIGINAL SERVER
# Drop the existing database
drop database avantra_db;

# Recreate the database called avantra_db with the owner being the user avantra
create database avantra_db owner avantra;

# [optional] reset the password for the postgres user avantra
ALTER ROLE avantra WITH PASSWORD '<1nsert_your_pa$$word';

# exit out of psql
\q

# exit out of the postgres user
exit

# reset the local agent
sudo rm -Rf /opt/avantra/agent/db/agent.mv.db
sudo rm -Rf /opt/avantra/agent/services/ag/cfg/*cfg.json

# reset the avantra server database location
sudo rm -Rf /opt/avantra/.xandria/database.cfg

4. Shut down all Avantra services

Please note, this is where downtime starts for your existing Avantra installation.

Shut down all Avantra server services on both the old and the new Avantra servers. This includes the server, the web UI and any local agents.

5. Redirect the DNS alias to the new machine

Update the DNS record you created earlier e.g. "avantra.intranet.corp" to now point to the IP address of the new machine which will host Avantra e.g. "server2.intranet.corp". Make sure the TTL of 60 seconds remains in case you have to fail back. This can be increased at a later time if needed.

6. Backup the existing Avantra database to a file 

If you are using a hosted database instance and will simply be reusing that database with the new server, skip to step 8 to configure the new server to use the database.

The following command is to illustrate how this could work for a PostgreSQL installation but please refer to your own procedures for other databases such as MSSQL.

# Login as the postgres user
sudo su postgres

# Go to the home directory for that user so the output file can be stored
cd

# Use the standard command to dump the database - please adjust the name avantra_db here if your database is called something else
pg_dump -F c avantra_db > avantra_db.dump

# exit back to sudo-capable user.
exit

The backup file should be copied to the new destination server where it will be restored.

7. Restore the Avantra database on the new server

If using MSSQL please refer to their documentation for database restore.

For PostgreSQL the following commands illustrate how this can work:

# Set the ownership of the file to the postgres user
sudo chown postgres:postgres avantra_db.dump

# Log in as the postgres user
sudo su postgres

# Restore the database file into the database avantra_db
pg_restore -d avantra_db avantra_db.dump

# Remove the restore file when done.
rm avantra_db.dump

# exit back to sudo-capable user.
exit

Once you select the right database you should see a screen which shows that a valid Avantra database has been found:

Complete the wizard and log in using the credentials for an Administrator from the original Avantra system

9. Verify agent connectivity

Once logged in successfully, you can now proceed to verify your agent connectivity. Wait a few minutes (at least 5-10 minutes) and verify that agents are connecting OK.

10. [optional] Update local agent hostname

If you have an agent configured within Avantra for the local machine or if any of your gateways are set up on the local Avantra instance, you will need to adjust the value of the "Physical Server Name" in the server configuration to match the new hostname of the underlying new operating system. If you have specified an IP address (rather than a hostname) in the "FQDN or IP Address" field, this should be adjusted as well.

11. [optional] Update DNS to use the direct hostname

You can continue to use the DNS alias permanently going forward (and in fact this is useful for disaster recovery scenarios), but if you need or want to, you can adjust the agents to use the direct hostname by performing the reverse of step #2.

12. Archive the old server

Once you have successfully run your Avantra server on the new hardware for more than 24 hours, you should archive the old server.