000035655 - ESA alert migration instructions for upgrading to RSA NetWitness Logs & Network 11.0 from version 10.6.4.x

Document created by RSA Customer Support Employee on Oct 23, 2017Last modified by RSA Customer Support Employee on Nov 28, 2018
Version 4Show Document
  • View in full screen mode

Article Content

Article Number000035655
Applies ToRSA Product Set: NetWitness Logs & Network, Security Analytics
RSA Product/Service Type: Event Stream Analysis (ESA)
RSA Version/Condition: 10.6.4.x, 11.0
Platform: CentOS
IssueCustomers who were not using Incident Management (IM) in RSA Security Analytics 10.6.4.x are not able to view old ESA alerts in RSA NetWitness Respond after migrating to version 11.0. 
ResolutionThe ESA Alert Migration script will move ESA Correlation Rule alerts from the local ESA MongoDB backup from 10.6.4.x to the central MongoDB alert database on the ESA Primary Server host in RSA NetWitness Logs & Network 11.0. While running the script, you have the option to move some or all of your ESA alerts.

Caution: Consider carefully whether you want to migrate your old ESA 10.6.4.x alerts to RSA NetWitness Logs & Network 11.0. The ESA Alert Migration script can take a very long time to finish and can cause performance issues in RSA NetWitness Respond.



  • Determine whether you need to run other programs simultaneously while running this script. This script requires user input, so you must run it in the foreground. If you want to simultaneously run other programs, GNU screen is required.
  • Locate the mongodb.tar.gz file. An ESA Alert backup tar file is created during the upgrade to version 11.0 of the RSA NetWitness Platform. The dump archives are usually located in the /var/netwitness/database/nw-backup directory on the host where the ESA database was configured in 10.6.4.x. An example name of a backed up Mongo tar file for ESA is NWAPPLIANCE29973- Before running the migration script, ensure that the mongodb.tar.gz file is on the ESA Primary host in 11.0. If it is not there, copy the mongodb.tar.gz file to the ESA Primary host.

    NOTE: This is important. If you had multiple ESA services configured in 10.6.4.x, there will be multiple mongo*.tar.gz files on each of the hosts. You only need to copy the one from the host where the ESA database was configured. (This host will usually be the one where you had the Context Hub service running in 10.6.4.x.)

  • Unzip the mongodb.tar.gz file. Unzip this file prior to the procedure using the following command:

    tar xvzf <mongodb.tar.gz_filename>

    After you extract the tar file, you will find a directory named dump. The binary dump is located at /dump/esa/alert.bson.  In the procedure, you will add the dump file path (dumpPath) to the script.properties file. For example:


  • Disable ALL Incident Rules in RSA NetWitness Suite 11.0. Go to CONFIGURE > Incident Rules > Aggregation Rules tab. Disable all of the incident rules. Rules that are enabled show a green circle. Disabled rules show a white circle. To disable a rule, select the checkbox in front of the rule and select the edit icon. Clear the Enabled checkbox and click Save.


  1. Download the ESA alert migration script files attached to this article.
    migration_script.jarThis is the ESA Migration script.
    script.propertiesThis file changes the script settings. The script.properties file must be in the same directory as the migration_script.jar when you run the script.
    script-sample.propertiesA sample script.properties file is provided for your reference.

  2. Edit the script.properties file and add the following required properties.
    Required PropertiesDescription
    dumpPathEnter the absolute or relative path to the location of the dump file that you extracted from the dump archive file. For example:


    esaVersionEnter the previous ESA version from which you are migrating. For example:


  3. (Optional) You can edit the script.properties file and add the following optional property, but it is not required.
    Optional PropertyDescription
    ratePerMinute(Optional) Enter the rate at which alerts must be published. The default is 400 alerts per minute.

    Caution: Increasing the ratePerMinute value decreases the time needed to run the script, but it will cause performance issues in NetWitness Respond and could lead to system failure. Any changes that you make to the ratePerMinute property are made at your own risk.


  4. On the ESA Primary Server host, run the following command to create a screen session named migration.

    screen -S migration

    NOTE: After you run the script, you will be presented with alert statistics and you will have the option to terminate the script in case you decide not to migrate your 10.6.4.x ESA Alerts. You can force quit the script at any time by pressing Ctrl + C.

  5. Inside the screen session, run the script in the foreground using the following command:

    java -jar migration_script.jar

    The script runs in the foreground. It performs a scan on the dump file and shows you the following statistics when the scan is complete:

    • Size of the Dump file
    • Number of Alerts
    • Date Range of the Alerts
    • Estimated Time of Completion

  6. To work on other tasks while the script is running, detach the screen. To do this, press Ctrl + a and then press d. The script runs in the foreground on the detached screen.
  7. To check the status of the script, reattach the screen and run the following command:

    screen -r migration

  8. Follow the prompts on the screen:
    • To publish the whole alert dump, enter y.
    • To specify a smaller date range, enter n. Enter the new date range and enter y. The scan runs again and provides statistics for alerts in the new date range. To publish the alerts in the selected range, enter y. If you want to change the date range again, select q to quit, and run the script again starting with step 5.
    • To quit, enter q.


After alert publishing begins, a script.prog file is created in the current directory to track migration progress. If you stop the migration for any reason, you can resume it by running the commands again starting with step 5. If you want to abort the job and restart with different dates, you need to DELETE the script.prog file and then run the commands again starting with step 5.