Server Migration

Server migration overview:

1. Install CAS on a new server (use the same license key).

2. Shutdown the old CAS and create a backup of the data.

3. Copy the backup from the old server to the new server.

4. Restore the CAS backup data on the new server.

5. Switch your BATM's to access the new server (SERVER IP).

Consider & prepare for the imminent impact, for instance:

•  the duration of your server downtime, 

• the need to visit each machine (depending on the approach you take), 

• logistic implications, etc.

You have several options:

• Use the same IP address for the newly installed server and your BATMs won't need any configuration change. This may or may not be difficult to set up, depending on your network configuration.

• Use a NEW IP and change the SERVER IP setting for each of your BATMs manually at each BATM.

• You can use your old server to redirect your BATMs to the new server. After first redirect, the new server IP address will be stored in the BATM. This means after each BATM has been redirected, you won't need the old server anymore. This solution might seem preferable to the previous one, but beware if you make a mistake in the redirect IP and BATM receives the redirect, there's no way of fixing the error remotely - you’ll have to visit the BATM onsite.

Step 1 - Install CAS on a new server

The CAS versions must be identical on both the old & new server!

• During install, make sure that the database name, username, and password are identical to the source server, or the restore will fail!

• Upgrade both the old & new servers' CAS to the most current version, or at least the same version.

• The license key must be identical on both servers to migrate Terminals remotely.

Step 2 - Backup the old (“source”) server’s CAS:

Stop ALL CAS services:

sudo /batm/batm-manage stop all

Backup your CAS data:

sudo /batm/batm-manage backup

• Depending on your database size, this step may take a few minutes.

• Note the backup directory!

  • (e.g. /batm/backup/20180923-151804-0400

Step 3 - Copy the backup to the new server:

Copy the backup/source directory (noted in the previous step) over to the new/target machine.

• Use any SFTP client to copy the backup to/from servers (e.g. SCP, FileZilla, PuTTY).

The following example demonstrates using the SCP method:

1. Your old CAS IP address is “1.2.3.4”

2. The backup directory is: "/batm/backup/20180923-151804-0400",

3. You have sudo (root/superuser) access.

cd /batm/backup
sudo scp -r root@1.2.3.4:/batm/backup/20180923-151804-0400 .

• NOTE: don’t omit the trailing “.” in the scp command! It is quite necessary.

• add the -i /path/to/identity.key parameter (before the “-r") if using a SSH public key (urged).

  • insert the actual path & filename to point to the actual SSH public key.

  • e.g. sudo scp -i /root/.ssh/id_rsa -r root@1.2.3.4:/batm/backup/20180923-151804-0400 .

Step 4 - Restore the backup on the new server:

The restore procedure is normally used on the same system - not on a new system as it is in this case. The restore should be modified to provide the wanted data (only). Some data isn’t required -or- will only create extra work (bad data).

Some configuration will be lost with a selective restore (as is demonstrated below). Missing configurations should be setup again using the appropriate feature’s instructions.

• Note the “Troubleshooting” section at the bottom of this article for guidance.

• See: batm-manage: the CAS CLI Toolkit (command: restore) for all options.

Migration restore using the batm-manage utility:

sudo /batm/batm-manage restore /batm/backup/20180923-151804-0400 "config data db"

• Replace the example /batm/backup/20180923-151804-0400 with the actual backup name & path.

Lastly, modify the /batm/config/network file to point to the current IP.

• See “Troubleshooting” at the bottom of this article for instructions (if needed).

Step 5 - Point the BATMs to the new CAS

The BATMs in your network now need to be redirected to the new server.

If your hosting service has the capability of reassigning your old/known IP to the new CAS server, then you should do so now. This is an unusual scenario - but some hosting services offer it. In some cases you may have a discreet backup & simply restore to a new Ubuntu image on your server. In these events - where the IP of your server hasn’t changed - you are done - you don’t need to change anything further (skip this step).

IN MOST CASES: you will follow one of these 2 procedures to change the BATMs' settings. Each BATM must be individually changed. There is no “batch” method (no matter which approach you take), though it is possible to create the redirection flags via a script (outside the scope of this article). Rebooting each BATM must be done one at a time, either onsite or via CAS. This is deliberate & prudent.

Option A:

Create a redirection flag.

• In this example, we’ll create this flag: /batm/app/shared/server.BT123456

• Use the provided commands (specified below).

• The command should identify the IP address of your NEW server.

Using that example information, type this command at your OLD server’s command prompt:

sudo bash -c 'echo -n "https://10.20.30.40:7741/apiv1" > /batm/app/shared/server.BT123456'

Then, tell the BATM to check for the new information the next time it calls home:

sudo touch /batm/app/shared/reconfigure.BT123456

Finally, reboot your BATM.

Option B:

Travel to each BATM physically & change the Server IP onsite as described here:

Set the BATM Server IP

Step 6 - Reboot the BATM(s).

You can do this remotely or onsite.

Troubleshooting

If you encounter this error during the restore, then your MySQL root password is insecure. You’ll need to set a password for the MySQL root account to restore the database.

1. INSTRUCTIONS: https://generalbytes.atlassian.net/wiki/spaces/ESD/pages/2555052033/Database+Configuration+Notes#Root-passwords

2. Reattempt the restore from the beginning.

If you restored everything during Step 4 (Restore), then you’ve overwritten your configuration files. Your network configuration file is amongst them. Bad entries in the network config file will cause this (and other symptoms).

First, determine your CAS server IP: What is the IP address of my CAS server?

Ensure your new/target IP is properly set in your network config file:

The “public_ip” setting is normally the public IP of your CAS server (example used: 1.2.3.4):

su -c 'sed s/^public_ip=.*/public_ip=1.2.3.4/ /batm/config/network'

Correct the hostname:

• required for linking messages & notifications back to your new website (i.e. Onfido).

• Typically, the hostname will be the same as the previous host/server.

• If empty, add the default to CAS by using:

su -c 'hostname > /batm/config/hostname'

If you know your domain name, and wish to enter it specifically (recommended), use:

su -c 'echo your.host.name > /batm/config/hostname'

• replace “your.host.name" with the fully qualified domain name (e.g. example.generalbytes.com).

Start the new CAS and note any reported errors.

Some configurations may be lost when migrating. Some migrations won’t be affected at all, and others will have to reconfigure a number of features. This article is designed to guide the many, so the few that are missing features will have to walk through the setup of each configuration individually.

Examples of some lost configurations might include:

• Custom database configuration: https://generalbytes.atlassian.net/l/cp/nPdCVRYU

• Extensions: https://generalbytes.atlassian.net/l/cp/0YoA5eco

• Port specifications

• Email settings

• SMS/Voice settings

Review and copy the relevant configuration files from the old server to quickly restore these settings.

• all configuration files are found in: /batm/config

Related articles

• Page:
  Crypto Setting Configuration Notes
• Page:
  Location Analytics
• Page:
  Custom Strings
• Page:
  Admin OpenVPN (using batm-manage)
• Page:
  Terminal Details