Upgrade Splunk App for Enterprise Security

This topic describes how to use the Enterprise Security Install App to upgrade an installed version of the Splunk App for Enterprise Security 2.4 or later.

Step 1. Download the Splunk App for Enterprise Security

1. Download the latest Splunk App for Enterprise Security Install app.

2. Choose Download App and save the Splunk Enterprise Security Install App to your desktop.

Important: You must be logged into Splunk Apps with your Splunk.com ID and be a licensed Enterprise Security customer to download the app. If you have issues, contact Splunk Support.

3. On the search head, navigate to App > Manage Apps… > Install App from File to add the Install App to your Splunk Enterprise instance.

4. If you already have the Enterprise Security Install App on your system, you must choose Upgrade app. to overwrite the older app with the latest version.

5. Restart Splunk Enterprise.

Step 2. Launch the upgrade installer

1. After the search head restarts, log back into Splunk Enterprise.

2. Go to Home and choose the Enterprise Security Install App.

3. To perform the upgrade, the installer must disable the current instance of the Splunk App for Enterprise Security. Choose Disable to begin.

4. Restart Splunk Enterprise.

5. Choose click here to continue when the restart is complete.

Step 3. Evaluate your environment prior to upgrade

1. After restarting, log back into the search head. In the Enterprise Security Install App, choose Continue to begin the upgrade.

2. The Upgrade and Compare screen contains tabs with upgrade warnings, customizations, deprecated apps, or changes to the default configuration files associated with the upgrade. Review each of these tabs before continuing with the upgrade. See "Resolve warnings and conflicts" in this topic.

Important: To back out of the upgrade, the prior version of the Splunk App for Enterprise Security must be re-enabled. A description of the procedure is available "here".

3. Use the information in these panels to evaluate your existing configuration and resolve potential conflicts and customizations that could pose a problem during the upgrade. See "Resolve warnings and conflicts" in this topic.

4. If changes are made to to resolve issues before moving on with the upgrade process, choose Recheck to verify that the Enterprise Security Install App finds the fix. Repeat this process as many times as necessary.

5. Choose Print Report for a list of the warnings, customizations, deprecated apps, and changes to configuration files associated with the upgrade. Printing the report is recommended. When you have reviewed each of the tabs and made changes, continue with the upgrade.

Step 4. Upgrade Enterprise Security

1. Choose Upgrade & Restart to perform the upgrade.

2. Choose the click here to continue link when the Splunk Enterprise restart is complete.

3. The Enterprise Security Install App will display a message when complete:

    Splunk App for Enterprise Security is up to date. 
    Current version (version:3.0.x, build:xxxx) is installed.
    You will be notified of future updates. 

Step 5. Finalize the app setup

1. From Home, Choose the Enterprise Security app.

2. Choose Continue to app setup page on the App configuration dialog.

Important: After the upgrade is performed, if the setup procedure is not run there may display errors on some Enterprise Security dashboards.

3. Verify the settings on the Splunk App for Enterprise Security Setup page.

4. Choose Save. The Enterprise Security configure page appears.

Step 6. Validate Enterprise Security

The Splunk App for Enterprise Security upgrade process is now complete. Correlation searches that were disabled during the upgrade will be enabled. The dashboards should be checked to confirm they are functioning normally.

Important: Do not remove or disable the Enterprise Security Install App.

Managing upgrade issues

Resolve warnings and conflicts

During an upgrade using the Enterprise Security Install App, the installer app may provide descriptions of warnings and conflicts between the current installation and the newer version of the Splunk App for Enterprise Security.

The following sections describe the possible issues and the appropriate actions to resolve them.

Upgrade warnings

Any warnings associated with your upgrade are shown on this tab. Use the examples in this section to resolve these upgrade warnings.

A Custom navigation file is detected

This custom navigation file will prevent updates from being deployed with the new navigation. This custom file will be renamed (to default.xml.old) and disabled after the upgrade. Re-enable this custom navigation file to rollback the changes.

Explanation:

The latest version of the Splunk App for Enterprise Security includes major changes to app navigation. If you upgrade from a 2.x version, you have a pre-existing custom navigation for Enterprise Security, most likely an artifact of previous setup tasks that generate a custom, local navigation as a side effect.

If you didn't make any customizations to your navigation, you can ignore this message. The install/upgrade disables the existing custom navigation and deploys the new one. If you have customizations you want to keep, continue with the upgrade. After the upgrade, the new navigation will be used.

To retrieve your previous customizations, refer to the old navigation file, now located: $SPLUNK_HOME/etc/apps/SplunkEnterpriseSecuritySuite/local/data/ui/nav/default.xml.old. You will need to manually map and add the earlier customizations into the new default.xml navigation file.

Invalid Savedsearches.conf Attribute Settings

Example:

File: $SPLUNK_HOME/etc/apps/SA-NetworkProtection/local/aggregate.conf

Network - Policy Or Configuration Change - Rule ==> 
duration :: -86400 - ERROR: 'duration' less than 1 second group_by ::
 - ERROR: 'group_by' cannot be empty

Explanation:

These conflicts apply to the detection and conversion of correlation search aggregation settings. These errors only apply to ES 2.0.* upgrades, which used the correlation search aggregate framework, and correspond to invalid custom settings with that older framework. The change needed to fix each error is shown in the detected error message.

Example:

Network - Policy Or Configuration Change - Rule ==> 
duration :: -86400 - ERROR: 'duration' less than 1 second
group_by :: - ERROR: 'group_by' cannot be empty

Errors show the correlation search stanzas and the offending settings for each. Possible errors include:

    duration cannot be less than 1 second
    duration must be an integer
    group by cannot be empty

To resolve the issue, change the local values of settings in their respective stanzas, in the /local/aggregate.conf file before proceeding with the upgrade. Choose the recheck button after you make changes to the aggregate.conf file to verify that the issue is resolved.

Local/Custom Savedsearch overwrites new default search

Example:

File: $SPLUNK_HOME/etc/apps/SA-EndpointProtection/local/savedsearches.conf

Endpoint - Recurring Malware Infection - Rule ==> search :: 
`get_summary(endpoint_summary,Endpoint - All Malware - Summary Gen)` | 
search * | stats dc(date_mday) as day_count by dest,signature | 
search day_count>3 | localop | aggregate search="Endpoint - Recurring Malware Infection - Rule"

Explanation:

You can modify search strings in a saved searches local directory, but if the newer version of the app includes a fix/change in the same saved search, the local version will prevent the new changes from taking effect. The searches detected here are specifically correlation searches and ones that have undergone conversion from the aggregate framework to the per-event-alerting framework.

Splunk recommends that you comment out the existing custom search string in your /local directory. The new search string in the /default stanza will be used. To preserve the existing custom search string, you will need to reconcile the differences between the existing search logic and the new analogous search string in the /default stanza.

Customizations

Choose Customizations to see what local customizations may be lost during the upgrade. This tab identifies local customizations in .conf files in the Splunk App for Enterprise Security that may prevent new default content from taking effect. The Install App searches for modifications to configuration files in default and local directories and displays any custom configuration conflicts that may occur with the newer version of the app.

Changes to configuration files should always be performed in an equivalent file within the local sub-directory. User customizations made to default objects are not saved and will be overwritten during the app upgrade.

Warning: If you chose to move forward with the upgrade, the files listed will be overwritten and any customizations will be lost.

For guidance on modifying default files versus local files, see "About the default files" in the core Splunk Admin Manual.

The Splunk configuration file layering system gives local .conf settings precedence over default .conf settings. If a setting's value changed in the new release and there is an existing local setting, this prevents new functionality or fixes.

The reporting hierarchy for .conf files is as follows:

- removed file
- modified file
  - removed stanza
  - modified stanza
    - removed attribute setting
    - modified attribute setting

This information is presented this way in the panel:

• Local .conf files different from latest default version
• Local .conf stanzas removed from latest default version
• Local .conf attributes different from latest default version
• TSIDX Conflicts
• Navigation Lite View Differences

Conflicting deprecated local .conf files

The detected local customized files that are deprecated from the latest release. We recommend that you remove these files, as they no longer exist in default. Examine the files to determine if anything needs to be backed up.

Example:

Conflicting Deprecated Local .conf Files
file: SA-IdentityManagement/local/correlationsearches.conf

Conflicting modified local .conf files

The upgrade process may detect local configuration files that have stanza and attribute conflicts.

• Deprecated Stanzas: These stanzas no longer exist in the latest release. We recommend that you remove this stanza from the 'local' .conf file

deprecated stanza(s): file: SA-EndpointProtection/local/savedsearches.conf
> stanza: [Endpoint - Disk Tracker - Lookup Gen]

• Deprecated Attributes: These attributes no longer exist in the latest release. We recommend that you remove this attribute from the 'local' .conf file

deprecated attribute(s): file: SA-CommonInformationModel/local/macros.conf > stanza: [cim_ids_types]
attribute: errormsg

• Conflicting Attributes: The following attributes have updated default values in the latest release. We recommend that you evaluate whether you want to keep your local customization. You can simply remove it and the default value will override it.

conflicting attribute(s): file: SA-CommonInformationModel/local/macros.conf > stanza: [cim_ids_types]
attribute: definition

TSIDX Conflicts

These searches have updated search attributes. These are former lookup or summary generating searches that have been replaced with TSIDX generating searches.

Example:

TSIDX Conflicts
File: $SPLUNK_HOME/etc/apps/SA-AccessProtection/local/savedsearches.conf
Access - All Account Management - Lookup Gen

Evaluate and determine the significance of your customization. We recommend that you remove this customization to allow the new default search to replace it. See "Tscollect" in the core Splunk Search Reference for more information about TSIDX.

Navigation Lite View Differences

The Splunk app for Enterprise Security 2.0.x included the option of enabling "Lite" dashboards within the navigation. These dashboards have been deprecated in the latest release.

Navigation Lite View Conflicts
File: $SPLUNK_HOME/etc/apps/SplunkEnterpriseSecuritySuite/local/data/ui/nav/default.xml
access_center_lite

We recommend that you remove these links from the navigation.

Deprecated Apps

Choose Deprecated Apps to see any currently installed apps or add-ons, previously shipped with the Splunk App for Enterprise Security, that are deprecated in this release. Some deprecated apps are replaced with a newer app and others are simply left in place. Notes on this tab tell you what the installer will do with each of these apps.

Default .conf

The Default .conf tab shows any modified default configuration files or extension files that have been detected by the Install App.

• Detected Modified Configuration Files: These files have been modified from the original files shipped with the Splunk App for Enterprise Security. These files will be overwritten during the installation. If you want to save the modified files, copy the files to an appropriate location (like the local directory on your system).

Warning: If you chose to move forward with the upgrade, the modified configuration files listed will be overwritten and any customizations will be lost.

• Detected Extension Files: These files are new 'extension' files detected by the Install app. They will be unaffected by the upgrade.

Backup of the upgrade

The Enterprise Security Install App creates a backup of the Splunk App for Enterprise Security installation after the upgrade completes. The folder and ZIP file of the Enterprise Security installation are located at:

  $SPLUNK_home/etc/apps/ess-backup-yyyy-mm-dd-hh-nn-ss

This file is located $SPLUNK_HOME/etc/apps/.

Re-enable the app

To back out of the upgrade, the prior version of the Splunk App for Enterprise Security must be re-enabled before the app can be used.

In order to fully re-enable the Splunk App for Enterprise Security, you must also re-enable all of the following apps in Apps > Manage Apps:

• SA-*
• TA-*
• DA-ESS-*
• Splunk_TA-*
• Splunk_SA-*
• SplunkEnterpriseSecuritySuite

To do this:

1. After logging in, go to Home and Apps > Manage Apps.

2. Choose Enable next to each of the apps listed above.

3. Restart Splunk Enterprise.

The SA-* and DA-ESS* apps do not contain UI elements; because of this no Enable button shows up on the Splunk Web Home page.

Note: SA-AuditAndDataProtection is among the apps disabled/enabled as part of the upgrade process. If SA-AuditAndDataProtection is in the disabled state, Splunk is accessed via HTTP; if it is enabled, Splunk is accessed via HTTPS.