Splunk® Enterprise

Installation Manual

Splunk Enterprise version 8.2 is no longer supported as of September 30, 2023. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.
This documentation does not apply to the most recent version of Splunk® Enterprise. For documentation on the most recent version, go to the latest release.


About upgrading to 8.2 READ THIS FIRST

This topic describes changes in behavior to note for Splunk Enterprise and Splunk Universal Forwarder when you upgrade to version 8.2. Use the Version drop-down list to choose the product version to which you're upgrading. Lower or higher versions of this topic might present different information than the information for your target version.

Splunk App and Add-on Compatibility

Not all Splunk apps and add-ons are compatible with Splunk Enterprise version 8.2.

  • See the Splunk products version compatibility matrix for information about which versions of Splunk IT Service Intelligence and Splunk Enterprise Security are compatible with this version of Splunk Enterprise.
  • You can visit Splunkbase to confirm that your apps and add-ons are compatible with this version.

If your app or add-on is not compatible with version 8.2, consider delaying your upgrade until a compatible version is available.

Key points for upgrading to version 8.2

The following is a list of important elements that you must consider before upgrading Splunk Enterprise and its components. The sections that follow provide supporting details for these key points. Read through all sections in the topic before you begin your upgrade activities.

  • Migrate your KV store storage engine from the Memory Mapped (MMAP) storage engine to the WiredTiger storage engine to significantly reduce the amount of storage you need and to improve performance. See Migrate the KV store storage engine in the Admin manual to plan your migration.
  • Splunk data collection practices have changed in 8.0 and later. In an effort to provide better support for you, Splunk now automatically opts you in to sharing telemetry data after you upgrade. You can still opt out; see Splunk data collection practices have changed later in this topic to learn how.
  • Adjust your scripts and templates to use Python 3-compatible syntax before you upgrade. See Choose your Splunk Enterprise upgrade path for the Python 3 migration for more information.
  • Use the Splunk Products version compatibility matrix to ensure that any premium Splunk apps and add-ons you run are compatible with version 8.2. If they are not, do not upgrade until compatible versions become available.
  • Upgrading Splunk Enterprise directly to version 8.2 is only supported from versions 8.0.x and 8.1.x. Upgrading a universal forwarder directly to version 8.2 is supported from versions 7.3.x, 8.0.x, and 8.1.x.
  • To upgrade search head or indexer clusters, see Follow specific instructions to upgrade clusters later in this topic.
  • Back up your App Key Value Store (KV Store) databases prior to starting an upgrade. If you run version 7.1 and lower of Splunk Enterprise, you must stop Splunk Enterprise instances first.
  • If you run Linux machines that use the second extended (ext2) file system, upgrade that file system to third extended (ext3) prior to starting an upgrade.

Changes that can potentially break Splunk Enterprise installations

There is no supported method for rolling back an installation to a prior release. Follow the guidance for these critical items to avoid breaking your existing installation during an upgrade.

Change to the search_listener parameter for the search/jobs endpoint

The search_listener request parameter for the Splunk REST API search/jobs endpoint is disabled. This change takes effect in Splunk Enterprise versions 8.1.13, 8.2.10, and 9.0.4.

Plan your upgrade to work with the Python 3 migration

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 8.0, 8.1

Beginning with version 8.1, Splunk Enterprise uses the Python 3 interpreter globally by default. You can choose to revert to Python 2 globally, but Splunk Web supports only Python 3.7. Scripts and templates that depend on Splunk Web must be adjusted to use Python 3-compatible syntax before the upgrade. Python scripts that aren't dependent on Splunk Web either need to be adjusted to use Python 3-compatible syntax, or you need to revert to Python 2. Python 2 will be removed from a future version of . Reverting to Python 2 is a temporary workaround only. See Choose your Splunk Enterprise upgrade path for the Python 3 migration for more information.

Note the following important items:

  • In version 8.1, direct calls to splunk cmd python (and $SPLUNK_HOME/bin/python) are always fulfilled by the Python 3 interpreter. This is true even if you configure your Splunk Enterprise instance so that the default is Python 2.
  • Searches whose results include multi-byte characters will fail in apps that implement a custom search command using the Splunk Enterprise SDK for Python between versions 1.6.5 and 1.6.13, when executed by using Python 3. For more information and workarounds, see issue SPL-194426 in the Known issues topic of the Release Notes.

Splunk Enterprise must be version 8.x or higher to upgrade to version 8.2

Applicable components: Splunk Enterprise and universal forwarder
Applicable OSes: all
Version introduced: 8.2

Upgrading Splunk Enterprise to version 8.2 is only supported from versions 8.0.x and 8.1.x. If you are upgrading from version 7.x or earlier, you must upgrade to version 8.0.x or 8.1.x as an intermediate step before upgrading again to 8.2.x. See Upgrade paths to version 8.2 for more information.

Upgrading a universal forwarder to version 8.2 is supported from versions 7.3.x, 8.0.x and 8.1.x. If you are upgrading from version 7.2.x or earlier, you must upgrade to version 7.3.x, 8.0.x, or 8.1.x as an intermediate step before upgrading again to 8.2.x.

Follow specific instructions to upgrade clusters

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 7.3

To upgrade indexer or search head clusters, follow the upgrade procedure for the type of deployment you have.

On Splunk Enterprise indexer cluster manager nodes, enable maintenance mode before you upgrade

Applicable components: Splunk Enterprise and Splunk Universal Forwarder
Applicable OSes: all
Version introduced: 8.1

Because of changes to bucket data with the release of the latest version of Metrics Store, indexers that run versions of Splunk Enterprise lower than 8.1 cannot handle bucket replications from versions that run 8.1 and higher. Before you upgrade a cluster manager node, ensure it is in maintenance mode first. This is a standard part of the indexer cluster update process.

See Use maintenance mode in Managing Indexers and Clusters of Indexers.

Back up App Key Value Store prior to starting an upgrade

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 7.3

Back up the app key value store (KV store) before any maintenance like an upgrade.

If you are upgrading from version 7.1 or lower, you must stop Splunk Enterprise before you can back up the KV Store databases. Confirm that you have accounted for this downtime in your upgrade planning. See Back up and restore KV store for more information.

Support for the second extended (ext2) file system on Linux has been removed

Applicable components: Splunk Enterprise and Splunk Universal Forwarder
Applicable OSes: Linux
Version introduced: 7.1

Support for the ext2 file system on Linux operating systems has been removed. If you still run the ext2 file system on a Linux machine that runs Splunk Enterprise, you must upgrade that file system to a minimum of ext3 before you start a Splunk Enterprise upgrade.

The Splunk Enterprise credential creation scheme might affect scripted upgrades

Applicable components: Splunk Enterprise and Splunk Universal Forwarder
Applicable OSes: all
Version introduced: 7.2

Splunk Enterprise 7.1 introduced an updated authentication scheme for users that requires that you create a password for the admin account. In version 7.2, the scheme was extended to let you customize administrator credential creation for Splunk Enterprise instances.

This scheme includes additional settings and configuration options, which can affect how you upgrade if you use scripts to automate the upgrade process. You might need to change your upgrade scripts before performing scripted upgrades. Specifically, confirm that you do not pass any illegal arguments to the Splunk CLI for starting or restarting Splunk Enterprise during the upgrade, as this could result in a situation where Splunk Enterprise does not start after the upgrade has finished.

Search head pooling has been removed

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 8.0

Search head pooling has been removed from Splunk Enterprise. This feature, which was replaced by search head clustering, has been deprecated for many years. If you still use search head pooling, then do not upgrade to version 8.0. Consider switching to search head clustering where possible, as soon as possible.

Occurrences that appear to be problems but are not

You might see things happen during or immediately after an upgrade that appear to indicate that the upgrade is not working. In nearly all cases, the occurrences that happen here can be expected.

If the following things occur during the upgrade, let the upgrade continue and do not interrupt it. If they occur immediately afterward, then perform benchmark tests on the deployment and compare to any benchmarks that you set up as part of the first phase of upgrading. Consider involving Splunk Support only if those benchmarks differ by a significant margin.

  • On indexers, memory and CPU usage increases due to the following:
    • New data ingestion pipelines
  • Permissions on the Splunk Enterprise introspection directory might change. Confirm that the user that runs Splunk Enterprise has write permission to the $SPLUNK_HOME/var/log/introspection directory.
  • Deployment servers might push updates to all deployment clients due to app bundle hash recalculations.

CPU and memory usage on indexers increases

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 7.3

By default, new data ingestion pipelines consume more resources when they are enabled.

Permissions on introspection directory might change

Applicable components: Splunk Enterprise and Splunk Universal Forwarder
Applicable OSes: all
Version introduced: 7.3

Confirm that the user who runs Splunk Enterprise has write permission to the $SPLUNK_HOME/var/log/introspection directory.

Deployment servers might push updates to all deployment clients due to app bundle hash recalculations.

Applicable components: Splunk Enterprise and Splunk Universal Forwarder
Applicable OSes: all
Version introduced: 7.3

Scheduled views reaper process might increase disk I/O and CPU usage on startup

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 7.1

When you upgrade to version 7.1 or higher of Splunk Enterprise, a new process runs that checks and removes orphaned scheduled views, such as saved searches or reports that generate PDFs on a schedule. This happens when Splunk Enterprise starts, and might result in increased disk I/O and CPU usage on startup.

Considerations for changed or removed features

The following major features have been changed or removed from this version. If you use features that have been removed, and have not yet migrated off them, consider delaying your upgrade until you have.

The use of SSL compression is replaced with HTTP compression except when forwarding

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 8.2

In an effort to improve scalability and efficiency, the use of SSL compression is no longer enabled by default for SSL communications between Splunk Enterprise instances. The SSL compression is replaced with HTTP compression by default, except when forwarding data over SSL. This change does not prevent the use of SSL compression when negotiating communications over SSL with earlier Splunk Enterprise instances. For example, an earlier client negotiating with a 8.2 instance will still use SSL compression, and a 8.2 client negotiating with earlier servers will use HTTP compression.

This change effects the existing settings:

Setting New default with 8.2 Prior default
server.conf
useHTTPClientCompression
true false
server.conf
useClientSSLCompression
false true
outputs.conf
useClientSSLCompression
true Referenced the server.conf useClientSSLCompression setting (default: true)

If you have modified the useHTTPClientCompression or useClientSSLCompression settings in the past, check your environment to determine if the new defaults will impact your compression settings after an upgrade. Use btool to verify how compression is set in your environment based upon the settings above, and where those changes are made.

If you have explicitly enabled the server.conf setting useClientSSLCompression using a custom app or a local .conf file, after the upgrade both the SSL and HTTP compression will be enabled simultaneously. After the upgrade is complete, verify the useClientSSLCompression setting, and make sure the SSL compression is disabled.


A new setting for versioning Simple XML dashboards

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 8.2

A new setting for versioning Simple XML dashboards is included to support an update to the libraries used by Simple XML. Do not change or set the web.conf setting simplexml_dashboard_create_version. The only supported value is the default simplexml_dashboard_create_version = 1.0. A dashboard that does not have a defined value will default to 1.0.


The default tsidxWritingLevel for indexes has changed

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 8.2

The default tsidxWritingLevel in indexes.conf has changed from 1 to 2 beginning with this release.

Splunk Enterprise 7.2 introduced a new file format and optimizations for tsidx files that resulted in improved search performance through decreased I/O, lowered storage usage, and improved utilization of SmartStore caches. These optimizations are encapsulated in levels, with new levels added in higher releases of Splunk Enterprise. Changing the default tsidxWritingLevel changes the optimizations used by both the index tsidx files and data model accelerations. See The tsidx writing level in the Managing Indexers and Clusters of Indexers manual.


The splunkd.log events now include thread names

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 8.2

The default logging level for splunkd.log events now includes thread names to improve troubleshooting.


An additional option is available when performing a searchable rolling restart for multisite clusters

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 8.2

The new server.conf setting searchable_rolling_site_down_policy improves searchable rolling restart performance when the prerequisites are met.

See How the manager determines the number of multisite peers to restart in each round in the Managing Indexers and Clusters of Indexers manual.

A Splunk Enterprise or universal forwarder installation will no longer create an inputs.conf with the hostname

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 8.1

There's a change in the default installation behavior for Splunk Enterprise and universal forwarder instances. When installing earlier releases, the installation process would determine the hostname and set it in a newly created $SPLUNK_HOME/etc/system/local/inputs.conf file. On 8.1 and later releases, splunkd no longer creates the inputs.conf file during installation. The service checks and sets the hostname as part of the inputs.conf setting host = $decideOnStartup when the service starts.


Some logging categories for the authentication system have changed

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 8.1

As part of overall improvements to support of the Security Assertion Markup Language (SAML) authentication scheme, various logging channels for the Splunk platform authentication system have changed. The logging category names that previously started with AuthenticationManager now begin with AuthenticationProvider. Following an upgrade, review the log.cfg in $SPLUNK_HOME/etc/ to confirm that the names have been changed.


Splunk Enterprise license enforcement change

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 8.1

For license stack volumes of less than 100GB of data per day, Splunk Enterprise will disable search when license limits are violated, after 45 warnings within a 60-day rolling window. For more information, see the License Enforcement FAQ on splunk.com.

The default logging level for audit logs has changed

Applicable components: Splunk Enterprise and Splunk Universal Forwarder
Applicable OSes: all
Version introduced: 8.1

The default logging level for auditing of certain administrative events, information that goes to the _audit index, has been lowered from the INFO level to the DEBUG level. Additionally, you now gain the ability to control the logging level that auditing events happens.

While this is a net positive for most customers due to the lower default verbosity of logging, it also means that some audit events, such as capability checks, are no longer logged by default due to the lower log level. To restore the old behavior, you can configure the Splunk platform logging utility by editing the $SPLUNK_HOME/etc/log-local.cfg file and raising the category.AuditLogger entry from DEBUG back to INFO.

Splunk data collection practices have changed

Applicable components: Splunk Enterprise and Splunk Universal Forwarder
Applicable OSes: all
Version introduced: 8.0

In an effort to provide better support to its customers and improve its products and services, Splunk has changed its data collection practices. After you upgrade, Splunk automatically opts you in to sharing telemetry data. To learn what data Splunk collects, see What data Splunk collects in the Admin Manual.

The change happens when you first log into an instance with an administrator user after the upgrade. You receive a pop-up message that indicates the policy change, and the instance overwrites any existing data-sharing configurations after you acknowledge the pop-up.

You can still opt out of sharing telemetry data at any time. To learn how, see How to opt out in the "Share data in Splunk Enterprise" topic of the Admin Manual.

The "access controls" Splunk Web menu options have changed

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 8.0

The "Access controls" menu item under the "Users and Authentication" header in the Settings menu in Splunk Web has been replaced with individual links to user, role, password, and authentication scheme management.

The default memory resource allocation for workload categories has changed

Applicable components: Splunk Enterprise
Applicable OSes: Linux
Version introduced: 8.0

On upgrade to version 8.x, the default memory resource allocation for the ingest workload category changes from 20% to 100%. This might cause an increase in memory usage in the ingest category after upgrade. The default memory resource allocation for the search and misc. categories remains the same, at 70% and 10%, respectively.

For more information on workload categories, see Configure workload categories in the Workload Management manual.

The "failure to localize search" Splunk Web error message has been replaced with a "partial results" message

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 8.0

When you upgrade to version 8.x and run a search that encounters a localization error, the message that appears in Splunk Web has changed. Instead of displaying a "failure to localize" message, Splunk Web notifies users that the search process might have returned partial results.

Roles with the "install_apps" capability also need the "list_settings" capability to access certain REST endpoints

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 8.0

After you upgrade to version 8.x of Splunk Enterprise, any roles that hold the install_apps capability must also hold the list_settings capability for role users to be able to manage app installations through REST (using the manager/appinstall/<app> endpoint, for example.

Splunk Enterprise forwarders at version 8.x cannot forward metrics data to indexers that run lower than version 8.x

Applicable components: Splunk Enterprise and Splunk Universal Forwarder
Applicable OSes: all
Version introduced: 8.0

There is no support for the forwarding of metrics data from forwarders that run version 8.x to indexers that run version 7.3 or lower. If you need to forward metrics data from a version 8.x forwarder, confirm that all indexers that receive this kind of data also run version 8.x.

Upgraded search head nodes will complain of missing metrics indexes in lower-version indexer nodes

Applicable components: Splunk Enterprise and Splunk Universal Forwarder
Applicable OSes: all
Version introduced: 8.0

If you upgrade your distributed search environment to version 8.x of Splunk Enterprise but keep your indexer nodes at a version below 8.0, your search head nodes will generate alerts about a missing _metrics index when they try to send metrics.log events to those indexers. You cannot work around this problem by adding an _metrics index to the indexer cluster, as the format of the metrics data is different on indexers that run a lower version. Upgrade all Splunk Enterprise components to the latest version where possible.

After an upgrade, configure limits.conf settings on all search head cluster nodes that handle metrics data

Applicable components: Splunk Enterprise and Splunk Universal Forwarder
Applicable OSes: all
Version introduced: 8.0

After you upgrade your search head and indexer clusters to version 8.x of Splunk Enterprise, edit limits.conf on each search head cluster and set the always_use_single_value_output setting under the [mcollect] stanza to false. This lets these nodes use the "multiple measures per metric data point" schema when you convert logs to metrics with the mcollect command or use metrics rollups. This new schema increases your data storage capacity and improves metrics search performance.

In metric indexes only, by default the Splunk software removes rawdata journal files from buckets when they roll from hot to warm

Applicable components: Splunk Enterprise and Splunk Universal Forwarder
Applicable OSes: all
Version introduced: 8.1

Rawdata journal files are not used by metric searches. However, after the optimizations introduced in 8.0, rawdata journal files take up a large amount of the volume of a metrics index bucket. In version 8.1 and later, the Splunk software removes these files from metric index buckets when they roll from hot to warm by default. The software removes the file from /rawdata directory in the bucket and replaces it with a dummy journal file that has no usable data other than the journal header. This reduces the amount of space that metric indexes take up on disk.

This does not apply to metric indexes that have replication enabled (repFactor = auto in limits.conf) for indexer clustering. For more information, or to learn how to disable rawdata journal removal for a specific index, see the description of the metric.stubOutRawdataJournal setting in limits.conf.spec.

Metric data points containing metric names that are empty or composed entirely of white spaces cannot be indexed or searched upon

Applicable components: Splunk Enterprise and Splunk Universal Forwarder
Applicable OSes: all
Version introduced: 8.1

In version 8.1 and later, Splunk Enterprise cannot index metric data points containing metric names that are empty or composed entirely of white spaces. This can happen with ingested metrics data as well as event data that is converted to metrics data through the log-to-metrics sourcetype or some other method.

After the upgrade, Splunk Enterprise searches cannot return metric data points containing empty or white-spaced metric names, if those metric data points were indexed in a previous version of Splunk.

StatsD metric data inputs now produce single-measurement metric data points by default

Applicable components: Splunk Enterprise and Splunk Universal Forwarder
Applicable OSes: all
Version introduced: 8.0.3

For ease of use, by default Splunk Enterprise version 8.0.3 and later converts StatsD metric data into single-measurement metric data points that have one key-value pair for the metric name and one key-value pair for the measurement value. If, prior to 8.0.3, you used StatsD inputs that converted their data to metric data points that could carry multiple measurements, you need to add STATSD_EMIT_SINGLE_MEASUREMENT_FORMAT=false to a stanza for the metric source type in props.conf.

Streaming metric alerts are not available on indexer clusters that run version 7.2 and lower

Applicable components: Splunk Enterprise and Splunk Universal Forwarder
Applicable OSes: all
Version introduced: 8.0

Splunk Enterprise version 8.0 introduces streaming metric alerts, which are evaluated on a continuous basis, and which can reduce the load on your system by enabling similar alerts to share the same search process. There is no support for streaming metric alerts on indexer clusters that run version 7.2 or lower. If you have an indexer cluster and a search head cluster, and you upgrade the search head cluster to version 8.x, you lose the ability to trigger streaming metric alerts for that search head cluster. If you need to retain this ability, upgrade the indexer cluster to version 8.x first.

You can no longer use wildcards in real-time searches that use the mstats command

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 8.0

Beginning with Splunk Enterprise version 8.0, you can no longer use wildcards in real-time searches that contain the mstats command. If you have these kinds of searches, change them so that they no longer use wildcards of any kind, either in aggregation fields or metric names, prior to upgrading

Metrics indexing and search is now case-sensitive

Applicable components: Splunk Enterprise and Splunk Universal Forwarder
Applicable OSes: all
Version introduced: 8.0

The indexing and search schema for metrics data is case-sensitive as of Splunk Enterprise 8.0. Instances of Splunk Enterprise that are lower than 8.0 might encounter problems retrieving results when searching instances that run version 8.0 or higher.

Older, deprecated configuration file settings for knowledge bundle replication have been removed

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 8.0

Many older, previously deprecated settings under the [replicationSettings] stanza in distsearch.conf have been removed. If your configuration uses these settings, consider changing them before you start an upgrade.

Configuration file settings for specifying the mounted bundle option for knowledge bundle replication have changed

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 8.0

The distsearch.conf setting for specifying the mounted bundle option for knowledge bundle replication has changed. Previously, the setting was shareBundles=false. The new setting is replicationPolicy=mounted. If the upgrade process finds the old setting in your configuration files, it converts it automatically to the new setting, so no manual intervention is required on your part.

Workload management adds separate workload categories for different process types

Applicable components: Splunk Enterprise
Applicable OSes: Linux
Version introduced: 7.3

On upgrade to from 7.2 to 7.3 or from 7.2 to 8.0, workload management automatically creates workload categories that allocate resources based on the process type (search, ingest, and misc.), and places existing workload pools in the appropriate workload category, as follows:

  • search: All existing search pools are placed under the search category. The existing default_pool becomes the default_category_pool in the search category.
  • ingest: The existing ingest_pool becomes the default_category_pool in the ingest category
  • misc.: The misc category is created with no pools defined.

For detailed information on upgrading workload management, see Upgrade workload management in the Workload Management manual.

The Splunk credentials scheme might affect new scripted installations

Applicable components: Splunk Enterprise and Splunk Universal Forwarder
Applicable OSes: all
Version introduced: 7.2

While the software retains existing credentials during an upgrade, if you perform scripted installations, those installations might be affected significantly by the new credential scheme. You might need to modify your scripts before you perform scripted installations with version 7.2 and higher of the software. Carefully read the following topics to understand the updated installation process:

For more information on the updated password policy, see Password best practices for administrators.

Additionally, your Splunk administrator might introduce password eligibility requirements that affect you if you change your password after an upgrade. See Configure Splunk password policies in Securing Splunk Enterprise for additional information.

The Django framework has been removed

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 7.3

The Django framework and all its associated components have been removed from the Splunk platform. Apps and dashboards that use this framework will not function anymore. Before you upgrade, confirm that apps and dashboards you regularly use no longer use Django, as an upgrade will render them inoperable.

Updated field alias behavior might result in null values

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 7.2

When you upgrade to a version of Splunk Enterprise that is 7.2 or higher, the behavior of certain field alias configurations changes. This behavior affects events where the alias field is already present before field alias processing takes place.

  • If both the source field and the alias field are present in the event, the search head overwrites the value of the alias field to match the value of the source field.
  • If the alias field is present in the event but the source field is missing or has a null value, the search head removes the alias field from the event.

This is how field aliasing should work in these situations. However, you might have searches that rely on the old field alias behavior. A new ASNEW syntax has been added to enable you to provide the pre-7.2 behavior to your field alias configurations.

The pre-7.2 field alias behavior enabled users to create sets of field alias configurations that matched multiple source fields with one alias field. You can use the ASNEW syntax to continue doing this. A better practice would be to use a calculated field that uses the coalesce function to create a new field that takes the value of one or more existing fields. This method lets you be explicit about ordering of input field values in the case of null fields. For example: EVAL-ip = coalesce(clientip,ipaddress).

See Field alias behavior change in the Release Notes for further details.

Splunk Enterprise meters metric data points under 150 bytes by volume on a scale that is similar to the scale used for event data

Applicable components: Splunk Enterprise and Splunk Universal Forwarder
Applicable OSes: all
Version introduced: 7.3

There is a change to the way that Splunk Enterprise meters metrics data in version 7.3. Prior to this release, all metric data points counted against the license as if they were a flat 150 bytes. As of 7.3, Splunk Enterprise meters each metric data point that measures less than 150 bytes by volume on a scale that is similar to the scale used for event data. This scale is capped at 150 bytes. Metric events with volumes over 150 bytes are metered as if they are only 150 bytes. As a result, license usage for such events might be lower than in prior release.

For additional information on licensing, see How Splunk Enterprise licensing works in the Admin Manual.

The tstats command now reports the actual number of matched events in an index bucket as the scan count of those events

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 7.3

The tstats search command, which performs statistical queries on indexed fields in tsidx files, has updated behavior with regard to the number of events it finds in a bucket.

Previously, the command reported the scan count of events in a bucket. After an upgrade, the command now reports the actual number of matched events in a bucket as the scan count. If you use tstats for searches, you might see scan counts fall significantly. This does not indicate incorrect results.

Data model searches now only use fields that have been defined within the data model

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 7.1

When you upgrade to version 7.2 or higher of Splunk Enterprise, data model searches can only use field names that have been defined within the data model. Splunk Enterprise no longer automatically extracts field names. Knowledge objects that depend on such fields will require the data model to have such fields explicitly added in order to continue working as expected.

Additionally, if you have a data model search that references an automatically extracted field name that contains whitespace, you must work around the fact that data models do not allow field names that contain whitespace.

The default color scheme for choropleth maps has changed

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 7.1

The color scheme for choropleth maps and single-value visualizations has changed in Splunk Enterprise 7.2. Existing visualizations will be retained through the upgrade, but any new visualizations that you create after an upgrade will use the new color scheme.

Modified navigation menus in default Splunk apps will be removed after upgrade

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 7.1

After an upgrade to version 7.2 or higher of Splunk Enterprise, any modifications that you have made to navigation menus in default Splunk apps will be removed.

As a reminder, you should not make edits to default apps or configurations, as they can be and, in nearly all cases, are removed after an upgrade. Edit local configurations rather than making modifications to Splunk default configurations and apps.

Stats percentile results might shift by a few percent

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 7.0


Splunk software computes percentiles and median in stats and related commands (tstats, streamstats, eventstats, chart, timechart, sistats, sichart, sitimechart) using an approximation algorithm, unless you use the exactperc aggregation function. In versions lower than Splunk Enterprise 7. , these commands used an approximation algorithm called rdigest. After you upgrade, the default digest behavior changes to tdigest, which has been shown to be more performant than rdigest in some cases, and for metrics data in particular.

Reports that use percentiles and medians might emit slightly different results upon an upgrade to Splunk Enterprise 7.x. The difference is usually small (less than 1%) but could be greater for highly skewed datasets. After the initial shift, stats continues using the new digest method and does not produce another shift unless you switch back to using the rdigest method.

If you want, you can revert the digest behavior globally in limits.conf. The behavior for stats, tstats, streamstats, eventstats, chart, and timechart are controlled by the setting in the stats stanza. The behavior for sistats, sichart, and sitimechart are controlled by the setting in the sistats stanza.

See limits.conf.spec in the Admin Manual.

You can no longer use disabled lookups in searches or other lookups

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 7.0

You can no longer use a disabled lookup as part of a search or other lookup. After you upgrade, when you attempt to use a disabled lookup, you receive the error message The lookup table '<lookup name>' is disabled.

Considerations for new features

Splunk has introduced the following new features in this version of Splunk Enterprise. You might need to perform some configuration after an upgrade to enable and take advantage of these features.

New configuration settings for importing structured data files

Applicable components: Splunk Enterprise and Splunk Universal Forwarder
Applicable OSes: all
Version introduced: 8.0

Splunk Enterprise 8.0.0 and higher has added some new settings for configuring the indexing of structured data. Previously, the structured data processor converted characters that it encountered in header field names that were neither alphanumeric nor a space into underscores. With the new HEADER_FIELD_ACCEPTABLE_SPECIAL_CHARACTERS setting in props.conf, you can control which characters the processor accepts as valid in header field names. Some characters might cause the processor to malfunction, so if you import lots of structured data and want to use the feature, use a test index to confirm that the processor imports the data in the way you want.

Systemd support boot-start

Applicable components: Splunk Enterprise and Splunk Universal Forwarder
Applicable OSes: Linux
Version introduced: 7.2.2

Splunk Enterprise 7.2.2 and higher adds broad support for systemd on Linux with an updated enable boot-start command that lets you automatically configure systemd to manage splunkd as a service. Use of systemd changes the commands used for managing the Splunk processes and requires non-root users to have certain sudo capabilities. These differences may require changes to any scripting, automation, or support documentation.

See Run Splunk Enterprise as a systemd service for instructions.

Splunk Enterprise uses a new cipher suite and message authentication code for inter-Splunk communication

Applicable components: Splunk Enterprise and Splunk Universal Forwarder
Applicable OSes: all
Version introduced: 7.2

Splunk Enterprise 7.2 introduced a new cipher suite and message authentication code (MAC) that replaces the existing cipher suite that was responsible for securely handling inter-Splunk communications.

The new suite and MAC are not compatible with the old suite. Splunk instances that run version 7.2 and higher of Splunk software have been configured by default to allow inter-Splunk communication using both the new and old suites. However, if you later configure a 7.2 or higher instance to run only the new suite and MAC, inter-Splunk communication between versions that run only the old suite is not possible. You cannot configure lower versions of Splunk software to use the new suite.

For more information about the changes, see Configure secure inter-Splunk communications with updated cipher suite and message authentication code in Securing Splunk Enterprise.

HTTP Event Collector now cleans up idle indexer ACK channels by default

Applicable components: Splunk Enterprise and Splunk Universal Forwarder
Applicable OSes: all
Version introduced: 7.1

After an upgrade to version 7.2 of Splunk Enterprise, the HTTP Event Collector now cleans up any indexer ACK channels it finds that have an idle time of more than maxIdleTime seconds, as defined by that setting in the inputs.conf configuration file, by default. While this results in improved HEC performance, you might experience a slight increase in network and CPU activity during the cleanup.

The ability to customize the number of reports retrieved might reduce browser performance

Applicable components: Splunk Enterprise
Applicable OSes: all
Version introduced: 7.0

You can now increase or decrease the number of reports that Splunk Web can retrieve at a time by modifying an entry in web.conf. If you increase the number of reports that can be retrieved after you upgrade, you might cause problems with browser performance due to the number of reports available.


Learn about known upgrade issues

To learn about any additional upgrade issues for Splunk Enterprise, see the Known Issues - Upgrade Issues page in the Release Notes.

Last modified on 07 July, 2023
How to upgrade Splunk Enterprise   How to upgrade a distributed Splunk Enterprise environment

This documentation applies to the following versions of Splunk® Enterprise: 8.2.0, 8.2.1, 8.2.2, 8.2.3, 8.2.4, 8.2.5, 8.2.6, 8.2.7, 8.2.8, 8.2.9, 8.2.10, 8.2.11, 8.2.12


Was this topic useful?







You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters