What to expect when migrating to 4.0
This topic discusses the various issues and considerations you should review before migrating to 4.0 from 3.4.x or earlier. You'll find information about aspects of your deployment that cannot be migrated automatically, some changes you will need to make manually, and other changes that the migration script will handle.
Note: If you're migrating from versions earlier than 3.4.x, please follow the documentation for that version to migrate to 3.4.x and then proceed from there. Migration to 4.x is only supported from 3.4.x.
Before you proceed with migration, you should also review the Known Issues for additional information.
Share your migration experiences
Did you migrate an existing Splunk installation to 4.x and run into some issues? What led to your success? Share your tips with other users on the Splunk Community Wiki "Migration experiences"
page.
Considerations and support for users of Splunk 3.4.x
Splunk 4 is a huge stride forward in performance and flexibility, but there are a few interaction
changes vs. 3.4.x which upgraders should be aware of, and even some reasons why you might want to wait for a future release before upgrading. Below are some capabilities that have changed with the introduction of Splunk 4:
Live tail
With Splunk 4's dramatically improved search and indexing speed, along with the ability to provide intermediate search results, you don't really need a separate live event console to see data in near real-time. However, if your use case relies on version 3.4.x's "Live tail" feature, you may want to wait on upgrading to Splunk 4. Future roadmap plans involve re-architecting the live tail functionality to scale across much larger data flows, and across distributed
environments. Additionally, look out for improve real-time alerting and dashboard updates down the road as a result of these upcoming architectural changes.
•
Custom field actions
Based on customer feedback, we decided to re-architect this feature to improve flexibility and allow for event actions based on multiple fields. Expect this functionality to be reintroduced in a near term 4.x release. If you rely on this functionality, but still want to upgrade, you may want to consider Splunk 4's new "Dynamic field lookups" as an alternative which allows you to map data from external databases and lists into Splunk.
•
Snapshots
In Splunk 4, we've improved upon 3.x's ability to take a timeline snapshots of individual searches. Try out Splunk 4's new job manager which allows you to retrieve the entire cached search result, including reports, from existing searches.
•
Event scrolling
In Splunk 4, the new page selector allows you to hop between results with greater flexibility, even as a search runs. However, for those who still prefer a scroll bar, expect this capability to be re-introduced as an option in a future 4.x release.
•
Timeline and timestamp interaction
In Splunk 4, we improved the timeline to allow users to quickly view any time range within search results, without having to rerun a search. Also try clicking "zoom-in" on the timeline, which now allows you to lock-in a time range, and specify follow on search.
•
We're also planning to improve the usability of some related 3.4.x functionality including clicking on timestamps, and double clicking on timeline bars in future versions of 4.x.
•
Crawl
Crawl is no longer configurable via Splunk Web, but is still available as a search command.
Based on customer feedback, we have decided to re-architect this feature to make it easier and more effective. Expect improved functionality, along with a new user interface to be introduced in a future release.
•
FIFO inputs
This input type has been deprecated with Splunk 4, and we do not recommend using it as a best practice due to data loss considerations. If you currently rely on this input type consider writing the output to a flat file that Splunk is monitoring.
•
Persistent Queue
This feature has been deprecated with Splunk 4. When a forwarder loses its connection to the indexer, it will block instead of continuously writing events to disk. If you are concerned about data loss, consider using TCP or file inputs.
•
RSS alerts
RSS alerts are not supported for the initial realease of the 4.x line.
•
Let us know when you're ready to migrate, and we'll be here to help.
Migrating your license
Splunk 4.x does not work with licenses from older releases.
If you're migrating to 4.0 or 4.0.1, AFTER YOU INSTALL, YOU WILL SEE A MESSAGE STATING THAT YOUR LICENSE IS NO LONGER VALID.
•
If you are an current Enterprise customer, check your splunk.com orders page for an updated license.
•
If you're migrating to 4.0.2, your 3.x license is backed up and replaced with an Enterprise trial license when you start Splunk 4.
•
If you are running with a 3.x Free or Enterprise trial license, delete the
$SPLUNK_HOME/etc/splunk.license file before you start Splunk 4.x. The instance will then pick up the 60-day Enterprise trial license.
•
Pre-seeding your license before first time run
Starting with 4.0.2, by default when you start Splunk for the first time, it moves aside any existing 3.x license and replaces it with a temporary Enterprise trial license. This allows you to bring up the new version of Splunk without having your license be expired until you get your new one copied in.
If you are migrating to Splunk 4.0.2 or later and have a valid 4.x license, you can pre-seed the license file so that it pulls in and installs your new license the first time you start Splunk 4. This is useful if you have to deploy multiple instances and don't want to have to manually copy the new license in after starting Splunk on each machine.
Migrate to 4.0.2 or later, but don't start Splunk yet.
•
Copy your new license into $SPLUNK_HOME/etc/splunk-user.license.
•
Start Splunk.
•
If you're making a deployable package, you can include the splunk-user.license file with your updated license in it before you tar/zip it up for deployment to other systems.
Which migration is right for you?
If you have not customized your 3.x deployment extensively, you may be able to use the automatic migration process described in either Migrate on Windows or Migrate on UNIX.
If you have customized your 3.x deployment to any degree, (in particular, if you have customized deployment.conf), you may have to consider migrating your deployment manually. In this case, follow the Steps for manual migration to Splunk 4.x.
What cannot be migrated
Splunk 4.x is significantly different from earlier versions. Some configuration files from your 3.x deployment can be copied over to your new 4.x install without any migration required. However, some aspects of your existing deployment cannot be migrated, and must be rebuilt; this is most relevant for 3.x deployments and configurations that have been extensively customized.
Splunk Web display customizations
All things to do with Splunk Web have been completely re-architected and rebuilt from the ground up.
As a result, any customizations you've made that affect the display of Splunk Web cannot be migrated; you must rebuild them using the 4.x architecture and tools. These include:
Form searches
•
Field actions (field_actions.conf)
•
Dashboards
•
UI preferences (prefs.conf)
•
Report chart and table preferences on saved searches
•
Changes to UI strings (literals.conf)
•
Considerations for apps
In general, apps do not get migrated; you should re-architect your apps to follow the new 4.0 architecture. For more information about apps in 4.0, refer to the Developer Manual. For more guidance on migrating your apps, consult this topic on migrating your 3.x apps in the Developer Manual.
Not all Splunk 3.4.x apps will be immediately available for 4.0. New apps will be added to the Splunk App Store as they become available.
Splunk for Change Management has not yet been made available for Splunk 4, If you have this app, contact Support before upgrading, or consider installing a parallel instance of Splunk to maintain it.
Considerations for deployment server and forwarders
4.x deployment server is not backwards compatible with 3.x deployment clients.
If you use the Splunk deployment server, you must rebuild your deployment configuration using the new deployment server architecture in 4.x; it cannot be migrated. If you've made changes to deployment.conf in version 3.x, you should not copy it over into your new Splunk 4.x installation.
Set it aside to use as a basis for building your new deployment server configuration.
In the meantime, if you have 3.4.x deployment server and clients and do not want to migrate all the clients at this time, you can use the instructions in this topic to configure a stripped-down 3.4.x deployment server to continue managing your deployment clients.
If you have 3.4.x forwarders, you can delay migrating them to 4.x; 3.4.x forwarders will work with a 4.x version of Splunk. This is especially useful for large forwarder deployments. You can wait until you are comfortable with your new deployment server configuration before migrating forwarders to 4.x.
In summary:
3.x forwarders will work with a 4.x indexer.
•
3.x deployment clients will not work with 4.x deployment server.
•
Considerations for distributed search
4.0.x distributed search is not backwards compatible with 3.x distributed search. In addition, the deployment server classes are not directly applicable to 4.x deployment server configuration. 4.x deployment servers use the concept of "apps" to push configuration to clients, as opposed to classes.
Admins must build an application from their classes configuration to push to clients. It is
recommended to do this first, before losing configuration parity at upgrade time, for clients running 4.x.
If you use distributed search, all your participating distributed search nodes will need to run Splunk 4.x in order to successfully communicate and return results.
Using a 4.0 or 4.0.1 Splunk deployment derver with 3.x deployment clients will crash the clients
This issue was resolved in 4.0.2.
To ensure your 4.x server doesn't contact your existing 3.x deployment clients, change the management port on the 4.x instance. Add the following to
$SPLUNK_HOME/etc/system/local/web.conf to change it from the default 8089 port to 8090:
[settings]
mgmtHostPort = 127.0.0.1:8090
What you must migrate manually
Splunk 4.x differs significantly from version 3.x, and the migration script cannot convert the content of some configuration files. This section describes some of the changes that you must make manually.
Considerations for scheduled searches and alerts
Scheduled searches and alerts do not migrate automatically. In the 4.0 knowledge model, a search cannot execute outside of an app context. Thus, saved searches are considered part of the Search app; they are not global and viewable across all apps.
To migrate your saved searches:
1. Stop Splunk; execute the command:
$SPLUNK_HOME/bin/splunk stop
2. Move $SPLUNK_HOME/etc/system/local/savedsearches.conf to
$SPLUNK_HOME/etc/apps/search/local/
3. Move any stanzas whose name starts with "savedsearches/" from
$SPLUNK_HOME/etc/system/metadata/local.meta to
$SPLUNK_HOME/etc/apps/search/metadata/local.meta
4. Start Splunk; execute the command:
$SPLUNK_HOME/bin/splunk start
Note: Scheduled searches will not run unless these 2 steps are completed.
Considerations for tags and aliases
Sourcetype renaming replaces "sourcetype aliasing" and isn't implemented by tags. For more information, see "About tags and aliases" in the Knowledge Manager manual. Saved searches that rely on aliased sourcetypes won't work without migration. For steps to migrate these saved searches, see migration concerns for scheduled searches and alerts.
Considerations for crawl.conf
The crawl.conf stanza [file_crawler] should be renamed [files]. This does not happen automatically.
No migration concerns for CLI
The command line interface, CLI, has been completely rewritten for Splunk 4.x. There are no known migration or backwards compatibility issues. Refer to release notes for the list of changes to the CLI, which include deprecated CLI command options and new functionality.
Changes made during automatic migration
During migration, many configuration files cannot simply be copied over. Splunk provides scripts for converting and migrating the content of these files so that they will function correctly in 4.x. You can run the migration preview utility to see what will be changed before you actually upgrade and migrate.
The following is a list of some of the changes that take place during migration.
alert_actions.conf
This configuration file is migrated with savedsearches.conf.
indexes.conf
During migration, some attributes are added to indexes.conf while other local attributes are either removed or changed to global parameters. For more details about these parameters, refer to indexes.conf in the Admin manual.
The following attributes are no longer supported and have no effect:
_actions
The following global attributes are added with these defaults:
indexThreads = auto
For high-volume indexes (such as main), the following defaults are used:
maxHotBuckets = 10
•
maxHotIdleSecs = 86400
•
maxMemMB = 20
•
savedsearches.conf
During migration, form searches are disabled, a default global view state is set, and owner attributes are moved so that they follow the 4.0 roles and permissions model.
if the search attribute contains macros ($<strings>$), disabled = 1 is added to the stanza.
•
if the attribute defines a view state &mdash, which is any line that begins with "viewstate.", the line is commented out.
•
if the stanza contains 'userid' and/or 'role' attributes, a corresponding metadata owner/ACL is added.
•
server.conf
During migration, the following attributes are moved from splunkd.xml to server.conf:
minFreeMb
The following attributes, for the server certificate and key file and password, are renamed:
keysfile is replaced with sslkeysfile
•
keysfilepassword is replaced with sslkeysfilePassword
•
Windows specific conf files
During migration, Windows-specific files (regmon-filters.conf, sysmon.conf, and wmi.conf) and knowledge objects are moved out of default and into the Windows app architecture.
Conf files that are removed
During migration, the following conf files are removed:
typedefs.conf
•
searchdata.conf
•
Index data compatibility
Data indexed by version 3.x is completely compatible with 4.x and does not need to be re-indexed.
However, note that it may have been indexed in a less efficient form, so searches performed over data that was originally indexed and migrated from 3.x may not be as fast as searches over newly-indexed 4.x data.