Documentation and help portal

★ Home
regify Provider
Version 5.3
Alternative Upgrade Manual
Deutsch
Français
regify provider Alternative Upgrade Manual

Overview

These are the alternative upgrade instructions for the regify provider appliance to the next major version 6.0. It is normally enough to perform upgrades simply by going to Check for updates and following the instructions there. This alternative path is provided for installations where disk space does not permit the inplace process. Instead, a new machine is created, and a backup of the old machine is restored on it. This process is more involved, so attention must be paid to the details laid out here.

Unlike normal regify appliance administration, this process requires some familiarity with Unix/Linux command line use. If you are forced to use this path but do not have the necessary experience, please contact regify support for assistance.
All command line steps must be run as root.

Process Overview

This upgrade method works by following these basic steps:

  • Install a new properly sized machine

  • Upgrade the old machine to version 5.3.5

  • Make a backup of the old machine

  • Restore the backup on the new machine

  • Swap out the IPs from the old machine to the new one.

Step 1 - Onetime Steps

The steps in this section need only be done once.

Old Machine

  • Upgrade the old machine to version 5.3.5

  • Pull and run a script to include CSS customizations that were not stored in the DB in version 5.3.

    • Make sure you’re allowed to log into the old machine as root by ensuring Allow root login in SSH Settings is checked.

    • Log into the old machine as root and run the following:

wget https://files.regify.com/fixReplication
chmod +x fixReplication
./fixReplication

New Machine

  • Install a new properly sized machine. Pay particular attention to disk space.

  • Make sure you’re allowed to log into the new machine as root by ensuring Allow root login in SSH Settings is checked.

  • Run the Primary Appliance Wizard

  • Run the Secondary Appliance Wizard, however, this may fail if you do not yet have access to the clearing system. In that case you need to Back out of it by pressing F8 or tabbing to Back each screen.

Manual Clearing Credentials

  • If it failed, add the clearing credentials manually by editing /var/lib/regify-provider/menu_config.php and ensuring the following lines exist exactly once with the right credentials. You may use vim or nano to do so.

define('PROVIDERID', 99);
define('CLEARINGPASS', 'clearingtoken');

  • You can find your clearing credentails on the old machine by running:

cat /opt/provider/REGIFY_INCLUDE/menu_config.php

  • Before going life, you will also need to open the firewall to web traffic by running:

/usr/libexec/regify-provider-app/fwop -a 1 -p 80
/usr/libexec/regify-provider-app/fwop -a 1 -p 443

Stop Cron

Regardless of whether the wizard worked or not, you must comment out the provider cron jobs to prevent them from running.

  • Edit /etc/cron.d/1provider

SHELL=/usr/bin/bash
PATH=/usr/sbin:/usr/bin
MAILTO=root
HOME=/
#*/5 *   *   *   *   www-data   /usr/libexec/regify-provider/task_5min
#2   0   *   *   *   www-data   /usr/libexec/regify-provider/task_daily

Step 2 - Migrate Data

Following this step allows you to test the upgrade offline, so it is highly recommended to do this before taking the old system offline.

Backup Old Machine

  • From the old machine make a backup by running:

/usr/libexec/regify-provider-app/makebackup -o backup.enc

  • Copy the backup to the new machine:

rsync -av backup.enc new.machine.ip:

Normal Disk Variant

Restore New Machine

  • On the new machine restore the backup:

export TMP=/var/tmp
/usr/libexec/regify-provider-app/restore backup.enc
The restore operation may take a substantial amount of time depending on the size of the database.

RAM Disk Alternative

The performance of the database restore of often I/O bound. As a workaround the following speed booster may be employed.

This check should be done on the new machine after an initial restore has been done.

Determine the disk space needed by the database by running:

du -ch /var/lib/mysql

Round that number up a bit and add that many gigabytes of RAM to your virtual machine. It should also have at least 2 CPU cores.

Do not set this RAM size for a fresh installation because it will cause an oversized swap partition.

Setup RAM Disk

This should be done on the new machine

When the system runs with the added RAM, likely after a restart, run:

systemctl stop mariadb
mv /var/lib/mysql /var/lib/mysql.bak
mkdir /var/lib/mysql
mount -t tmpfs -o size=20G dbdisk /var/lib/mysql
rsync -a /var/lib/mysql.bak/ /var/lib/mysql/
systemctl restart mariadb

Restore New Machine

  • Run the restore as usual

export TMP=/var/tmp
/usr/libexec/regify-provider-app/restore backup.enc

Move the database to disk

Now move the database back to the normal disk:

systemctl stop mariadb
rsync -a --delete /var/lib/mysql/ /var/lib/mysql.bak/
umount /var/lib/mysql
rmdir /var/lib/mysql
mv /var/lib/mysql.bak /var/lib/mysql
systemctl restart mariadb

Remove Extra RAM

If this was the final run, remove the extra RAM again and restart the machine now.

Sanity check the Migration

Try to verify things as much as possible at this stage.

You may need to adjust your /etc/hosts file to make this work.

  • Log into your regify provider administration web portal https://<yourUrl>/ADMINISTRATION/ and inspect things.

  • Log into your sub provider pages and see whether they look sane.

Step 3 - Final Run

Once the migration has been tested, it is time to perform the real migration.

Follow these steps:

  • Put the old provider into maintenance mode

    • Log into your regify provider administration web portal https://<yourUrl>/ADMINISTRATION/

    • Go to Provider maintenance  Maintenance mode and click Enable maintenance mode

  • Follow the Migrate Data section once more

Step 4 - Swap Public IPs

Swap out public IPs from the old to the new system. We cannot give instructions on how to do this on most deployments.

It is no longer required to have an IP for every sub provider, so this is transitional and may be consolidated after DNS has been updated. It may also be consolidated now.

One Example

If your public IPs were directly on your provider, you may disconnect the public NIC of your old machine and then assign those public IPs to the new machine. You may manually set them in /etc/network/interfaces by copying the existing to /etc/network/interfaces.new and editing it.

cp /etc/network/interfaces /etc/network/interfaces.new
auto ens6
iface ens6 inet static
  address 1.2.3.4/24
  gateway 1.2.3.1

auto ens6:0
iface ens6:0 inet static
  address 1.2.3.5/24

auto ens6:n
iface ens6:n inet static
  address 1.2.3.6/24
...
Be sure to swap out ens6 with your own NIC, the IP/Mask sets with your own. The first one is the main outgoing IP and should have the gateway entry.

Also be sure to retain entries like

auto lo
iface lo inet loopback
Before applying /etc/network/interfaces.new ifdown any changed and deleted interfaces from /etc/network/interfaces

Bring the new IPs online

ifdown eno6
mv /etc/network/interfaces.new /etc/network/interfaces
ifup eno6
ifup eno6:0
...

Step 5 - Verify the new deployment

  • Log into the regify provider administration web portal using the new URL https://<yourUrl>/admin/

  • Handle any To-do items that you encounter there.

  • When everything seems done, go to Provider maintenance  Maintenance mode and click Remove maintenance mode to turn off maintenance mode again.

  • Remove the restored backup again:

rm /root/backup.enc

Restart Cron

You must re-enable the commented out the provider cron jobs since they must run.

  • Edit /etc/cron.d/1provider

SHELL=/usr/bin/bash
PATH=/usr/sbin:/usr/bin
MAILTO=root
HOME=/
*/5 *   *   *   *   www-data   /usr/libexec/regify-provider/task_5min
2   0   *   *   *   www-data   /usr/libexec/regify-provider/task_daily
It is strongly recommended to delete the old machine. If it is accidenatlly started, it will most likely try to use the public IPs. Either way, bad things will happen if it ever comes online again.