Upgrade Splunk App for Enterprise Security to a newer version
Follow these steps to use the Enterprise Security Install App to upgrade from the Splunk App for Enterprise Security 2.x to a newer version.
Step 1. Get the Splunk App for Enterprise Security
2. Click Download App and save the Splunk Enterprise Security Install App (
splunk-app-for-enterprise-security_300.tgz) to your desktop.
3. From Splunk Home, navigate to App > Manage Apps… > Install App from File to add the Install App to your Splunk instance.
Important: If you already have the Enterprise Security Install App on your system, be sure to click Upgrade app. and overwrite the existing app with the newer version when you upload the file.
4. Restart Splunk.
Step 2. Launch the upgrade installer
1. After Splunk restarts, log back into Splunk.
2. Go to Splunk Home and click Enterprise Security Install App.
3. The Install App appears. To perform the upgrade, the installer first needs to disable the current instance of the Splunk App for Enterprise Security. Click Disable to begin.
4. Restart Splunk.
Note: The Splunk App for Enterprise Security includes a setting that forces Splunk Web to run over HTTPS. While disabled you may need to connect to Splunk Web using HTTP instead (
4. Click the click here to continue link when the Splunk restart is complete.
Re-enable the app
Should you, for any reason, choose not to continue with the upgrade and instead want to continue to use the existing version of the Splunk App for Enterprise Security, you must re-enable the app before it can be used.
In order to fully re-enable the Splunk App for Enterprise Security, you must re-enable all of the following apps using Manage Apps:
To do this:
1. From Splunk Home go to Apps > Manage Apps.
2. Click Enable next to each of these apps.
3. Restart Splunk.
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.
Step 3. Evaluate your environment prior to upgrade
1. After restarting Splunk, log back into Splunk. In the Enterprise Security Install App, click 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" for details.
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 for more information.
4. As you make changes to resolve issues, click Recheck to verify that the issue is fixed. Repeat this process as many times as necessary.
5. Click Print Report for a list of the warnings, customizations, deprecated apps, and changes to configuration files associated with the upgrade.
Resolve warnings and conflicts
During an upgrade using the Enterprise Security Install App, you may encounter warnings and conflicts between your 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.
Any warnings associated with your upgrade are shown on this tab. Use the examples in this section to resolve these upgrade warnings.
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.
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
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
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.
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. Click 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
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"
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
Click 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
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.
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:
.conffiles different from latest default version
.confstanzas removed from latest default version
.confattributes 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.
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'
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'
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
These searches have updated search attributes. These are former lookup or summary generating searches that have been replaced with TSIDX generating searches.
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.
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.
Click 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.
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
localdirectory 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.
Step 4. Upgrade Enterprise Security
When you have reviewed each of the tabs and made changes, continue with the upgrade.
Note: If you chose not to continue with the upgrade, you will need upgrade manually.
1. Click Upgrade & Restart to perform the upgrade.
2. Click the click here to continue link when the Splunk restart is complete.
Note: The Splunk App for Enterprise Security automatically enables SSL. The link to Splunk should already provide the correct protocol redirection (
https). If you do not get redirected properly, check the protocol in your web browser (for example: https://localhost:8000).
3. The Enterprise Security Install App should display a message like:
Splunk App for Enterprise Security is up to date. Current version (version:3.0.0, build:xxxx) is installed. You will be notified of future updates.
Do not remove or disable the Enterprise Security Install App.
Step 5. Set up and configure the app
After performing the upgrade, set up the app.
1. Click Splunk to go to Splunk Home.
2. Click the Enterprise Security app.
3. Click Continue to app setup page on the App configuration dialog.
Note: If the upgrade is performed, and the setup procedure is not run, Splunk may display errors on some dashboards.
4. Verify the settings on the Splunk App for Enterprise Security Setup page.
See "Capacity planning for a larger Splunk deployment" in the core Splunk product documentation for more information about capacity planning.
5. Click Save. The Enterprise Security configure page appears.
See the "Steps to configure" in this manual for more details on setting up the Splunk App for Enterprise Security.
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:
This file is located
Note: After completing the upgrade and restarting Splunk, check various parts of the Splunk App for Enterprise Security to see if they are still working as expected. For details about what is new in this release, see "Enhancements" in the Release Notes.
Plan the upgrade
Manual upgrade of Enterprise Security
This documentation applies to the following versions of Splunk® Enterprise Security: 3.0