Upgrading the SOAR Platform

The supported upgrade path requires that you upgrade to each major release, one at a time. If you are using an older version of the SOAR Platform, you must first upgrade to V50 before you can upgrade to V51.

When you upgrade to a major release, it is recommended to install the latest point release. For example, if you currently have 49.2 installed and you want to install 51.x, you must run two installers: 49.2 > 50.x > 51.x.

Before you begin

Review the following information to ensure that you are prepared for the upgrade.
  • 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.

  • Make sure that your system is up to date with all OS security updates.
  • Ensure that the following users and groups are created. If necessary, create them.
    • res-email user in a res-email group.
    • res-messaging user in a res-messaging group.
    • res-keystore group.
  • 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.

About this task

The upgrade process 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.

To support the soarSystemBackup and soarSystemRestore processes, the upgrade includes commands to add a disk to the SOAR volume group, and then move the /crypt/attachments directory to new logical volume.

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.

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. The emails are triggered when the system finds accounts that did not authenticate since the system upgraded to V39 or later.

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 application. 
    sudo /crypt/resRollbackServerUpgrade -n <yum_ID>
    The -n option prevents the rollback of the database, which was done in the previous step.