Updating Search Anywhere Framework

Caution!

This instruction describes the process of updating Search Anywhere Framework from version 6.1.* to 6.2.*.

Important Note!

For proper operation of notes and other features, you must:

1. Create the $OS_HOME/uploads directory on SA Data Storage nodes
2. Set ownership to the user running SA Data Storage
3. Mount a shared network folder to this directory

Refer to the configuration guide for setup instructions.

Information

Conventions:

• SAF_INSTALLER - the directory where the Search Anywhere Framework version 6.2 installation package is unpacked
• USER - a system user with administrator rights, usually admin
• OS_HOME - the OpenSearch home directory, usually /app/opensearch/
• OS_DATA - the directory where indexed data is stored, usually /app/data/opensearch
• OS_IP - IP address of one of the OpenSearch cluster servers
• 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://$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 6.2.

Let's consider the update procedure for each component. The 6.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.

Recommended Actions

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

• The config directory, usually $OS_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 $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

Updating OpenSearch

The Search Anywhere Framework 6.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 saf-installer-*.tar.gz -C /app/distr/
SAF_INSTALLER=/app/distr/saf_6.2

Note!

For clusters consisting of multiple nodes, it is recommended to disable allocation before upgrading. This can be done through the Dev Tools console (Main Menu - System Settings - Dev Tools) 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:

• 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 script automates the update process and is located at $SAF_INSTALLER/opensearch/setup.sh. To update, either pass the update action when running the script, or run the script without arguments and select the appropriate option from the interactive menu:

Select action [default: update]:
  1) install
  2) update
  3) uninstall

Action [update]:

The script supports the following startup parameters:

• <action> - action to perform: install, update, or uninstall
• -c, --config <path_to_config_file_yaml> - specify the configuration file for the update
• -h, --help - displays help information about available commands

Example configuration file: $SAF_INSTALLER/opensearch/example_config_opensearch.yaml. The YAML file format is similar to the configuration file used during installation.

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/setup.sh update

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_6.2/opensearch

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

New version OpenSearch: 3.5.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 that require privilege escalation. However, we recommend switching to the root user for the update.

Important Note!

It is impossible to completely perform the update without root privileges, part of operations need to be performed as root user, then run the installer as the user under which OpenSearch operates, after the script finishes, some operations need to be performed again as root user. The list of operations will be displayed in the installer.

If commands are not executed before updating, data loss is possible.

You can run the installer as opensearch user with the following command:

sudo -u opensearch $SAF_INSTALLER/opensearch/setup.sh update

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_6.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:

1. Disable allocation before updating
2. 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.5.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.5.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_6.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).

Important Note!

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:

• curl
• zip
• unzip

The script automates the update process and is located at $SAF_INSTALLER/opensearch-dashboards/setup.sh. To update, either pass the update action when running the script, or run the script without arguments and select the appropriate option from the interactive menu:

Select action [default: update]:
  1) install
  2) update
  3) uninstall

Action [update]:

The update script supports the following parameters:

• <action> - action to perform: install, update, or uninstall
• -c, --config <path_to_config_file_yaml> - Specifies the configuration file for the update
• -h, --help - Displays help information about available commands

Example configuration file: $SAF_INSTALLER/opensearch-dashboards/example_config_dashboards.yaml. The YAML file format is similar to the configuration file used during installation.

The script creates backup copies of the systemd service file, opensearch-dashboards.yml, and the configuration directory in the temporary $SAF_INSTALLER/opensearch-dashboards/staging/ directory. The script does not modify the data or logs directories.

Important!

If the script is run again, the staging directory is cleared and the previous backup is lost. If you need the backup, copy it from this directory before rerunning the script.

To update, run the script:

$SAF_INSTALLER/opensearch-dashboards/setup.sh update

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_6.2/opensearch-dashboards

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

Current version of OpenSearch-Dashboards: 3.5.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.

Important Note!

A complete update cannot be performed without root privileges. You must:

1. Execute some operations as the root user
2. Run the installer as the SA Web runtime user
3. After script completion, perform additional operations again as root The 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/setup.sh update

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_6.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.5.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_6.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.

Important

To correctly restore cluster operation and clear the accumulated resource load after all nodes have been updated, stop the nodes in the following order: SA Data Storage Hot, SA Data Storage Cold, SA Master Node. Then start the nodes in the following order: SA Master Node, SA Data Storage Hot, SA Data Storage Cold.

Post-Update Actions

Migrate Limit Settings

After upgrading to version 6.2.0 and restarting the OpenSearch nodes, migrate the cluster limit settings first, followed by the base, user, and role limit documents. Send the requests without a body. Before starting, back up the current cluster settings and the limits index.

Migrate Cluster Settings

POST _core/migration/6.2.0/migrate_limits/cluster

After the upgrade, previous values may be stored in archived settings. The migration moves five fields:

Old path after upgrade	New path
archived.sme.core.enable_limits	sme.core.limits.enable_limits
archived.sme.core.check_base_limit	sme.core.limits.check_base_limit
archived.sme.core.max_subsearch_hits_count	sme.core.limits.max_subsearch_hits_count
archived.sme.core.list_limit	sme.core.limits.list_limit
archived.sme.core.sort_limit	sme.core.limits.sort_limit

HTTP status	Message or situation	Action
200	Limit settings migrated successfully	Settings were migrated.
200	No limit settings found to migrate.	No old settings were found; nothing changed.
400	Limit settings migration failed due to invalid values: ...	Check and correct the archived values, then retry.
409	Another limit settings operation is already in progress on this node.	Wait for the current operation to finish.
500	Migration or cluster access error.	Resolve the error and check the settings.
503	Limit settings migration was not acknowledged	The cluster did not acknowledge the change; check the stored values before retrying.

Check the result:

GET _cluster/settings?include_defaults=true&flat_settings=true

Confirm that settings under sme.core.limits exist and match the original configuration.

Migrate Base, User, and Role Limits

After checking the cluster settings, run:

POST _core/migration/6.2.0/migrate_limits/users_roles

The migration processes documents in the index configured by sme.core.limits.index_name (.sm_sme_limits_user by default). Writes are paginated, so an error may occur after some documents have already been saved.

Field	Change
allowed_dt_start, allowed_dt_end	Removed after successful interval conversion.
max_command_ram_usage	Removed without a direct replacement.
max_dt_interval	Added based on the previous time bounds, or preserved if the document was already converted.

max_dt_interval sets the maximum allowed search time range in seconds. The old allowed_dt_start and allowed_dt_end defined the bounds of a time window, so the new setting does not have exactly the same meaning. For example, "allowed_dt_start": "now-7d" and "allowed_dt_end": "now" become "max_dt_interval": 604800. If either bound is missing, the defaults are now-10y for the start and now for the end. Calendar periods are fixed at migration time.

The response contains an array of document results with document (document ID) and message (result). Possible status codes:

HTTP status	Meaning
200	All documents were processed without errors.
404	Documents with limits not found in <index>: the search completed, but no limit documents were found.
409	One or more documents need manual correction; some may already have been migrated.
500	Conversion, read, or write error; some documents may already have been saved and are not rolled back. If both write errors and documents requiring manual correction occur, the response is 500.

Migrated successfully. Converted calendar periods are fixed at migration time. means the document was saved; This document has already been migrated. means no change was needed. Migration requires manual correction: <error> indicates an unsupported value, while Migration failed: <error> indicates a document processing or write error.

For a 409 or 500 response, save the response, identify the affected documents, and inspect their actual contents. Correct unsupported values or resolve the error, then rerun the migration if needed. A repeated run does not recalculate max_dt_interval for documents whose old time bounds have already been removed.

After migration, confirm that successfully processed documents no longer contain allowed_dt_start, allowed_dt_end, or max_command_ram_usage, and that max_dt_interval contains the correct duration in seconds. Documents requiring manual correction should retain their previous values; other user and role settings should remain unchanged.

Migrate File Storage Settings

Starting with version 6.2.0, Incident Manager (IM) and Knowledge Center (KWC) store files through shared connections and module bindings. The old settings are no longer read: without migration, the modules cannot save files or serve previously uploaded files. The storage type and its settings do not change during migration.

Run this request once after the upgrade, without a body:

POST _core/migration/6.2.0/file_storage

The request can be repeated: a binding that already has a connection is not changed. Status 200 means there were no errors; if any module has a failed outcome, the response is 500. Check modules in the response:

outcome	Meaning
migrated	A connection was created and selected in the binding.
already_configured	A connection was already selected; the binding was not changed.
skipped	Old settings are missing or incomplete; see message for the reason.
failed	Migration failed; see message for the reason, such as a connection name already in use.

Example response:

{
  "message": "File storage migration completed",
  "modules": [
    {
      "module": "incident_manager",
      "outcome": "migrated",
      "connection_id": "im_file_storage",
      "message": "Binding now uses connection 'im_file_storage'",
      "warnings": []
    },
    {
      "module": "kwc",
      "outcome": "migrated",
      "connection_id": "kwc_file_storage",
      "message": "Binding now uses connection 'kwc_file_storage'",
      "warnings": ["maxSize is set to 5M: the value of the removed setting plugins.kwc.max_file_size cannot be read, change maxSize in the binding if needed"]
    }
  ]
}

After migration, check module connections and bindings. IM S3 keys are not migrated: save them again under Module Settings - File Storage - Connection Settings. KWC now has a default maxSize of 5M, instead of the previous 20M. For IM without file_max_size, the previous default was 25M. If either module must accept larger files, increase maxSize in its binding.

Active Actions

Version 6.2.0 adds Active Actions. Its scripts and actions can be used in Job Scheduler jobs, manual incident runs, incident workflow transitions, and incident SLAs.

Configure the Main Menu

Remove the obsolete first version of the ASM section using the trash icon to its right. Then open Main Menu - System Settings - Module Settings - General - Menu Settings and click Add Module.

Field	Module value
Item Type	Group
System Name	active-actions
Title	Active Actions
Show	Enabled

Inside the Active Actions group, click Add Section twice to create these pages:

Field	First page	Second page
Item Type	Page	Page
System Name	actions	scripts
Title	Active Actions	Scripts
Show	Enabled	Enabled

Click Save Changes and configure permissions according to your security policy.

Migrate SME Interpreters

New scripts use the script interpreter directory. Interpreters for the script command from the cluster setting sme.core.remote_script.interpreters do not appear there automatically. Run this request once after the upgrade, without a body:

POST _core/migration/6.2.0/script_interpreters

The request can be repeated: entries whose names already exist are skipped. sme.core.remote_script.interpreters is not changed, and the script command continues to use it. If a name occurs more than once, the last entry is used.

Setting entries have the form name::path, for example python3::/usr/bin/python3. Only Python and PyPy interpreters are migrated, including versioned names and python.exe and pythonw.exe. Examples of valid paths are /usr/bin/python3.11, /usr/bin/python3.13t, /opt/pypy/bin/pypy3, and C:\Python311\python.exe. /bin/bash, /usr/bin/node, /usr/bin/ipython, /usr/bin/python3-config, and a path ending in /python/ are not valid. Active Actions currently support only Python scripts.

Status 200 means interpreters were created or already existed; if failed is not empty, the response is 500. Check these response fields:

Field	Meaning and action
created	Created interpreters: name and record ID.
already_exists	Existing record names that the migration did not change.
invalid	Malformed name::path entries or values exceeding the allowed name or path length. Correct the setting and rerun the request, or create the records manually.
not_python	Skipped interpreters for other languages. They continue to work for the script command through the old setting.
failed	Names and creation errors. Resolve the cause and rerun the request; created records will be skipped.

Example response:

{
  "message": "Script interpreters migration completed",
  "created": {
    "py311": "v5Dfh6EBqr6UwvBa8Etk",
    "pypy": "wZDfh6EBqr6UwvBa8kul",
    "venv": "w5Dfh6EBqr6UwvBa9kuy"
  },
  "already_exists": ["python3"],
  "invalid": ["broken"],
  "not_python": ["bash::/bin/bash"],
  "failed": {}
}

Important

The migration skips an interpreter only when its name matches. If you rename a migrated record, a repeated run creates it again under the original name.

Configure SME RE

Active Actions scripts run through SME RE at /sme_scripts/v1. Each SME RE instance needs a list of allowed interpreters and a token store; each OpenSearch node needs the same token in its keystore. Interpreter paths in the directory must match the allowed SME RE paths exactly. Without a token or interpreter configuration, errors may include 401 auth.unauthorized, 422 interpreter.not_allowed, and sme_re.token_missing.

The old /sme_remote_exec/* routes and script command continue to use the sme.core.remote_script.user account and mTLS configured under server.ssl.*. The Sm-Access header no longer bypasses account verification on those routes.

1. Install SME RE from the release package. On startup, it places the script loader and sm_actions package in sme.scripts.loadersDir (./loaders by default). Make sure kill is available in PATH; in minimal images it is provided by procps. A missing command is logged as an error.

2. Generate a random token of at least 32 bytes and store it in the SME RE PKCS12 keystore under an alias starting with scripts-token-. For example:

   openssl rand -base64 32
   JAVA_HOME=${OS_HOME}/jdk/ ${JAVA_HOME}/bin/keytool -importpass -storetype PKCS12 -keystore ${OS_HOME}/utils/sme-re/scripts-tokens.p12 -alias scripts-token-cluster1

   Multiple entries are allowed: all tokens are accepted, and the token alias appears in the call log instead of a username. Do not save the token or keystore password in documentation or command logs.

3. Configure SME RE in application.properties (or pass the same settings at startup):

   sme.scripts.interpreters=${OS_HOME}/utils/python/bin/python3,/usr/bin/python3,/opt/venv/bin/python3
   sme.scripts.auth.keystorePath=${OS_HOME}/utils/sme-re/scripts-tokens.p12
   sme.scripts.auth.keystorePassword=${SME_RE_KEYSTORE_PASSWORD:}

   Point to the actual interpreter binary, such as bin/python3 in a virtual environment. A wrapper or shim may prevent child processes from being stopped when execution times out. Use separate virtual environments for different library sets. A script receives only PATH, LANG, and its own HOME; the administrator installs libraries in the interpreter environment.

4. Set the keystore password in the SME RE service environment, for example with Environment="SME_RE_KEYSTORE_PASSWORD=<keystore password>" in the systemd unit file. Restrict access to that file.

5. Store the same token in the keystore of every OpenSearch node. The primary method is a core request that updates every cluster node and immediately reloads secure settings:

   POST _core/keystore/sm.actions.script.sme_re.token?nodeid=node_with_sme:true
   {
     "value" : "<token>"
   }

   If the keystore is password protected, add "keystore_password": "<password>" to the body. If the key already exists, replace it with a PUT request to the same path. Alternatively, run opensearch-keystore add sm.actions.script.sme_re.token on each node, then run POST _nodes/reload_secure_settings without restarting. Until the token is set, sm-actions-api returns sme_re.token_missing, and the node log shows sm.actions.script.sme_re.token is not set in the node keystore.

6. Check the SME RE addresses in cluster settings. They are shared with the old script command and do not need to be recreated:

   Setting	Default	Description
   sme.core.remote_script.url	["http://127.0.0.1"]	List of SME RE hosts: requests rotate across them and skip unavailable hosts.
   sme.core.remote_script.port	18080	SME RE port.
   sme.core.remote_script.enable_ssl	true	Connect to SME RE over HTTPS.

7. Compare paths in the interpreter directory with sme.scripts.interpreters. If they differ, SME RE returns 422 interpreter.not_allowed.

To verify the configuration, check the following:

• the SME RE startup log has no kill error or No script tokens are accepted warning
• the OpenSearch node log has no warning about sm.actions.script.sme_re.token
• a test script run from Active Actions finishes with status completed

To rotate the token without downtime, add a scripts-token-<label> entry to every SME RE keystore. Then replace the token on OpenSearch nodes with PUT _core/keystore/sm.actions.script.sme_re.token, or manually run opensearch-keystore add -f sm.actions.script.sme_re.token on each node followed by POST _nodes/reload_secure_settings. When the old alias no longer appears in the SME RE log, delete it:

JAVA_HOME=${OS_HOME}/jdk/ ${JAVA_HOME}/bin/keytool -delete -storetype PKCS12 -keystore ${OS_HOME}/utils/sme-re/scripts-tokens.p12 -alias <old_alias>

Migrate Job Scheduler Throttling

In version 6.2.0, each throttling record is stored as a separate document in .sm_throttling_v2. Manual throttling and exceptions were added, and throttle.enabled controls throttling for a job. Version 6.1 stored one document per job with an array of records in .sm_throttling. The new mechanism cannot read these records, so migrate them and add the flag to regular and SP jobs.

Cluster nodes are upgraded one by one, without stopping jobs during the upgrade or migrations. While both versions run, 6.1 nodes use the old index and 6.2 nodes use the new one, which they create on startup. For jobs saved in 6.1, 6.2 nodes treat throttling as enabled when a list of throttling fields is set. The indices do not interfere with each other.

Behavior Before Migration

A 6.2 node cannot see a record created by a 6.1 node until .sm_throttling is migrated. When a job first runs on a 6.2 node, a previously throttled event may pass through the job actions once. The node then creates a record in the new index and throttles subsequent repeats. At most one extra action can occur for each active throttling record.

After all nodes are upgraded, open Main Menu - System Settings - Dev Tools. Run the following requests in order, waiting for each response before starting the next migration. Do not stop jobs.

Add the Throttling Flag to Jobs

POST _core/migration/6.2.0/enabled_throttled

The request adds throttle.enabled to regular and SP jobs that do not yet have it: true if the job has a list of throttling fields, otherwise false. It does not change throttling behavior because 6.2 nodes already compute this value. A repeated run processes only jobs without the flag.

The response has job for regular jobs and sp for SP jobs. job.successful and sp.successful show how many jobs lacked the flag. job.version_conflicts and sp.version_conflicts may be nonzero if jobs were saved during migration. In that case, rerun the request. If it fails, resolve the cause reported in the response first.

Confirm that both requests return "count": 0:

GET .sm_jsc_jobs/_count
{"query": {"bool": {"must_not": {"exists": {"field": "throttle.enabled"}}}}}

GET .smos_jobs_sp_meta/_count
{"query": {"bool": {"must_not": {"exists": {"field": "job_parameter.throttle.enabled"}}}}}

Migrate Throttling Records

POST _core/migration/6.2.0/throttling

The request copies records from .sm_throttling to .sm_throttling_v2 while preserving their expiration times. Expired records are skipped. The old index is neither changed nor deleted. New records created by jobs during migration are already in .sm_throttling_v2 and are unaffected. A repeated run overwrites migrated records with the same values without creating duplicates. If the request is interrupted or fails, resolve the cause and rerun it.

The response reports the number of 6.1 documents read (one per job with throttling records), records migrated, and expired records skipped.

Event Comparison

Version 6.1 did not store event field values, so migrated records are compared with events by hash only. For fractional numbers and nested objects, version 6.2.0 computes the hash differently: such a record will not match, and the event will pass through the job actions once.

For jobs with active throttling records, confirm that repeated events are throttled until the record expires: throttled_events_count in run statistics should be greater than zero.

Check the New Index and Delete the Old One

After a successful migration, count automatically created records in the new index:

GET .sm_throttling_v2/_count
{"query": {"term": {"origin": "auto"}}}

count must be at least the “records migrated” value in the migration response. After checking, delete the old index:

DELETE _core/migration/6.2.0/throttling/legacy_index

The request returns 404 if .sm_throttling is already absent.

Migrate the System SMTP Configuration

In version 6.2.0, the Send Email action without smtp_id uses the system SMTP configuration. It must be created from the 6.1 Job Scheduler mail settings. Until a system configuration exists, 6.2 nodes continue to send mail without smtp_id using the old settings; mail is not lost during a rolling upgrade.

After upgrading all nodes, run:

POST _core/migration/6.2.0/system_smtp

The migration copies the host, port, user, sender address, protocol, and timeout from GET _core/settings/job-scheduler. The password is not migrated: it stays under the existing keystore key and is supplied automatically. If the system SMTP configuration already exists, the migration does not change it. The request can be repeated safely.

Check the system configuration under Main Menu - System Settings - Module Settings - Job Scheduler - SMTP Configurations: its fields should match GET _core/settings/job-scheduler. Click Test Connection and confirm that the connection succeeds. Then test a job with the Send Email action and no smtp_id: the email should be sent, and the email action should have status done in run statistics.

Migrate the System Database Connection

Starting with version 6.2.0, the connection of the Inventory module to PostgreSQL is configured under Main Menu - System Settings - Module Settings - General - System database instead of the postgres block of the module global settings. The old block is no longer read: without the migration, the updated calculation algorithm does not work, and the Inventory initialization page shows a notice that the connection is not configured.

Version 6.1 nodes keep using the postgres block, so run the request without a body after all nodes are updated:

POST _core/migration/6.2.0/inventory_system_db

The migration moves the host, port, database name, user, and timeouts to the system database settings with the same access permissions and removes the postgres block from the Inventory global settings.

HTTP status	outcome	Meaning
200	MIGRATED	The connection settings were migrated.
200	ALREADY_CONFIGURED	The connection was already configured under System database and was not changed; the postgres block was removed from the global settings.
200	SKIPPED	Nothing to migrate; the reason is given in reason: inv_settings has no postgres block means the block is missing or the migration has already run, inv_settings document not found means Inventory was never configured, Inventory plugin is not installed means the module is not installed.
500	FAILED	The migration failed; the reason is given in reason. Fix it and repeat the request.

If the PostgreSQL connection was not configured in version 6.1, configure it manually as described in Connecting to the System Database.

Migrate UBA

Version 6.2.0 changes the UBA data model: objects become inventory assets, object types become categories, and scoring accruals become alerts. The new mechanism cannot read documents from versions 5.3–6.1. The migration is intended to transfer objects, policies, response rules, and active accruals, rebuild profiles, and disable old scoring jobs. One migration is planned for all source versions from 5.3 through 6.1.

Planned POST _core/migration/6.2.0/… requests:

No.	Content	Request path suffix
1	Rule families	uba_rule_families
2	Objects	uba_objects
3	Policies	uba_policies
4	Response rules	uba_reactions
5	Profiles	uba_profiles
6	Alerts	uba_alerts
7	Legacy scoring	uba_legacy_scoring

Migration Under Development

The set of requests and their paths may change. The execution order, result checks, and responses have not been published yet. Do not run the listed requests as a completed migration procedure until confirmed instructions are available.