RHEL migration

RHEL 7.5 is nearing end-of-life for full security updates. Migrating to RHEL 8.10 ensures continued patching, security hardening, and compliance with organizational policies. For more information see, RHEL End of Maintenance.

Benefits

  • The future Cisco IoT FND releases typically require newer OS libraries and database drivers. Moving the databases to a newer OS reduces the risk of runtime issues during the upgrade.

  • RHEL 8.10 provides newer package management, security features, and maintenance capabilities that simplify long-term administration and updates. For more information on RHEL 8.10 see, 8.0 Release Notes.

  • The migration aligns with security, compliance, and modernization goals while positioning the environment for a stable, supported upgrade to future Cisco IoT FND releases.

Migrating RHEL

Here are the steps involved in migrating RHEL 7.5 base OS to RHEL 8.10 base OS:

Summary

Here are the components that you require to perform the migration:

  • An existing VM (VM1) which was deployed along with OVA (Cisco IoT FND + Postgres + Influx) running RHEL 7.5 base OS, that was upgraded to Cisco IoT FND Release 5.0.

  • A new VM (VM2) deployed along with OVA (Cisco IoT FND + Postgres + Influx). Ensure that the VM2 is running RHEL 8.10 as the base OS.

  • Configure the VM2 to add 800GB to the /root logical volume (LV) and apply other database configurations as specified in the Achieving Scale Beyond 25,000 routers.

Here is the workflow to achieve a successful migration:

Workflow

  1. Perform a backup of the Postgres and Influx DB on VM1
  2. Deploy the VM2
  3. Copy the respective files from VM1 to VM2: cgms.properties, cgms.keystore, and userPropertyTypes.xml.Here is the path in which these files are found: /opt/fnd/data
  4. Follow the configuration steps and other database configurations specified inAchieving Scale Beyond 25,000 routers
  5. Restore the backup on VM2
  6. Configure the hostname in /etc/hosts if you have any
  7. Validate the VM2

Result

You've sucessfully migrated the OVA from RHEL 7.5 to RHEL 8.10 including the latest OS and DB versions.

What’s next

Follow the detailed steps for each of the stages.

Backup Postgres and Influx DB on VM1

Backup Postgres DB

This task guides you to backup the Postgres DB

Before you begin

  • Ensure that you are the root user when you run the script.

  • Ensure that you run the backup script on VM1 running Cisco IoT FND Release 5.0 and later releases.

  • To back up the Postgres DB from the Cisco IoT FND Postgres OVA, Cisco IoT FND is bundled with a script that writes the backup to a designated file location. The script, backupdb.sh, is available at /opt/cgms-postgres/scripts/. This script is included in the cgms-postgres rpm and the rpm is already installed for OVA deployments.

Use these instructions to backup the Postgres DB:

Procedure

Step 1

Stop the CGMS service:

Example:

$ docker exec -it fnd-container /etc/init.d/cgms stop

$ docker exec -it fnd-container /etc/init.d/cgms status

The Cisco IoT FND container is stopped.

Step 2

Run the backupdb.sh to move the Postgres DB to a particular location.

Example:

# Create the backup dir where to keep the backup DB file
mkdir -p /home/scaleDB

$ cd /opt/cgms-postgres/scripts
$ ./backupdb.sh
Usage: ./backupdb.sh <db service> <username> <backup file path>

$ ./backupdb.sh cgms cgms_dev /home/scaleDB/backup-postgres-db
password:<enter the db password here>

Postgres DB backup is successful.

What to do next

Perform a backup of Influx DB.

Backup Influx DB

This task guides you to backup the Influx DB

Before you begin

  • Ensure that you are the root user when you run the script.

  • To back up the Influx DB from the Cisco IoT FND Postgres OVA, Cisco IoT FND is bundled with a script that writes the backup to a designated file location. The script, backupdb.sh, is available at /opt/cgms-influx/scripts/. This script is included in the cgms-influx rpm and the rpm is already installed for OVA deployments.

Use these instructions to backup the Postgres DB:

Procedure

Step 1

Stop the CGMS service:

Example:

$ docker exec -it fnd-container /etc/init.d/cgms stop

$ docker exec -it fnd-container /etc/init.d/cgms status

The Cisco IoT FND container is stopped.

Step 2

Run the backupdb.sh to move the Influx DB to a particular location.

Example:

# Create the backup dir where to keep the backup DB file
$ mkdir -p /home/scaleDB/influxDBbackup

$ cd /opt/cgms-influx/scripts
$ ./backupdb.sh
Usage: ./backupdb.sh <db service> <backup file path>

$ ./backupdb.sh fnd /home/scaleDB/influxDBbackup/backup-influx-db

Influx DB backup is successful.

What to do next

Deploy VM2

Deploy VM2

This task helps you deploy VM2.

Procedure

Step 1

Deploy a new VM of Cisco IoT FND Release 5.0 Postgres OVA running RHEL 8.10 OS base version using VMware vSphere. For more information see, Deploy a Virtual Machine from an OVF or OVA File in the VMware Host Client.

Step 2

Configure the VM2 to add 800GB to the /root logical volume (LV) and apply other database configurations as specified in the Achieving Scale Beyond 25,000 routers.

Step 3

Ensure that the VM compatibility and ESXi host settings are appropriate for the migration.

Step 4

Ensure that all the important backup configuration files, such as cgms.properties, cgms_keystore, and userPropertyTypes.xml in VM1 /opt/fnd/data/ are copied or moved to the VM2 in the same location.

The VM2 is successfully deployed.

What to do next

Restore the backup on VM2

Restore backup on VM2

Restore Postgres DB backup on VM2

This task helps you restore Postgres DB backup on VM2.

Before you begin

  • Ensure that the VM2 is running Cisco IoT FND Release 5.0.

  • You must be the root user to run the restoration script.

  • Use the Cisco IoT FND provided restore scripts and ensure that the DB versions are compatible.

  • Once the restoration is complete, run the database migration script ./db-migrate to align the DB schema with the Cisco IoT FND version.

  • Copy the Postgres DB backup file from VM1 to VM2, and restore using the restoredb.sh script located at /opt/cgms-postgres/scripts. The script is included in the cgms-postgres rpm and the rpm is already installed for OVA deployments.

Follow these steps to restore Postgres DB backup on VM2:

Procedure

Step 1

Stop the CGMS service:

Example:

$ docker exec -it fnd-container /etc/init.d/cgms stop

$ docker exec -it fnd-container /etc/init.d/cgms status

Cisco IoT FND container is stopped.

Step 2

Drop the Postgres DB if the DB is already present:

Example:

$ cd /opt/cgms-postgres/scripts
$ ./dropdb.sh
Usage: ./dropdb.sh <db host> <db port> <db service> <username> <password>

$ ./dropdb.sh localhost 5432 cgms cgms_dev cgms123

Step 3

Create a new DB:

Example:

$ cd /opt/cgms-postgres/scripts
$ ./createdb.sh
Usage: ./createdb.sh <db host> <db port> <db service> <username> <password>

$ ./createdb.sh localhost 5432 cgms cgms_dev cgms123
A new DB is created.

Step 4

Restore the Postgres DB. The VM1 Postgres backup file (backup-postgres-db) is copied and stored in the VM2 location: /home/scaleDB/backup-postgres-db

Example:

$ cd /opt/cgms-postgres/scripts
$ ./restoredb.sh
Usage: ./restoredb.sh <db service> <username> <backup file path>

$ ./restoredb.sh cgms cgms_dev /home/scaleDB/backup-postgres-db
password: <cgms123>

Step 5

Run the DB migrate script followed by initiating the CGMS service:

Example:

$ docker exec -it fnd-container /bin/bash
$ /opt/cgms/bin/db-migrate 
password: <cgms123>

$ /etc/init.d/cgms start

$ /etc/init.d/cgms status
$ exit

Postgres DB backup from VM1 is restored in VM2.

What to do next

Restore Influx DB backup on VM2

Restore Influx DB Backup on VM2

This task helps you restore Influx DB backup on VM2.

Before you begin

  • Ensure that the VM2 is running Cisco IoT FND Release 5.0.

  • You must be the root user to run the restoration script.

  • Use the Cisco IoT FND provided restore scripts and ensure that the DB versions are compatible.

  • Once the restoration is complete, run the database migration script ./db-migrate to align the DB schema with the Cisco IoT FND version.

  • Copy the Influx DB backup file from VM1 to the VM2, and restore using the restoredb.sh script located at /opt/cgms-influx/scripts. The script is included in the cgms-influx rpm and the rpm is already installed for OVA deployments.

Follow these steps to restore Influx DB backup on VM2:

Procedure

Step 1

Stop the CGMS service:

Example:

$ docker exec -it fnd-container /etc/init.d/cgms stop

$ docker exec -it fnd-container /etc/init.d/cgms status

Cisco IoT FND container is stopped.

Step 2

Drop the Influx DB if the DB is already present:

Example:

$ cd /opt/cgms-influx/scripts
$ ./dropDB.sh
Usage: ./dropDB.sh <db host> <db port> <database> <adminusername> <adminpassword>

$ ./dropDB.sh 192.68.5.1 8086 fnd cgms_dev cgms123

Step 3

(Optional) If you're installing Influx DB for the first time, create an admin user:

Example:

$ cd /opt/cgms-influx/scripts
$ ./createAdminUser.sh
Usage: ./createAdminUser.sh <db host> <db port> <adminusername> <adminpassword>

$ ./createAdminUser.sh 192.68.5.1 8086 cgms_dev cgms123
An admin user is created.

Step 4

The VM1 Influx DB backup file (backup-influx-db) is copied and stored in the VM2 location: /home/scaleDB/backup-influxDBbackup

Example:

$ cd /opt/cgms-influx/scripts
$ ./restoredb.sh
Usage: ./restoredb.sh <db service> <backup file path>

$ ./restoredb.sh fnd /home/scaleDB/influxDBbackup/backup-influx-db

Step 5

Start the CGMS service:

Example:

$ docker exec -it fnd-container /bin/bash

$ /etc/init.d/cgms start

$ /etc/init.d/cgms status
$ exit

Influx DB backup from VM1 is restored in VM2.

What to do next

Validate the VM2

Validate VM2

This task helps you validate the VM2 that you just deployed.

Procedure

Step 1

Verify the service status and connectivity to PostgreSQL and InfluxDB. For more information see, PostgreSQL documentation and Influx DB documentation.

Step 2

Perform sanity tests such as device onboarding, firmware upgrade, and configuration push to validate the Cisco IoT FND environment.

  • VM2 is successfully deployed and validated.

Troubleshoot

This task helps you troubleshoot a known issue of the device group list missing in the left tree on Cisco IoT FND post migration.

Before you begin

Ensure that the backup is restored on VM2.

Here are the instructions to fix the issue where the device list doesn't appear on Cisco IoT FND post migration:

Procedure

Step 1

From the Cisco IoT FND menubar, choose DEVICES > Field Devices.

Step 2

Click Add Devices.

Step 3

Upload a dummy .CSV file from your local device.

Step 4

Click Add.

You'll see the device list appearing in the left pane.

You've succesfully fixed the issue where the device group list appear on Cisco IoT FND left tree post migration.