Splunk® Enterprise

Installation Manual

Download manual as PDF

Splunk version 4.x reached its End of Life on October 1, 2013. Please see the migration information.
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

About upgrading to 4.3 READ THIS FIRST

This topic is about what you need to know before you upgrade to Splunk 4.3.

What's new and awesome in 4.3?

Check out Meet Splunk 4.3 in the Release Notes for a full list of the new features we've delivered in 4.3.

Review the Known issues in the Release Notes for a list of issues and workarounds in this release.

Always back up your existing deployment first

Get into the habit of backing up your existing deployment before any upgrade or migration.

You can manage your risk by using technology that allows you to restore your Splunk install and data to a state prior to the upgrade, whether you use external backups, disk or file system snapshots, or other means. When backing up your Splunk data, consider the $SPLUNK_HOME directory, as well as any indexes outside of it.

For more information about backing up your Splunk deployment, read the topics beginning with "What you can back up" in the Admin Manual.

Upgrading from 4.0 and later

Splunk supports a direct upgrade from versions 4.0 and later to version 4.3.

If you're upgrading from 4.2.x or later, read the rest of this topic first before proceeding with the installation instructions linked below.

If you're upgrading from 4.1.x to 4.3, Splunk recommends that you also review the 4.2.x version of the topic you're reading now as well as this version before proceeding with the installation instructions:

Migrating from 3.4.x and earlier

Upgrading from version 3 of Splunk to version 4 is a significant, complex undertaking. This is because Splunk versions 4.0 and later have a completely different architecture than Splunk versions 3.x and earlier. For this reason, there is no direct upgrade path from version 3.x to version 4.3. Attempting to upgrade directly from 3.x to 4.3 is unsupported and is strongly discouraged. You should only upgrade to version 4.3 after you have determined that your migration to version 4.0 is stable and complete. Read "Upgrade from 3.x to 4.3" for additional information and instructions.

After you've migrated from 3.4.x to 4.0, you can then upgrade from 4.0 to 4.3 using the UNIX and Windows instructions in this manual.

Upgrade distributed deployments

If you're planning to upgrade your distributed Splunk environment, be sure to read "Upgrade your distributed environment" in the Distributed Deployment Manual for guidance on how to do so with minimal impact.

Upgrade universal forwarders

Upgrading universal forwarders is a different process than upgrading full Splunk. Before upgrading your universal forwarders, be sure to read the appropriate upgrade topic for your operating system:

To learn about interoperability and compatibility between indexers and universal forwarders, read "Indexer and universal forwarder compatibility" in the "Deployment Overview" topic of the Distributed Deployment Manual.

You want to know this stuff

Upgrading to 4.3 from 4.0 and later is pretty simple, but here are a few tips and gotchas:

Changes to how Splunk handles host names retrieved from scripted inputs

In version 4.2 of Splunk, various scripted inputs (in particular, the Windows-based scripted inputs defined in inputs.conf) would generate multiple hostnames that identified a single host. In version 4.3, we've changed that behavior to produce a single name for the computer running these inputs, by identifying various equivalent names for the local system. The inputs recognize when a system name matches one of the equivalent names such as the socket hostname, the NetBIOS-style COMPUTERNAME, or the name defined in server.conf when Splunk is first run on a machine. For all of these cases, the inputs allow the value to be controlled by your choice in inputs.conf.

We've also fixed a bug that sometimes causes invalid hostname generation.

This might impact you if you have searches defined that expect fully-qualified domain names. After you upgrade, if you need to retain the previous functionality, you can specify the desired hostname by using the 'host' attribute on the input in question.

No change to license management

Licenses issued for 4.0-4.1 as well as newer 4.2 XML licenses will both work in 4.3 without change. Regardless of whether you've migrated Splunk or reinstalled it, your existing 4.x licenses will work with 4.3.

If your license is not accepted by Splunk 4.3.x, it is possible that your upgrade rights have expired due to a lapsed maintenance agreement. Contact Splunk Support to reinstate your agreement and upgrade entitlement.

Splunk uses more Unix file descriptors

Splunk 4.3 uses more file descriptors on Unix filesystems than version 4.2 did when monitoring files.

Before you upgrade, consider increasing the number of open file descriptors your system can use with the ulimit command.

Changes to Windows Registry Monitor configuration files

We've changed how Splunk handles Windows Registry monitoring configurations.

On versions of Splunk prior to 4.3, Registry monitoring was configured with two configuration files - sysmon.conf and regmon-filters.conf. The sysmon.conf file contained global settings for which event types to monitor, and the regmon-filters.conf file contained the regular expressions used to filter the Registry keys that Splunk should monitor.

In 4.3, sysmon.conf is deprecated and is no longer shipped. All Registry monitoring configuration now resides in regmon-filters.conf. After you upgrade your Splunk instance and restart Splunk, the Splunk Registry monitoring utility (splunk-regmon.exe) will read your existing sysmon.conf and transfer any relevant configuration values to regmon-filters.conf. It will then mark sysmon.conf as "migrated" and ignore any further updates to this file.

Changes to Windows Registry monitor default behavior

In 4.3, we migrated the defaults for Windows Registry monitoring from core Splunk into the Windows app. If you currently use the Registry monitoring tools in Splunk 4.2, you might be impacted by an issue that arises when you upgrade. Be sure to read "Workaround for Registry monitoring configuration issue" to learn how to address this specific issue.

Note: The previous URL is hard-coded to take you to version 4.3 of the documentation because this issue is resolved in 4.3.1 and later; upgrading from 4.2.x to 4.3.1 and later will not experience this issue.

Changes to Active Directory monitoring configuration file defaults

We made a minor change to the case of the targetDc attribute in admon.conf. If you are using Splunk's Active Directory monitoring utility, you might see a warning that Splunk found a typo in this configuration file after you upgrade.

To prevent this notice from occurring, edit admon.conf and change any defined targetDC attributes to targetDc before upgrading.

Note that making this change does not affect how Active Directory monitoring works.

Changes to Windows event log monitoring configuration values

We corrected a minor issue with regard to the acceptable values for the start_from attribute for the [WinEventLog] stanza of inputs.conf. If you use Splunk's Windows event log monitoring inputs, you might be impacted by an issue related to case sensitivity of these values after you upgrade.

The two acceptable values for start_from are oldest and newest. These values must be specified in lower case. Before upgrading, review your inputs.conf to make sure that the values have the proper case.

The Windows app doesn't use the performance monitor collection features

The Windows app still does not use the Windows performance monitor collection features available in Splunk 4.3. While the app does work, and is supported, by default it will continue to gather local performance metrics using WMI-based scripted inputs.

If you want to use the new features, or you're using a universal forwarder to send data with the default performance monitoring data collections to an instance that's running the app, then you'll need to update the searches within the app, based on your defined performance monitoring collections.

You can follow the Windows app on Splunkbase for future updates.

Splunk expects canonical IP addresses in its configuration file stanzas

When editing configuration files such as inputs.conf to define stanzas that contain IP addresses, make sure to use canonical IP address formatting (for example, [tcp://]).

Do not put leading zeros in your IP addresses ([tcp://], as doing so can cause problems with reading and correctly parsing the configuration files.

The accessibility defaults for Splunk Web's single sign-on (SSO) implementation have changed

We've made a change to how Splunk's SSO implementation works. Beginning with Version 4.3, the default mode of Splunk Web's SSO is 'strict' instead of 'permissive'.

The SSOMode attribute in $SPLUNK_HOME/etc/system/local/web.conf defines the mode of accessibility. Strict mode blocks all SSO requests except those that originate from a trusted IP address (See "Use single sign-on with Splunk" for more information.)

If you use Splunk's SSO implementation, and did not explicitly define SSOMode in web.conf, you might experience problems with SSO after you upgrade. To fix the problem, add the SSOMode attribute under the [settings] stanza as follows:

SSOMode = permissive

Splunk timeline now displayed in HTML5 Canvas instead of Flash

We've included a new timeline histogram that is based on JavaScript and HTML5 Canvas by default. This replaces the Flash-based timeline that is present in version 4.2.

After you upgrade, the timeline is by default displayed using Canvas instead of Flash. You might see slight differences in the names of certain elements of the timeline, as well as how the timeline zooms in and out.

If you do not access Splunk Web with an HTML5-capable browser, timelines will continue to display in Flash.

Existing saved searches must be reconfigured to use the new report builder view

If you have saved searches that reference the report_builder view, Splunk might display an error "Cannot find the 'report_builder_display' view" when accessing this search after you upgrade.

If you experience this issue, you can edit savedsearches.conf and change the value of the displayview attribute from report_builder to report_builder_display.

You must restart Splunk in order for this change to take effect.

For more information about defining reports with Report Builder, read "Define reports" in the User Manual.

Dashboards with certain charting properties might not render or display as desired

We've added the ability to display charts based on JavaScript (JSChart) instead of Adobe Flash. This introduces some important considerations when creating or editing charts after an upgrade:

  • Some charting properties are not yet supported by JSChart. As a result, after you upgrade, some charts might display differently than they did before the upgrade.
  • Backward compatibility with Flash is maintained through the upgrade. This means that dashboards with charting properties that are not supported by JSChart will be kept as Flash-based during the upgrade.
  • If Splunk encounters a charting property in a dashboard that is not supported by JSChart, it falls back to rendering the dashboard in Flash.
  • If you view these Flash-based dashboards with a browser that is not capable of displaying Flash, the browser will not display the charts.
  • If you make a change to an existing dashboard outside of Splunk Web, and use a charting property that is not supported by JSChart, you might experience undesirable results in how the dashboard is rendered.
  • Even when the dashboard is properly rendered using JSChart, you might see some charts display incorrectly - particularly those charts that feature row-grouping or have large numbers of categories.

For additional information about how customizing charts in dashboards affects how dashboards are rendered, review "Chart customization and non-Flash chart displays" in the "Advanced charting options" topic of the Developer Manual.

The Panel Editor introduces a new editing workflow for some dashboards

The new Panel Editor changes how you edit some dashboards - in particular, those which use Simple XML. The new editor only edits dashboard properties that are supported by JSChart. There might also be instances where dashboards edited with the new Panel Editor display inconsistently or incorrectly.

For information on the new Panel Editor and how to use it, read "Edit dashboard panel visualizations" in the User Manual.

Simple XML now always has precedence when editing form or dashboard settings

We've fixed a bug where some Simple XML form and dashboard settings were not correctly prioritized when you edited a form or dashboard.

Simple XML settings now always have precedence over settings defined in viewstates.conf that have the same name. This is true whether you edit the form or dashboard using the new Panel Editor, or edit the form or dashboard XML directly.

If you want to use the settings defined in viewstates.conf, you can change the value of the desired setting within the form or dashboard XML, or remove it from the XML entirely.

Changes to LDAP authentication configuration for multi-domain support

We've added functionality for multi-domain LDAP configurations in 4.3.

  • We've made changes to settings in authentication.conf:
    • The authSettings attribute is now a comma-separated list of LDAP strategies.
    • The roleMap attribute is no longer global, but is rather scoped to a specific LDAP strategy. When you upgrade, all 'roleMap' attributes will be renamed according to the strategy that they are defined in.
  • We've made changes to the nomenclature of existing LDAP strategies. When you upgrade to 4.3, any existing LDAP strategies that contain commas (',') will be renamed.

Existing LDAP configurations will be automatically updated to work with these changes as part of migration.

For additional information about using Splunk with multiple LDAP strategies, review "Use multiple LDAP strategies" in the "Set up user authentication with LDAP" topic in the Admin Manual.

Users of LDAP version 2 might experience user configuration issues

We've fixed a bug that caused Splunk's LDAP configuration screen to display LDAP users that could not actually log into Splunk when Splunk was configured to map users to groups by distinguished name (DN). This problem occurred because those users fell outside the scope of the list of user base DNs, as defined by the UserBaseDN attribute in authentication.conf.

If you are using LDAP version 2, Splunk will populate the LDAP user list with only those users who have already successfully logged in to Splunk, as opposed to the full list of users who have login access.

If you are concerned about this, Splunk recommends that you utilize LDAP version 3 in your environment, as it does not cause Splunk to exhibit this anomaly.

Bloom filters get created after upgrading

When you start Splunk after upgrading to 4.3, Bloom filters are created for specific buckets in your Splunk indexes for the most recent 30 days of indexed data. Typically, these filters take up around 10% of the size of an index bucket on disk. You might want to ensure that you have adequate disk space prior to upgrading, to address the increased overhead.

You can adjust the backfill time window (the amount of days for which bloom filters are generated for an index bucket) by editing the maxBloomBackfillBucketAge attribute in indexes.conf.

Splunk's database-checking utility might use more resources

After you upgrade to 4.3, Splunk's database consistency checking utility (fsck) might use more system resources (in particular, disk I/O) when they run, particularly if bloom filters are being created at the same time.

The deployment server's serverclass.conf has a new attribute "machineTypesFilter"

We've added a new attribute for serverclass.conf for distributed deployments. This new attribute allows you to specify which servers in a given server class are filtered from a whitelist or blacklist that is defined within that class.

The new machineTypesFilter attribute tells Splunk that, for a given whitelist or blacklist of servers in a server class definition, the machine type(s) defined by the attribute must be applied only to the list of servers defined within that whitelist or blacklist. Review the following serverclass.conf example:

machineTypesFilter=linux-i686, linux-x86_64

In this example, the "Austin_Linux" server class is defined as "all hosts in the *.austin.ourcompany.com domain whose machine type is either 'linux-i686' or 'linux-x86-64'."

This is different from the existing machineTypes attribute, which selects all hosts whose machine type matches what is defined by that attribute, regardless of what is defined in the whitelist or blacklist for a given server class.

Section 508 compliance on Mac OS X and Firefox

When you upgrade to 4.3, you might lose the ability to use the Tab key to toggle through various navigation menus and dashboards in Splunk when running Firefox on Mac OS X. To fix this problem, open System Preferences, select Keyboard, and under the Full Keyboard Access option at the bottom of the page, select All controls. Close System Preferences and then restart Firefox. You should now be able to tab through the menus and dashboards.

Migrate your 4.1.x apps to 4.3

Check out this topic about how to migrate 4.1.x apps to 4.3.

Start Splunk for the first time
Upgrade from 3.x to 4.3

This documentation applies to the following versions of Splunk® Enterprise: 4.3, 4.3.1, 4.3.2, 4.3.3, 4.3.4, 4.3.5, 4.3.6, 4.3.7


Does it matter if I upgrade my forwarders before or after I upgrade my indexers?

April 25, 2012

You can run 4.3 search heads against 4.2 indexers, but you might lose some functionality. See: http://docs.splunk.com/Documentation/Splunk/latest/Deploy/Whatisdistributedsearch#Compatibility_between_4.3_search_heads_and_4.2_search_peers<br /><br />Forwarders don't directly interact with search heads (rather, forwarders interact with indexers, which then interact with search heads), but in any case, there's good cross-version compatibility between forwarders and indexers, as outlined here: http://docs.splunk.com/Documentation/Splunk/latest/Deploy/Deploymentoverview#Indexer_and_universal_forwarder_compatibility<br /><br />For detailed information on updating a distributed environment, see http://docs.splunk.com/Documentation/Splunk/latest/Deploy/Upgradeyourdistributedenvironment

Sgoodman, Splunker
January 23, 2012

Can I upgrade my my search heads to 4.3 without upgrading my indexers and forwarders?

January 21, 2012

Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

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