Updating Search Anywhere Framework

Caution!

This instruction describes the process of updating Search Anywhere Framework from version 4.1.* to 4.2.*.

Information

Conventions:

SAF_INSTALLER - the directory where the Search Anywhere Framework version 4.2 installation package is unpacked.
USER - a system user with administrator rights, usually admin.
OPENSEARCH_HOME - the OpenSearch home directory, usually /app/opensearch/.
OPENSEARCH_DATA - the directory where indexed data is stored, usually /app/data/.
OSD_HOME - the OpenSearch Dashboards home directory, usually /app/opensearch-dashboards/.
PATH_SSL - the location of the certificate, the admin private key, and the ca-cert, usually /app/opensearch/config/.

The first step in updating is to determine the currently installed version of Search Anywhere Framework. This can be done by viewing the module versions on the main page or by running the following command in the command line:

curl https://127.0.0.1:9200/_cat/plugins -k -u $USER

After entering this command, you will need to enter the password for the $USER account. It is recommended to use the admin user.

A detailed list of new features can be found in the article What's New in SAF 4.2.

Let's consider the update procedure for each component. The 4.2 installer needs to be unpacked into a directory, for example, /app/distr/.

Caution!

Before starting work, it is strongly recommended to back up the main configuration files and Security settings.

Important!

After completing the update, be sure to update SAF Beat Manager. The RestAPI has been updated without backward compatibility, so in the menu item Navigation Menu - Settings - SAF Beat Management, the agent list will be empty. Use the SAF Beat Manager update instructions.

Recommended Actions

It is recommended to create a directory, for example, /app/backup, where you should save:

The config directory, usually $OPENSEARCH_HOME/config or $OSD_HOME/config.
The systemd files, usually /etc/systemd/system/opensearch.service and /etc/systemd/system/opensearch-dashboards.service, /etc/systemd/system/sme-re.service.
The file /etc/sysctl.d/00-opensearch.conf.

A copy of the Security settings. This needs to be done once, and requires the certificate and private key of the admin user. (The command below will create a directory with the current date containing the OpenSearch security settings.)

chmod +x $OPENSEARCH_HOME/plugins/opensearch-security/tools/securityadmin.sh
JAVA_HOME=$OPENSEARCH_HOME/jdk/ $OPENSEARCH_HOME/plugins/opensearch-security/tools/securityadmin.sh -backup /app/backup/security_$(date +%Y%m%d) \
  -icl \
  -nhnv \
  -cacert $OPENSEARCH_HOME/config/ca-cert.pem \
  -cert $OPENSEARCH_HOME/config/admin-cert.pem \
  -key $OPENSEARCH_HOME/config/admin-key.pem

Disabling the Inventory Processor

Significant changes have been made to the internal structure of Inventory document storage in version 4.2. To prevent the Inventory Processor from terminating with an error during operation, it is recommended to disable it.

Caution!

Disabling the Inventory Processor must be done before performing the main update. These steps need to be performed once.

Usually, the Inventory Processor runs in a single instance on the first SA Data Storage node with long-term data storage (routing mode cold) using crond on a schedule. You can view the list of crond jobs with the command below:

crontab -l

Comment out the execution of the Inventory Processor and save the changes in crond.

Important!

If the Inventory Processor is not launched from the standard location $OPENSEARCH_HOME/utils/inventory/moduleInventory, then after the update you need to replace the Inventory Processor executable file manually.

Updating OpenSearch

The Search Anywhere Framework 4.2 installer needs to be unpacked into a directory, for example, /app/distr/. The location where you unpack the archive contents will be referred to as $SAF_INSTALLER.

SAF_INSTALLER=/app/distr/saf_4.2

Note!

For clusters consisting of multiple nodes, it is recommended to disable allocation before upgrading. This can be done through the developer console (Navigation Menu - Settings - Dev Console) by executing the following command:

PUT _cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.enable": "none"
  }
}

The same can be done from the terminal with the following command:

curl -XPUT -k -u admin "https://127.0.0.1:9200/_cluster/settings?pretty" -H "Content-Type: application/json" -d '{"persistent":{"cluster.routing.allocation.enable": "none"}}'

When upgrading cluster nodes, do not use the update script to disable allocation. After upgrading all cluster nodes, enable allocation:

PUT _cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.enable": "all"
  }
}

The same can be done from the terminal with the following command:

curl -XPUT -k -u admin "https://127.0.0.1:9200/_cluster/settings?pretty" -H "Content-Type: application/json" -d '{"persistent":{"cluster.routing.allocation.enable": "all"}}'

Automatic Mode

The script requires the following pre-installed packages:

curl
zip
unzip

Note!

If you do not see the message indicating that Search Anywhere Framework has been updated at the end, do not rerun the update script. Take a screenshot of where the script stopped and contact technical support.

The automatic update script automates the update process and is located at $SAF_INSTALLER/opensearch/update.sh. You can specify a configuration file $SAF_INSTALLER/opensearch/example_config_opensearch.yaml when calling the script. The file format is YAML and is similar to the configuration file used during installation.

The update script supports the following launch parameters:

-c, --config <path_to_config_file_yaml> - specify the configuration file for the update
-h, --help - displays help information about available commands

Note!

Start the upgrade with nodes that do not have the master role. Data nodes can connect to older versions of master nodes, but not vice versa.

To start the update, run the script:

$SAF_INSTALLER/opensearch/update.sh

After launching, the script automatically finds the paths to the main directories:

OpenSearch Home Directory - the OpenSearch installation directory, usually /app/opensearch
OpenSearch Conf Directory - the OpenSearch configuration files directory, usually /app/opensearch/config/
OpenSearch Data Directory - the data directory, usually /app/data/
OpenSearch Logs Directory - the logs directory, usually /app/logs/

The update script does not perform any actions with the data and logs directories. The configuration files directory and systemd files will be saved to a temporary directory $SAF_INSTALLER/opensearch/staging/.

Note!

If you run the script again, the staging directory will be cleared.

================================================================================
SEARCH ANYWHERE FRAMEWORK UPDATE SCRIPT - OPENSEARCH
================================================================================

Current working directory: /app/distr/saf_4.2/opensearch

Current name of install's archive: opensearch-2.13.0-linux-x64.tar.gz

New version OpenSearch: 2.13.0

================================================================================
-- STEP 1. INSTALLATION DIRECTORIES

opensearch.service file found. Will get necessary paths from there

Final Opensearch home directory: /app/opensearch
Final Opensearch conf directory: /app/opensearch/config
Final Opensearch data directory: /app/data/opensearch
Final Opensearch logs directory: /app/logs/opensearch
Is this correct? [y/n]:

After entering the directories, you need to confirm the automatically found data by pressing y, or enter your directories manually by pressing n.

In the second step, you need to answer the question about allocation. If you enter y, the script will disable allocation before the update and enable it at the end of the script.

-- STEP 2. CONFIGURE ALLOCATION

Do you want to disable allocation during update? [y/N]: n

You don't want to disable allocation: n
Is this correct? [y/n]:

In the third step, you will need to enter the password for the admin user. The password will not be displayed while typing.

-- STEP 3. GET ADMIN PASSWORD

Enter password for user "admin":

Note!

If you enter an incorrect password, the allocation will not be disabled even if selected in the previous step, and information about the current node will not be displayed. However, the update will not be interrupted.

Then, preparatory actions will be performed before the update. Before applying the update, you will be asked to continue. No changes are made to the system until this point. Some information about the current node and the cluster as a whole will also be displayed.

... (Example output omitted for brevity) ...
!!! AT THIS POINT WE START TO MAKE CHANGES IN OPERATING SYSTEM !!!
Do you want to continue? [y/N]:

Pressing Enter will interrupt the update; press y to continue.

Upon successful completion of the update, you should see the message SEARCH ANYWHERE FRAMEWORK SUCCESSFULLY UPDATED!. Information about the cluster and the current node will be displayed beforehand.

... (Example output omitted for brevity) ...
================================================================================
-- SEARCH ANYWHERE FRAMEWORK SUCCESSFULLY UPDATED!
================================================================================

If for some reason the update script was unable to update some plugins, it will display additional information about these plugins at the end, as in the example above (the text The following plugins cannot be installed).

Note that the update script takes into account the current list of installed plugins on OpenSearch nodes. If you need to install any additional plugins, you should do this manually at the end of the node update.

UpdatingOpenSearch Dashboards

This script automates the OpenSearch Dashboards update process. It requires the following pre-installed packages:

curl
zip
unzip

The automatic update script is located at $SAF_INSTALLER/opensearch-dashboards/update.sh. You can specify a configuration file using $SAF_INSTALLER/opensearch-dashboards/example_config_dashboards.yaml. The file format is YAML and is identical to the installation configuration file.

The update script supports the following parameters:

-c, --config <path_to_config_file_yaml> - Specifies the configuration file for the update.
-h, --help - Displays help information about available commands.

During execution, the script backs up the systemd service file, opensearch-dashboards.yml, and the configuration directory to a temporary directory: $SAF_INSTALLER/opensearch-dashboards/staging/.

The update script does not modify the data and logs directories. The configuration directory and systemd files are backed up to the temporary directory $SAF_INSTALLER/opensearch-dashboards/staging/.

Important!

Running the script again will clear the staging directory.

To update, run the script:

$SAF_INSTALLER/opensearch-dashboards/update.sh

The script automatically detects the main paths on the current server for the following directories:

OpenSearch Dashboards Home Directory - The OpenSearch Dashboards installation directory, typically /app/opensearch-dashboards
OpenSearch Dashboards Conf Directory - The OpenSearch Dashboards configuration directory, typically /app/opensearch-dashboards/config/
OpenSearch Dashboards Data Directory - The data directory, typically /app/data/
OpenSearch Dashboards Logs Directory - The logs directory, typically /app/logs/

Example output:

================================================================================
SEARCH ANYWHERE FRAMEWORK INSTALL SCRIPT - OPENSEARCH DASHBOARDS
================================================================================

Current working directory: /opt/saf_4.2/opensearch-dashboards

Current name of install's archive: opensearch-dashboards-2.13.0-linux-x64.tar.gz

Current version of OpenSearch-Dashboards: 2.13.0

================================================================================
-- STEP 1. INSTALLATION DIRECTORIES

opensearch-dashboards.service file found. Will get necessary paths from there

Final Opensearch Dashboards home directory: /app/opensearch-dashboards
Final Opensearch Dashboards conf directory: /app/opensearch-dashboards/config
Final Opensearch Dashboards data directory: /app/data/opensearch-dashboards
Final Opensearch Dashboards logs directory: /app/logs/opensearch-dashboards
Is this correct? [y/n]:

After the directories are displayed, confirm the information by pressing y, or enter your directories manually by pressing n.

The script then performs preparatory actions for the update. Before applying the update, it prompts for confirmation. Up to this point, no actions affecting the system's operability are performed. Information about the current node and the cluster will also be displayed.

Current list of plugins:
-- smartMonitor
-- smartMonitorColumnChart
-- smartMonitorCyberSecurity
-- smartMonitorDrawio
-- smartMonitorHeatmapChart
-- smartMonitorHtmlChart
-- smartMonitorIncidentManager
-- smartMonitorInventory
-- smartMonitorKnowledgeCenter
-- smartMonitorLineChart
-- smartMonitorLookupManager
-- smartMonitorMitreAttack
-- smartMonitorPDFExport
-- smartMonitorPieChart
-- smartMonitorSingleValue
-- smartMonitorTable
-- smartMonitorUserBehaviorAnalytics

Current version of OpenSearch-Dashboards: 2.13.0

!!! AT THIS POINT WE START TO MAKE CHANGES IN OPERATING SYSTEM !!!
Do you want to continue? [y/N]:

Upon successful completion of the update script, the following message is displayed: SEARCH ANYWHERE FRAMEWORK DASHBOARDS SUCCESSFULLY UPDATED.

Tag Color Scheme Format Update

Version 4.2 introduces changes to the internal structure for storing tag colors. The installer includes a utility for migrating tags. This utility is located in the directory $SAF_INSTALLER/utils/migrations_4.1-4.2/tags_colors_migrations/ and is written in Python. The utility's main requirements are:

Python 3.8+
opensearch-py package

The remaining packages are included in a standard Python installation. A more detailed list of packages is provided below:

certifi==2023.7.22
charset-normalizer==3.3.2
idna==3.4
opensearch-py==2.3.2
python-dateutil==2.8.2
requests==2.31.0
six==1.16.0
urllib3==2.0.7

Note!

The Search Anywhere Framework 4.2 installer includes Python 3.8 with the required set of packages.

Configuration File

Before running the utility, configure the parameters in the file $SAF_INSTALLER/utils/migrations_4.1-4.2/tags_colors_migrations/default.ini. An example configuration file is shown below:

[server]
host = 127.0.0.1
port = 9200

[user]
name = admin
pass = password

The server.host parameter should specify the IP address of any OpenSearch node. It is recommended to specify a node with the data role and the routing_mode: hot attribute. If the user.pass parameter is omitted, the utility will prompt for the OpenSearch user password interactively.

Utility Launch Parameters

The utility has the following launch parameters:

-c, --config - Configuration file (Optional). Defaults to ./default.ini
-h, --help - Display help information

Running the Utility

To perform the migration, run the utility with the following command:

$SAF_INSTALLER/utils/python/bin/python3 $SAF_INSTALLER/utils/migrations_4.1-4.2/tags_colors_migrations/main.py -c $SAF_INSTALLER/utils/migrations_4.1-4.2/tags_colors_migrations/default.ini

Updating the SAF Theme

The storage format for the Search Anywhere Framework theme has changed in version 4.2. To migrate, open the developer console (Navigation Menu - Settings - Dev Console).

Delete the old style settings:

DELETE _core/settings/styles

Create the new style format:

POST /_core/settings/styles
{
    "theme": "blue",
    "_meta": {
         "id":"styles"
      }
}

Updating Inventory Asset Configurations

In version 4.2, the format for storing base and advanced fields in the Inventory configuration has changed. To migrate, open the developer console (Navigation Menu - Settings - Dev Console).

To create a backup of the Inventory configurations, execute the following in the developer console:

POST _reindex
{
  "source": {
    "index": ".sm_inv_config"
  },
  "dest": {
    "index": "backup_20241001.sm_inv_config"
  }
}

Then delete the index with the Inventory configurations:

DELETE .sm_inv_config

Next, you need to migrate the old configuration format to the new data format. Execute the following command:

POST _reindex
{
  "source": {
    "index": "backup_20241001.sm_inv_config"
  },
  "dest": {
    "index": ".sm_inv_config"
  },
  "script": {
    "source": """def base = []; ctx._source.get("base").forEach(f -> base.add([ "name": f, "display_name": "", "weight": 1])); ctx._source.put("base", base); def advanced = []; ctx._source.get("advanced").forEach(f -> advanced.add(["name": f, "display_name": "", "weight": 0])); ctx._source.put("advanced", advanced);""",
    "lang": "painless"
  }
}

After executing the above command, you can enable the Inventory Processor in crond. Usually, the Inventory Processor runs as a single instance on the first SA Data Storage node with long-term data storage (routing mode cold).

Warning!

If the Inventory Processor is not launched from the standard location $OPENSEARCH_HOME/utils/inventory/moduleInventory, then after the update, you need to replace the Inventory Processor executable file manually.

After successful execution of the previous command and verification that the inventory is running successfully, you can delete the backup:

DELETE backup_.sm_inv_config

Updating the Mitre Role Model

In version 4.2, the format of the Mitre module's role model has changed. To migrate, open the developer console (Navigation Menu - Settings - Dev Console) and execute the following command:

POST .sm_mitre_layers/_update_by_query
{
  "query": {
    "bool": {
      "must_not": [
        {
          "exists": {
            "field": "_permission"
          }
        }
      ]
    }
  },
  "script": {
    "source": """
    void traverseMap(Map map, Map targetMap) {
          for (entry in map.entrySet()) {
            if (entry.getValue() instanceof Map && targetMap.containsKey(entry.getKey())
                && targetMap[entry.getKey()] != null) {
                  traverseMap(entry.getValue(), targetMap[entry.getKey()]);
              } else {
                  if (entry.getValue() == null) {
                    targetMap.remove(entry.getKey());
                  } else {
                    targetMap[entry.getKey()] = entry.getValue();
                  }
              }
          }
    }
    traverseMap(params, ctx._source);""",
    "params": {
      "_permissions": {
        "owner": "admin",
        "read": {
          "roles": [],
          "users": []
        },
        "write": {
          "roles": [],
          "users": []
        }
      }
    },
    "lang": "painless"
  }
}

Updating the Incident Manager Role Model

In version 4.2, the format of the Incident Manager module's role model has changed. To migrate, open the developer console (Navigation Menu - Settings - Dev Console) and execute the following command:

PUT _core/im_settings/incident-manager-settings
{
  "editFields": {
    "reviewer" : {
      "default_value": "empty",
      "values": [
        {
          "text": "Not set",
          "value": "empty"
        }
      ]
    }
  }
}

Information​

Recommended Actions​

Disabling the Inventory Processor​

Updating OpenSearch​

Automatic Mode​

UpdatingOpenSearch Dashboards​

Tag Color Scheme Format Update​

Configuration File​

Utility Launch Parameters​

Running the Utility​

Updating the SAF Theme​

Updating Inventory Asset Configurations​

Updating the Mitre Role Model​

Updating the Incident Manager Role Model​

Information

Recommended Actions

Disabling the Inventory Processor

Updating OpenSearch

Automatic Mode

UpdatingOpenSearch Dashboards

Tag Color Scheme Format Update

Configuration File

Utility Launch Parameters

Running the Utility

Updating the SAF Theme

Updating Inventory Asset Configurations

Updating the Mitre Role Model

Updating the Incident Manager Role Model