• Read This First
  • Before you install
    • System Requirements
  • What Gets Installed
• Step by Step Installation
  • Step 1: Unpack the software
    • RPM
    • deb
    • FreeBSD
    • Mac OS
    • Solaris
  • Step 2: Start Splunk
  • Step 3: Install your license
    • Using SplunkWeb
    • From the command line
• Install Splunk Toolbar
  • How to Install the Splunk toolbar for Firefox
    • Install from download page
    • Install from Splunk server
    • Uninstall Splunk toolbar
  • How to install the Splunk toolbar for Internet Explorer (beta)
    • Install Internet Explorer toolbar from download page
    • Install toolbar in Internet Explorer
    • Uninstall Internet Explorer toolbar
• Advanced Installation Topics
  • Automated installation
  • Configure Splunk to Start at System Startup
  • License Management
    • Installing or updating a license
  • Uninstall Splunk
    • RedHat Linux
    • Debian Linux
    • Solaris
    • FreeBSD
    • Manual uninstall
• Upgrade Instructions
  • Read this first before upgrading to 3.0.x
    • All bundles, all the time
    • Terminology changes
    • Event typer changes
    • What will be preserved on upgrade
    • Deployment server
    • License changes
  • Upgrading 2.1.x or 2.2.x to 3.0.x
    • Step 1: Administrative preparation
    • Step 2: Install the 3.0.x package and update your database
    • Step 3: Update and restore your configuration files
  • Upgrading to a later 3.0.x maintenance release
    • For rpm, pkg, and deb upgrades
    • For tar upgrades
• Help
  • Getting Help
    • Accessing help in SplunkWeb
    • Accessing help in the command line (CLI)
    • How can I learn more about Splunk's advanced features?
    • I lost my Splunk.com password. What do I do?
    • How do I report problems?
    • How can I make suggestions?
    • I have some questions that aren't answered here. Where can I get help?
  • Installer options
• Reference
  • File Manifest
  • PGP Public Key
    • Installing the key

Upgrading 2.1.x or 2.2.x to 3.0.x

Note: Do not attempt to migrate from 2.0.x to 3.0.x. You will first need to upgrade and migrate your data to 2.2.3 format. Read the 2.0.x to 2.2.x migration instructions first.*

Step 1: Administrative preparation

Obtain your new license(s)

Splunk 3.0 requires an entirely new form of license key. If you are a Splunk Professional customer, you must obtain a new Enterprise license (Professional is now known as Enterprise) even if your 2.x license has not expired. New licenses can be obtained through customer support or via your store account. If you have a current Enterprise support agreement, it is likely that customer support has already re-issued your license and attached it to your store account. Just log into www.splunk.com, and go to store -> my orders to view all of your licenses. Please contact support if this is not the case.

If you are using a Free license then there will be no need to install a 3.x license. The default 3.0 Free license will be installed automatically if no license is detected on startup.

Back up your old instance(s)

Please backup your 2.x instances before attempting to update them to 3.0.1 or higher. At a minimum make sure the $SPLUNK_HOME/etc and $SPLUNK_HOME/var directories in all your instances are backed up to a separate location before proceeding. If you have Splunk instances in production we recommended piloting the update in a staging environment before attempting it in production. It is possible to recover a corrupt instance or one in an indeterminate state but you will require assistance from customer support to do so.

Plan your update

Please read through both the upgrade overview and this entire page before attempting your first update. The update process involves overlaying Splunk 3.0.1 or higher (3.0.x) over your 2.x instance. If you're using packages native to your platform you'll use their update mechanisms. If you have a tar installation you'll simply extract 3.0.x over your 2.x instance after backing up your configuration. In either case you'll update your database to function with 3.0.x and move your configuration back in place after the 3.0.x package is in place. The time required to complete the update depends on the complexity of your configuration, not the size of your database(s).

You are not alone

Please do not hesitate to contact support if you have questions or experience problems updating to 3.0.x.

Step 2: Install the 3.0.x package and update your database

NOTE: If you have a Splunk Enterprise license (formerly known as Splunk Professional) be sure you have obtained a new 3.0 license before proceeding.

This process requires the installed configuration to be moved out of the way and then be restored after installation and database migration. Until configuration is restored the default ports will be used. Those ports are 8000 and 8089. It would be best to ensure there are no conflicts on ports 8000 and 8089 before executing the data migration step. Note that Splunk 3.0.1 only listens on one HTTP port and one management port, unlike 2.x which listened on one HTTP port, one HTTPS port, and one management port. That is why only 8000 and 8089 are important for this step. The HTTP port can be configured to be HTTPS (see Step 3).

To install Splunk 3.0.x over 2.1.x or 2.2.x and fashion the 2.1x or 2.2.x database for use in 3.0.x:

1. Download the appropriate 3.0.1 package from the Previous Releases page. The 3.0 package does not include the necessary migration tools.
2. Stop the 2.1.x or 2.2.x Splunk server.
3. Event types and tags will be lost when the database is migrated. If you wish to preserve your tags execute $SPLUNK_HOME/bin/splunk export globaldata before proceeding. (Note: Splunk must be running to execute this command.) Host tags and sourcetype aliases can be recovered with a procedure outlined below. We will release a procedure to convert event types at a later time.
4. Move $SPLUNK_HOME/etc to $SPLUNK_HOME/etc.bak. Directory must be named etc.bak. The native packages will move the configuration to $SPLUNK_HOME/etc.bak automatically.
5. Ensure your database, by default everything in $SPLUNK_HOME/var/lib, has been backed up to a location outside of $SPLUNK_HOME. The native packages will not do this automatically.
6. Update the native package or overlay the 3.0.x tar over the 2.x installation.
7. If you are not using LDAP and wish to migrate your user accounts, copy $SPLUNK_HOME/etc.bak/auth/splunk.secret to $SPLUNK_HOME/etc/auth. Copy $SPLUNK_HOME/etc.back/passwd to $SPLUNK_HOME/etc. Your 2.x accounts should then work as normal in 3.0.
8. If using tar archives, reset the SPLUNK_HOME value in $SPLUNK_HOME/bin/setSplunkEnv to the correct value.
9. If you moved your datastore from the default $SPLUNK_HOME/var/lib/splunk location, edit the SPLUNK_DB value in $SPLUNK_HOME/bin/setSplunkEnv to the correct path.
10. If you have Splunk Professional 2.2.x or 2.1.x , copy a 3.0 Enterprise license into $SPLUNK_HOME/etc.
11. Source $SPLUNK_HOME/bin/setSplunkEnv into your shell. (If you are already in the directory, the command is "source setSplunkEnv".)
12. Important! The following step will start and restart your instance. Absent configuration Splunk 3.0 will attempt to bind to its default ports, 8000 and 8089. If you or your environment cannot tolerate this, please skip to the "Port information in search.user.xml and splunkd.xml" section below and migrate your port configuration before proceeding. It is enough to have your port information in $SPLUNK_HOME/etc/bundles/local/web.conf in place. Do not start Splunk to confirm your configuration before proceeding to the next step as you haven't migrated your database.
13. Execute python $SPLUNK_HOME/bin/migrate_2x_data_to_3x.py. This will migrate the data, start, and restart Splunk. This is necessary for Splunk to correctly re-scan the database files. This is a one way process. Tags will be lost (see above for tag preservation information).
14. Splunk 3.0.x is now active but your configuration is empty. No inputs will be active until step 3 is completed. If your instance consumes live inputs that cannot tolerate downtime, make provisions to redirect those inputs to a file for later consumption. Configuration in $SPLUNK_HOME/etc.bak is ready for migration. Note that certain elements of the UI may appear corrupt or incorrect immediately after migration. It is necessary to clear your browser's cache after the update to remedy this.

Step 3: Update and restore your configuration files

Most configuration options previously controlled by XML files have now been moved to configuration files. This change makes it easier to
administer a Splunk server and easier to deploy configuration changes to other Splunk servers via bundles and the Splunk deployment server.

The purpose of this section is to provide a map between 2.x and 3.0.x configuration. It is not to provide exhaustive documentation of all
3.0.1 configuration. Please review the 3.0.1 administration guide for full details of how 3.0.1 works and 3.0.1 administration.

The process of updating and restoring your configuration involves moving some configuration information out of XML files and into bundle
files and updating your bundle files to work with 3.0.x. You'll need to migrate configuration parameters from $SPLUNK_HOME/etc.bak to $SPLUNK_HOME/etc.

At a high level the necessary configuration changes are:

• Port information in a 2.x $SPLUNK_HOME/etc/myinstall/search.user.xml needs to be moved to 3.0.x $SPLUNK_HOME/etc/bundles/local/web.conf. This file has moved from XML to Splunk bundle format.
• All configuration in a 2.x $SPLUNK_HOME/etc/myinstall/pluginConfs/multiIndexer.xml needs to be moved to 3.0.x $SPLUNK_HOME/etc/bundles/local/indexes.conf. This file has moved from XML to Splunk bundle format.
• If your 2.x instance is a lightweight forwarder then it's best to just set that configuration via the 3.0.x Splunk Web interface or CLI. In 3.0.x configuration of a forwarder with local indexing disabled automatically configures Splunk in a minimal mode.
• The 2.x bundle file regexes.conf is called transforms.conf in 3.0.1 and the 3.0.1 bundle file props.conf now requires the attribute prefix REGEXES- to be changed to TRANSFORMS-.
• The 2.x bundle files savedsplunks.conf and livesplunks.conf have been combined into the 3.0.x bundle file savedsearches.conf.
• The 2.x bunde file auth.conf is a subset of configuration available in the 3.0.x bundle file auth.conf. A new required parameter must be added to your 2.x configuration. (pageSize = 0)
• The 2.x XML file $SPLUNK_HOME/etc/myinstall/pluginConfs/cleaners.xml is now easier to administrate in the 3.0.x bundle file segmenters.conf.

XML Configuration Updates

Port information in search.user.xml and splunkd.xml

By default Splunk 2.x opened three ports. An HTTP port, and HTTPs port, and a management port. Splunk 3.0.x only opens two ports. A web port and a management port. The web port can be configured to be either HTTP or HTTPS. The default 3.0.x configuration can be observed at $SPLUNK_HOME/etc/bundles/default/web.conf. Documentation and an example of the 3.0.x web.conf file can be found at $SPLUNK_HOME/etc/bundles/README/web.conf.[spec|example] or here.

To migrate your settings from 2.x to 3.0.1 it should just be a matter of configuring the same ports used in the 2.x search.user.xml file in an override 3.0.x stanza in $SPLUNK_HOME/etc/bundles/local/web.conf. If you're using SSL and are also using your own certificates then you'll want to place those certificates from your 2.x instance in the location where the default 3.0.x web.conf file expects them, or override those configuration parameters in your local web.conf file as well.

Multiple indexes in 3.0.x

In 2.x all indexes were specified in $SPLUNK_HOME/etc/myinstall/pluginConfs/multiIndexer.xml. This file has been converted into a bundle in 3.0.x. In 3.0.x the set of default indexes are configured in $SPLUNK_HOME/etc/bundles/default/indexes.conf. Additional custom indexes may be added in $SPLUNK_HOME/etc/bundles/local/indexes.conf. Be sure to place the 3.0.x configuration information after migrating your database. If you don't also configure your custom indexes in Splunk 3.0.x then you won't see them. It should be readily apparent how the parameters in the 2.x XML file maps to the 3.0.x bundle file. Be aware that the index dropdown in 2.x is not present in 3.0.x. Search in your custom indexes with the index::yourcustomindexname search operator.

Documentation and an example of the 3.0.x indexes.conf file can be found at $SPLUNK_HOME/etc/bundles/README/indexes.conf.[spec|example] or here.

Bundle Configuration Updates

2.x regexes.conf is now 3.0.x transforms.conf

The file regexes.conf is ignored in 3.0.x. The file was renamed and extended to better serve its purpose - transforming data inputs and events based on requirements to modify and extend Splunk's automated processing. Like regexes.conf, transforms.conf is referenced by props.conf and may contain regular expressions to extract the target of the transformation. The format and actions of the individual attributes within the file has not changed. Rename your regexes.conf to transforms.conf. Then modify props.conf to refer to the transform.

Change regexes to transforms

Props.conf used to refer to regexes in the regexes.conf file. Now it refers to transforms in the transforms.conf file. In addition, the attribute prefix in props.conf has changed from REGEXES- to TRANSFORMS-. See the 3.0.x admin manual reference pages on props.conf and transforms.conf for full details.

An example of Splunk 2.x to Splunk 3.0.x regex to transforms changes:

In props.conf change from the following 2.x style:

[cisco_syslog]
MAX_TIMESTAMP_LOOKAHEAD = 32
SHOULD_LINEMERGE = False
REGEXES = syslog-host
...

to the following 3.0.1 props.conf style:

[cisco_syslog]
MAX_TIMESTAMP_LOOKAHEAD = 32
SHOULD_LINEMERGE = False
TRANSFORMS = syslog-host
...

A stanza in a 3.0.1 transforms.conf looks like stanzas in 2.x regexes.conf:

[syslog-host]
DEST_KEY = MetaData:Host
REGEX = :\d\d\s+(?:\d+\s+|(?:user|daemon|local.?)\.\w+\s+)*\[?(\w[\w\.\-]+)\]?\s
FORMAT = host::$1

Note that if you are using a regexes.conf stanza in 2.x in order to extract fields at search time for use with the report:: search modifier, you will want to read about how to define extracted fields in 3.0.1 as well as read about the new search language which has many powerful native statistical and structured search commands including select, {{where, {{fields, stats, top and rare which have replaced and improved upon the 2.x report:: search modifier.

2.x savedsplunks.conf and livesplunks.conf is now 3.0.x savedsearches.conf

The 2.x savedsplunks.conf and livesplunks.conf files have been combined into one overall savedsearches.conf file. In 3.0.x you can add scheduling and alert information directly to the saved search. The old live splunk subsystem in 2.x has been completely replaced with the new scheduling and alerting subsystem in 3.0.x.

The name/value pairs in savedsplunks.conf should map directly to savedsearches.conf with one exception. Use just the raw search string in 3.0.1, not the entire XML value of the query parameter in 2.x. Be sure a user exists in the 3.0.x instance with the same userid you're bringing over from 2.x.

The name/value pairs from livesplunks.conf will not map cleanly into savedsearches.conf. You do not need to bring over the savedsplunkid parameter as alert information is now stored directly with the saved search. The next change is that the 3.0.x saved searches.conf file uses a cron-like scheduling parameter in replacement of several run and range parameters in livesplunks.conf. It should be readily apparent how to map the relation and action configuration if one compares your livesplunks.conf stanza to the 3.0.x spec and example files. ($SPLUNK_HOME/etc/bundles/README/savedsearches.conf.[spec|example])

Special note about saved report:: searches

The only search syntax element that is not backwards compatible between 3.0.x and prior versions is report::. If you have saved searches that use report::, you should update them to take advantage of the new search language which has many powerful native statistical and structured search commands including select, {{where, {{fields, stats, top and rare which have replaced and improved upon the 2.x report:: search modifier. These new commands are both more flexible and faster than the old report:: modifier.

2.x auth.conf in LDAP mode to 3.0.x auth.conf in LDAP mode

If you're using LDAP authentication in 2.x then you can copy your auth.conf file into 3.0.x and use it if you make the following changes:

• Add name/value pairs userBaseFilter and groupBaseFilter. If you're unsure how to use LDAP filters you may safely supply the value '(objectclass=*)' without the quotes for these parameters. This filter will match every entry below your specified base DNs. Restrict the filter if you do not want this.

• Add the name/value pair pageSize. A pageSize of 0 means to use LDAPv2. A nonzero page size will use LDAPv3 with an additional control for paging. A nonzero page size is necessary if your using Microsoft Active Directory.

2.x cleaners.xml is now 3.0.x segmenters.conf

If you've modified your segmenters in your 2.x instance you should add them to your local segmenters.conf file. $SPLUNK_HOME/etc/bundles/local/segmenters.conf. See $SPLUNK_HOME/etc/bundles/README/segmenters.conf.[spec|example] for detailed information.

Data Inputs

In general nearly all data input parameters should map cleanly from 2.x to 3.0.x with the exception of the regexes/transforms transition described above. If you have a concern about a particular parameter you should browse $SPLUNK_HOME/etc/bundles/README for the parameter in question and see if it's usage has changed from 2.x to 3.0.x. If something about the data input configuration gets lost in translation there should be clear error messages in splunkd.log. Be aware that 3.0.x is capable of eating archive files directly without needing them to be uncompressed first.

Other Configuration Updates

Splunk Users

The procedure for migrating non-LDAP users is covered in Step 2. The procedure for migrating LDAP configuration is covered in Step 3. Select the method that is appropriate for you.

Lightweight Forwarders

Splunk 2.x required extensive configuration changes to run in a minimal mode for a forwarding-only instance. In Splunk 3.0.x this configuration is done for you automatically if you enable forwarding and disable local indexing in the GUI. Splunk should only consume about 100 MB RAM in the 3.0.x configuration, usually less. It is possible for 2.x forwarders to forward to a 3.0.x instance.

Custom C++ Processors

If your 2.x instance contains a custom C++ module, that module should work with 3.0.x. Be aware, however, that Splunk 3.0 ships with fewer shared objects than Splunk 2.x. In particular, libstdc++ is no longer included with the distribution. If you use your platform's libstdc++ and other libraries, your module should work.

Distributed Search

It is easiest to simply re-configure your 2.x distributed search hosts via Splunk Web in 3.0.x. Be aware that it is not possible to mix 2.x and 3.0.x servers in a distributed search cluster. Enhancements to the search language in the 3.0 product prevent this from working. Note that the "Splunk-2-Splunk" tab in the 2.x admin section has been renamed "Distributed" in the 3.0.x admin section.

Host tags and source type aliases

If in Step 2 you exported your global data to an XML file you can convert and re-import the host tag and sourcetype aliases into your Splunk 3.0 instance. With $SPLUNK_HOME/bin/setSplunkEnv sourced from a 3.0 instance, execute

python $SPLUNK_HOME/bin/migrate_2x_exported_data_to_3x.py $YOUREXPORTEDFILENAME
splunk import globaldata $YOUREXPORTEDFILENAME.readyfor30import -auth admin:$YOURPASSWORD

To confirm the procedure you should be able to see your host tags in type ahead and also see the correct data exported with a splunk export globaldata command.