Changed in 51.0.0.0 Upgrading the SOAR Platform

The supported upgrade path for IBM Security® QRadar® SOAR Platform requires that you upgrade to each major release, one at a time. For example, if you currently have V49 installed and you want to upgrade to V51, you must run two installers. You must first upgrade to V50 and then upgrade to V51.

When you upgrade to a major version, it is recommended to install the latest point release for the version that you are installing. The latest version is SOAR Platform 51.0.0.0.

Before you begin

Review the following items:
  • Download the upgrade package from IBM® Support Fix Central.

    By default, the security updates and optional packages are included in the SOAR software package; however, you can select a different download option so that you can download each package separately.

  • If your environment includes a Disaster Recovery (DR) system, you must disable it before you upgrade the SOAR Platform. For more information, see Disabling Disaster Recovery.

    When you upgrade, you must upgrade both the SOAR Platform and the DR system to the same version.

  • If your SOAR Platform is configured to use an App Host, consider upgrading the App Host software.

About this task

The upgrade automatically backs up the full database.

If the upgrade includes new features or enhancements that require specific privileges, the upgrade process does not change the privileges for existing roles. Administrators must update the permissions to make the new features available to existing roles.

The upgrade process creates a snapshot of the Elasticsearch data that exists on your system. The Elasticsearch snapshot is incremental so the first time that you upgrade, it might take a little longer than usual while the snapshot is created. You can view the log file for creating the Elasticsearch snapshot in /usr/share/co3/logs/create_es_snapshot_before-upgrade-<version>.log.

Tip: The system requires extra disk space to store the Elasticsearch snapshot data. If you use the soarSystemBackup process to backup your data, only the most recent snapshot is kept and the disk space that is used by older snapshots is automatically cleaned up. If you do not use the soarSystemBackup process, you can purge older snapshots by running the soarKeepOnlyLatestElasticSearchSnapshot command.

New in 51.0.0.0 As part of the upgrade process for SOAR Platform to V51, PostgreSQL is upgraded to PostgreSQL 14. During the upgrade process, the SOAR Platform uses pgbackrest to do an incremental backup of PostgreSQL 12 data. When the database is upgraded to PostgreSQL 14, the SOAR Platform takes a full backup (as it is the first backup of the PostgreSQL 14 database). Because the SOAR Platform needs to take a full backup of the database, this upgrade might take longer than usual. You can view the log file for the PostgreSQL upgrade at /usr/share/co3/logs/postgresql_12_to_14_*.log.

Procedure

  1. Use ssh to connect to the SOAR Platform.
  2. To start the upgrade, type this command. 
    sudo bash soar-<version>.run

    Provide the version number (typically in the format x.x.x) that is specified in the file name.

  3. When prompted, choose to continue the upgrade.

    The upgrade script provides information about change to the database backup tool.

  4. If you experience longer upgrade times, you can monitor the progress by examining the update_database_x.log, where x represents the timestamp of the database upgrade. 
    sudo tail -f /usr/share/co3/logs/update_database_x.log

Results

The upgrade continues to run until the process is complete. Depending on which version you upgraded from, some user and API key account owners might receive emails that state that the account is expiring.

What to do next

If the upgrade fails, a message like this one is shown:
Post-installation setup has failed
Failed to upgrade IBM Security SOAR

If needed, you can revert to the previous state.

  • Use the yum command to view the backup package IDs.
    sudo yum history
  • To revert to the previous state, type this command, using the ID of the backup package that you want to restore to.
    sudo /crypt/resRollbackServerUpgrade /crypt/db_restore_points/before-upgrade-<xx.x.xxxx>-<date> <backup_package_ID>
If the command cannot find the backup set, follow these steps.
  1. Type this command to list the backup sets.
    sudo -u postgres pgbackrest --stanza=ibm-security-soar info

    By default, the stanza name is ibm-security-soar. If your stanza name is different, use it.

  2. Choose the backup set that you want to restore to, and run the following command to restore the database.
    sudo resRestoreDatabaseToRestorePoint -b <backup_set_name> -p <restore_point>
    For example, 
    sudo resRestoreDatabaseToRestorePoint -b 20220522-000101F_20220527-014158I -p before-upgrade-46.0.7900-20220527014202

    If postgresql cannot find the restore point from that backup set, the restore fails. You need to cat the restore point file to get the restore point. Afterward, repeat the procedure and choose a different backup set.

    To cat the file, use the following command.
    -bash-4.2$ sudo cat /crypt/db_restore_points/before-upgrade-<xx.x.xxx-date>
    You see output similar to the following example.
    backup_set:20220522-000101F_20220527-014158I
restore_point:before-upgrade-46.0.7900-20220527014202
restore_target_time:2022-07-27 01:42:02.359892+00
last_upgrade_script:569-update-united-kingdom-tooltip.groovy
  3. Roll back the SOAR Platform: 
    sudo /crypt/resRollbackServerUpgrade -n <yum_ID>
    The -n option prevents the rollback of the database, which was done in the previous step.

New in 51.0.0.0 The SOAR Platform automatically completes a full backup of the database once every week, and does an incremental backup of the database every day thereafter. It also expires any backups that are more than a week old. So when you upgrade to SOAR Platform V51, the last remaining PostgreSQL 12 backup remains on the system for one week, before being expired. You can copy this last PostgreSQL 12 backup to a permanent location so that you can roll back your system to SOAR Platform V50 more than a week after the upgrade.

The backups are located in /crypt/pgbackrest_repo/backup/ibm-security-soar/, where ibm-security-soar is the stanza name. If you want to save a PostgreSQL 12 backup permanently, use the following command:
sudo cp /crypt/pgbackrest_repo/backup/ibm-security-soar/<backup-set> <permanent>/<location>/<directory>
To find out which backup set is used by the pre-upgrade restore point, use the following cat command:
$ sudo cat /crypt/db_restore_points/before-upgrade-<xx.x.xxx-date>

The output includes a backup_set: field, where it lists the backup set that is used by the pre-upgrade restore point. If you saved this backup permanently and want to restore to using it after the original has expired, you must move it back to the /crypt/pgbackrest_repo/backup/ibm-security-soar/ directory.