Updating Search Anywhere Framework
This instruction describes the process of updating Search Anywhere Framework from version 5.1.* to 5.2.*.
Seamless upgrade to version 5.2.0 without stopping the cluster is only supported when upgrading from Search Anywhere Framework version 5.1.2. The Cross Cluster Search functionality requires using Search Anywhere Framework version 5.1.2 or higher and OpenSearch version 2.19.0 or above.
For proper operation of notes and other features, you must:
- Create the
$OS_HOME/uploadsdirectory on SA Data Storage nodes - Set ownership to the user running SA Data Storage
- Mount a shared network folder to this directory
Refer to the configuration guide for setup instructions.
Information
Conventions:
SAF_INSTALLER- the directory where theSearch Anywhere Frameworkversion 5.2 installation package is unpackedUSER- a system user with administrator rights, usuallyadminOS_HOME- the OpenSearch home directory, usually/app/opensearch/OS_DATA- the directory where indexed data is stored, usually/app/data/opensearchOS_IP- IP address of one of the OpenSearch cluster serversOSD_HOME- the OpenSearch Dashboards home directory, usually/app/opensearch-dashboards/PATH_SSL- the location of the certificate, theadminprivate key, and theca-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://$OS_IP: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 5.2.
Let's consider the update procedure for each component. The 5.2 installer needs to be unpacked into a directory, for example, /app/distr/.
Before starting work, it is strongly recommended to back up the main configuration files and Security settings.
Recommended Actions
It is recommended to create a directory, for example, /app/backup, where you should save:
- The
configdirectory, usually$OS_HOME/configor$OSD_HOME/config - The
systemdfiles, usually/etc/systemd/system/opensearch.serviceand/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 $OS_HOME/plugins/opensearch-security/tools/securityadmin.sh
JAVA_HOME=$OS_HOME/jdk/ $OS_HOME/plugins/opensearch-security/tools/securityadmin.sh -backup /app/backup/security_$(date +%Y%m%d) \
-icl \
-nhnv \
-cacert $OS_HOME/config/ca-cert.pem \
-cert $OS_HOME/config/admin-cert.pem \
-key $OS_HOME/config/admin-key.pem
Actions before updating
Migrating indexes with the index.version.created_string parameter 7.X.X
If migrations from Elasticsearch 7.x or OpenSearch 1.x have been performed on the cluster, index migration must be performed before updating.
The installer includes a utility for migrating index versions. The utility is located in the $SAF_INSTALLER/utils/migrations/migrations_5.1-5.2/check_old_indices/ directory and runs on Python. The main requirements for the utility are:
- Python 3.8+
- The opensearch-py plugin
The Search Anywhere Framework 5.2 installer includes Python 3.8 with the required set of packages.
Configuration File
Parameters:
server.host- OpenSearch addressserver.port- OpenSearch portuser.name- OpenSearch usernameuser.pass- OpenSearch user password
Before running the utility, configure the parameters in the $SAF_INSTALLER/utils/migrations/migrations_5.1-5.2/check_old_indices/default.ini file. 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 user account password interactively.
Utility Launch Parameters
The utility has the following launch parameters:
- launch without parameters - output all old indexes
-c,--config- configuration file (Optional). Default is./default.ini-h,--help- output help
Running the Utility
- Check for the presence of indexes requiring migration using the following command:
$SAF_INSTALLER/utils/python/bin/python3 $SAF_INSTALLER/utils/migrations/migrations_5.1-5.2/check_old_indices/main.py -c $SAF_INSTALLER/utils/migrations/migrations_5.1-5.2/check_old_indices/default.ini
If no indexes are found, migration is not required.
- To perform migrations, run the utility with the
--migrateflag using the command:
$SAF_INSTALLER/utils/python/bin/python3 $SAF_INSTALLER/utils/migrations/migrations_5.1-5.2/check_old_indices/main.py -c $SAF_INSTALLER/utils/migrations/migrations_5.1-5.2/check_old_indices/default.ini --migrate
The .opendistro_security indexes (necessarily with the dot at the beginning of the name) require a special reindexing procedure. For this you need:
- Back up the index using the following command:
JAVA_HOME=$OS_HOME/jdk/ $OS_HOME/plugins/opensearch-security/tools/securityadmin.sh -backup /app/backup/security_$(date +%Y%m%d) \
-icl \
-nhnv \
-cacert $OS_HOME/config/ca-cert.pem \
-cert $OS_HOME/config/admin-cert.pem \
-key $OS_HOME/config/admin-key.pem
- Delete the current index using the following command:
JAVA_HOME=$OS_HOME/jdk/ $OS_HOME/plugins/opensearch-security/tools/securityadmin.sh -dci \
-icl \
-nhnv \
-cacert $OS_HOME/config/ca-cert.pem \
-cert $OS_HOME/config/admin-cert.pem \
-key $OS_HOME/config/admin-key.pem
- Restore the index using the
securityadmin.shfile with the following command:
JAVA_HOME=$OS_HOME/jdk/ $OS_HOME/plugins/opensearch-security/tools/securityadmin.sh --configdir /app/backup/security_$(date +%Y%m%d) \
-icl \
-nhnv \
-cacert $OS_HOME/config/ca-cert.pem \
-cert $OS_HOME/config/admin-cert.pem \
-key $OS_HOME/config/admin-key.pem
Updating OpenSearch
The Search Anywhere Framework 5.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.
tar xzf smart-monitor-installer-*.tar.gz -C /app/distr/
SAF_INSTALLER=/app/distr/saf_5.2
For clusters consisting of multiple nodes, it is recommended to disable allocation before upgrading. This can be done through the developer console (Main Menu - System 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://$OS_IP: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://$OS_IP: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:
curlzipunzip
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
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/opensearchOpenSearch 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/.
If you run the script again, the staging directory will be cleared.
================================================================================
SEARCH ANYWHERE FRAMEWORK UPDATE SCRIPT - OPENSEARCH
================================================================================
Current working directory: /app/distr/saf_5.2/opensearch
Current name of install's archive: opensearch-3.2.0-linux-x64.tar.gz
New version OpenSearch: 3.2.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.
At the second step, you need to answer the question about user usage during the update. If no information output is required, enter n; if additional information output is required, enter y.
The user can be used either for information output or for allocation management, consequently requiring different permission sets. For simple information output, the permissions of the sa-monitoringrole are sufficient.
-- STEP 2. GET USER
Do you want to see cluster information or manage allocation? [Y/n] :
Your account must have role "sa-monitoring"
Your account must have permission "cluster:admin/settings/update" for manage allocation
================================================================================
Enter username: admin
Enter password for user "admin":
Is this correct? [y/n]:
At the next step, you can disable all operations requiring privilege escalation to root user rights during the update.
A complete update cannot be performed without root privileges. You must:
- Execute some operations as the
rootuser - Then run the installer as the OpenSearch operating user
- After the script completes, perform additional operations again as
rootThe list of required operations will be displayed in the installer.
Failure to execute these commands before updating may result in data loss.
To launch the installer as the opensearch user, use this command:
sudo -u opensearch $SAF_INSTALLER/opensearch/update.sh
The first prompt will ask about disabling commands requiring root privilege escalation.
Next, you'll need to enter the user and group under which OpenSearch operates.
Following this, information will be displayed listing operations that must be performed before running the update script.
-- STEP 3. DISABLE OPERATIONS WHERE ROOT RIGHTS ARE REQUIRED
Want to update Search Anywhere Framework without root privileges? [y/N]: y
Final you set the non-root flag to: y
Linux username for Search Anywhere Framework [opensearch]:
Linux groupname for Search Anywhere Framework [opensearch]:
Final Search Anywhere Framework username: opensearch
Final Search Anywhere Framework groupname: opensearch
Is this correct? [Y/n]:
ATTENTION!
Before updating Search Anywhere Framework, you must run the following commands as a user with root privileges.
If yo need to disable allocation, run the following command:
curl -XPUT -k -u YOUR_USER_OPENSEARCH:YOUR_USER_OPENSEARCH_PASSWORD_HERE "https://YOUR_IP_OPENSEARCH:9200/_cluster/settings?pretty" -H "Content-Type: application/json" -d '{"persistent":{"cluster.routing.allocation.enable": "none"}}'
Change user, group and directories as needed
systemctl stop sme-re
systemctl stop opensearch
chown -R opensearch:opensearch /app/opensearch /app/opensearch/config /app/data/opensearch /app/logs/opensearch /app/distr/saf_5.2/opensearch
!!! Are you sure you have done everything from the list above? [y/N]:
At the final step, you must confirm that all commands were executed as the root user. Enter y to confirm, otherwise the update will be aborted.
At the next step, if you chose to use a user during the update, you need to answer the allocation question. If you enter y, the script will:
- Disable allocation before updating
- Re-enable it after completing the script operations
-- STEP 4. 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]:
Then preparatory actions will be performed before the update. Before applying the update, a confirmation prompt will appear - until this point, no changes are made to the system. Additionally, some information about the current node and the cluster as a whole will be displayed, if you selected to use a user during the update at step two.
get current list of plugins
sm-core
sm-im
sm-inventory
sm-ism-action-clickhouse
sm-job-scheduler
sm-job-scheduler-actions-incident
sm-job-scheduler-actions-mitre
sm-knowledge-center
sm-mitre
sm-mssp
sm-rsm
sm-uba
sme
opensearch-security
Information about current node OpenSearch:
{
"name" : "smos-node-00",
"cluster_name" : "smos-cluster",
"cluster_uuid" : "yKPPDCHGSA6rHQT948jokQ",
"version" : {
"distribution" : "opensearch",
"number" : "3.2.0",
"build_type" : "tar",
"build_hash" : "99a9a81da366173b0c2b963b26ea92e15ef34547",
"build_date" : "2025-10-29T17:05:01.906258Z",
"build_snapshot" : false,
"lucene_version" : "10.2.2",
"minimum_wire_compatibility_version" : "2.19.0",
"minimum_index_compatibility_version" : "2.0.0"
},
"tagline" : "The OpenSearch Project: https://opensearch.org/"
}
!!! 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!. Preliminary information about the cluster and current node will be displayed, if you selected to use a user during the update at step two.
-- STEP 10. PRINT INFORMATION
current state of cluster
{
"cluster_name" : "smos-cluster",
"status" : "yellow",
"timed_out" : false,
"number_of_nodes" : 1,
"number_of_data_nodes" : 1,
"discovered_master" : true,
"discovered_cluster_manager" : true,
"active_primary_shards" : 50,
"active_shards" : 50,
"relocating_shards" : 0,
"initializing_shards" : 0,
"unassigned_shards" : 15,
"delayed_unassigned_shards" : 0,
"number_of_pending_tasks" : 0,
"number_of_in_flight_fetch" : 0,
"task_max_waiting_in_queue_millis" : 0,
"active_shards_percent_as_number" : 76.92307692307693
}
current state clusters nodes
172.16.0.27 14 99 8 1.47 0.63 0.26 dim data,ingest,master * smos-node-00
Information about current node OpenSearch:
{
"name" : "smos-node-00",
"cluster_name" : "smos-cluster",
"cluster_uuid" : "5V2rIp1sRj-M-ANnGfF0cA",
"version" : {
"distribution" : "opensearch",
"number" : "3.2.0",
"build_type" : "tar",
"build_hash" : "99a9a81da366173b0c2b963b26ea92e15ef34547",
"build_date" : "2025-10-29T17:05:01.906258Z",
"build_snapshot" : false,
"lucene_version" : "10.2.2",
"minimum_wire_compatibility_version" : "2.19.0",
"minimum_index_compatibility_version" : "2.0.0"
},
"tagline" : "The OpenSearch Project: https://opensearch.org/"
}
================================================================================
ATTENTION!
After updating Search Anywhere Framework, you must run the following commands as a user with root privileges.
Change user, group and directories as needed.
cp /app/distr/saf_5.2/opensearch/staging/services/sme-re.service /etc/systemd/system/
chown root:root /etc/systemd/system/sme-re.service
chcon -Rv -u system_u -r object_r -t bin_t /app/opensearch/bin
chcon -Rv -u system_u -r object_r -t bin_t /app/opensearch/jdk/bin
chcon -Rv -u system_u -r object_r -t var_run_t /app/opensearch/run
chown -R opensearch:opensearch /app/opensearch /app/opensearch/config /app/data/opensearch /app/logs/opensearch
systemctl daemon-reload
systemctl enable sme-re opensearch
systemctl start sme-re
systemctl start opensearch
systemctl status sme-re opensearch
If you disable allocation before, wait 60 seconds and run the following commands as a "opensearch" or user with root privileges:
curl -XPUT -k -u YOUR_USER_OPENSEARCH:YOUR_ADMIN_PASSWORD_HERE "https://127.0.0.1:9200/_cluster/settings?pretty" -H "Content-Type: application/json" -d '{"persistent":{"cluster.routing.allocation.enable": "all"}}'
The following plugins cannot be installed:
-- sm-job-scheduler-actions-incident
-- sm-job-scheduler-actions-mitre
================================================================================
-- Search Anywhere Framework SUCCESSFULLY UPDATED!
-- For further instructions, please refer to the documentation: https://docs.saf-systems.com/
================================================================================
If you chose to update without using commands requiring privilege escalation to the root user, an information block will be displayed listing commands that need to be executed as the root user.
If for some reason the update script fails to update certain plugins, it will additionally display information about these plugins at the end (text reading The following plugins cannot be installed).
The update script takes into account the current list of installed plugins on OpenSearch nodes. If you need to install any additional plugins, this should be done manually after completing the node update.
Updating SA Web
This script automates the OpenSearch Dashboards update process. It requires the following pre-installed packages:
curlzipunzip
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/.
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-dashboardsOpenSearch 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_5.2/opensearch-dashboards
Current name of install's archive: opensearch-dashboards-3.2.0-linux-x64.tar.gz
Current version of OpenSearch-Dashboards: 3.2.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.
At the next step, you can disable all operations requiring privilege escalation to root user rights during the update.
A complete update cannot be performed without root privileges.
You must:
- Execute some operations as the
rootuser - Run the installer as the SA Web runtime user
- After script completion, perform additional operations again as
rootThe operation list will be displayed in the installer
Failure to execute these commands before updating may cause data loss.
To launch the installer as the opensearch user:
sudo -u opensearch $SAF_INSTALLER/opensearch-dashboards/update.sh
The first prompt will ask about disabling commands requiring privilege escalation to the root user.
Next, you'll need to enter the user and group under which SA Web operates.
Finally, information will be displayed listing operations that must be performed before running the update script.
-- STEP 2. DISABLE OPERATIONS WHERE ROOT RIGHTS ARE REQUIRED
Want to update SEARCH ANYWHERE FRAMEWORK without root privileges? [y/N]: y
Final you set the non-root flag to: y
Linux username for SEARCH ANYWHERE FRAMEWORK [opensearch]:
Linux groupname for SEARCH ANYWHERE FRAMEWORK [opensearch]:
Final SEARCH ANYWHERE FRAMEWORK username: opensearch
Final SEARCH ANYWHERE FRAMEWORK groupname: opensearch
Is this correct? [Y/n]:
ATTENTION!
Before updating SEARCH ANYWHERE FRAMEWORK, you must run the following commands as a user with root privileges.
Change user, group and directories as needed
systemctl stop opensearch-dashboards
chown -R opensearch:opensearch /app/opensearch-dashboards /app/opensearch-dashboards/config /app/data/opensearch-dashboards /app/logs/opensearch-dashboards /app/distr/saf_5.2/opensearch-dashboards
!!! Are you sure you have done everything from the list above? [y/N]:
At the final step, you must confirm that all commands were executed as the root user. Enter y to confirm; otherwise, the update will be terminated.
Next, preparatory actions will be performed before the update. Before applying the update, you'll be prompted for confirmation - until this point, no system-impacting operations are performed. Additional information about the current node 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: 3.2.0
!!! AT THIS POINT WE START TO MAKE CHANGES IN OPERATING SYSTEM !!!
Do you want to continue? [y/N]:
If the update was selected without using commands requiring privilege escalation to the root user, an information block will be displayed containing the list of commands that must be executed as the root user.
================================================================================
ATTENTION!
After updating SEARCH ANYWHERE FRAMEWORK, you must run the following commands as a user with root privileges.
Change user, group and directories as needed.
cp /app/distr/saf_5.2/opensearch-dashboards/staging/services/opensearch-dashboards.service /etc/systemd/system/
chown root:root /etc/systemd/system/opensearch-dashboards.service
chcon -Rv -u system_u -r object_r -t bin_t /app/opensearch-dashboards/bin
chown -R opensearch:opensearch /app/opensearch-dashboards /app/opensearch-dashboards/config /app/data/opensearch-dashboards /app/logs/opensearch-dashboards
systemctl daemon-reload
systemctl enable opensearch-dashboards
systemctl start opensearch-dashboards
systemctl status opensearch-dashboards
================================================================================
-- SEARCH ANYWHERE FRAMEWORK DASHBOARDS SUCCESSFULLY UPDATED!
-- For further instructions, please refer to the documentation: https://docs.saf-systems.com/
================================================================================
Upon successful completion of the update script, the following message is displayed: SEARCH ANYWHERE FRAMEWORK DASHBOARDS SUCCESSFULLY UPDATED.
Post-Update Actions
Configuring the Main Menu
To do this, open the menu settings (Main Menu - Settings - Management - Navigation). Save the current settings by clicking the Save Changes button.
After saving the settings, two new system sections will appear in the menu: Overview and Main.

To complete the setup, assign the appropriate user role permissions to these sections and click Save Changes.
Changing the System Name for the Sigma Rules List
To configure the system name for the Sigma rules list, open the menu settings (Main Menu - Settings - Management - Navigation). Locate the Sigma Rules group and expand it. Select the List of rules item and specify the value list in the Module Name field.

Task Migration
After a successful upgrade, task migration must be performed.
Before starting the migration, it is recommended to manually create a full backup of the .sm_jsc_jobs index, which contains the jobs.
Execute the following request to start the migration process:
GET _core/migrate/reindex_job
During the migration, backups of the jobs index will be created. After its completion, ensure that all tasks in the scheduler are running correctly.
After verification, you can delete the automatically created backups using the command:
DELETE _core/migrate/backup