About upgrading to 4.3 READ THIS FIRST
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
- Changes to how Splunk handles host names retrieved from scripted inputs
- No change to license management
- Splunk uses more Unix file descriptors
- Changes to Windows Registry Monitor configuration files
- Changes to Windows Registry monitor default behavior
- Changes to Active Directory monitoring configuration file defaults
- Changes to Windows event log monitoring configuration values
- The Windows app doesn't use the performance monitor collection features
- Splunk expects canonical IP addresses in its configuration file stanzas
- The accessibility defaults for Splunk Web's single sign-on (SSO) implementation have changed
- Splunk timeline now displayed in HTML5 Canvas instead of Flash
- Existing saved searches must be reconfigured to use the new report builder view
- Dashboards with certain charting properties might not render or display as desired
- The Panel Editor introduces a new editing workflow for some dashboards
- Simple XML now always has precedence when editing form or dashboard settings
- Changes to LDAP authentication configuration for multi-domain support
- Users of LDAP version 2 might experience user configuration issues
- Bloom filters get created after upgrading
- Splunk's database-checking utility might use more resources
- The deployment server's serverclass.conf has a new attribute "machineTypesFilter"
- Section 508 compliance on Mac OS X and Firefox
- Migrate your 4.1.x apps to 4.3
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.
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
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
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 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.
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
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,
Do not put leading zeros in your IP addresses (
[tcp://010.000.000.010:9995], 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'.
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
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:
[settings] SSOMode = permissive
Splunk timeline now displayed in HTML5 Canvas instead of Flash
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
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
- 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
- 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
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
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.
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:Austin_Linux] whiltelist.0=*.austin.ourcompany.com 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.