Migrate a Splunk instance
This topic discusses the procedure for migrating a Splunk instance from one server, operating system, architecture, or filesystem to another, while maintaining the indexed data, configurations, and users. This is different than upgrading an instance, which is merely installing a new version on top of an older one (though, an upgrade is a form of migration).
When to migrate
There are a number of reasons to migrate a Splunk install:
- Your Splunk installation is on a server that you wish to retire or reuse for another purpose.
- Your Splunk installation is on an operating system that either your organization or Splunk no longer supports, and you want to move it to an operating system that is supported.
- You are switching operating systems (for example, from *nix to Windows or vice versa)
- You want to move your Splunk installation to a different file system.
- Your Splunk installation is on 32-bit architecture, and you wish to move it to a 64-bit architecture for better performance.
- Your Splunk installation is on a system architecture that you plan to no longer support, and you want to move it to an architecture that you do support.
What to consider when migrating
While migrating a Splunk instance is simple in many cases, there are some important considerations to note when doing so. Depending on the type, version, and architecture of the systems involved in the migration, you might need to consider more than one of these items at a time.
When migrating a Splunk instance, be sure to note:
If you indexed data with a version of Splunk earlier than 4.2, the index files that comprise that data are sensitive to an operating system's endianness, which is the way the system organizes the individual bytes of a binary file (or other data structure).
Some operating systems are big-endian (meaning they store the most significant byte of a binary file first), and others are little-endian (meaning they store the least significant byte first). These operating systems create binary files of the same endianness. Index bucket files are binary, and thus, for versions of Splunk earlier than 4.2, are the same endianness of the operating system that created them.
For a listing of processor architectures and the endianness they use, refer to the Endianness article on Wikipedia.
When you migrate a pre-4.2 Splunk instance, in order for the destination system to be able to read the migrated data, you must transfer index files between systems with the same kind of endianness (for example, a NetBSD system running on a SPARC processor to a Linux system also running on a SPARC processor.)
If you can't move index between systems with the same endianness (for example, when you want to move from a system that's big-endian to a system that's little-endian), you can move the data by forwarding it from the big-endian system to the little-endian system. Then, once you have forwarded all the data, you can retire the big-endian system.
Index files created by Splunk versions 4.2 and later do not have problems with endianness.
Differences in Windows and Unix path separators
The path separator (the character used to separate individual directory elements of a path) on *nix and Windows is different. When moving index files between these operating systems, you must make sure that the path separator you use is correct for the operating system you want to move the Splunk installation to. You must also make sure that you update any Splunk configuration files (in particular,
indexes.conf) to use the correct path separator.
When moving a Splunk instance between Windows servers, make sure that the destination server has the same rights assigned to it that the source server does. This includes but is not limited to the following:
- Ensure that the file system and/or share permissions on the target server are correct and allow access for the user that runs Splunk.
- If Splunk runs as an account other than the Local System user, that the user is a member of the local Administrators group and has the appropriate Local Security Policy or Domain Policy rights assigned to it by a Group Policy object
If you downgrade the architecture that your Splunk instance runs on (for example, 64-bit to 32-bit), you might experience degraded search performance on the new server due to the larger files that the 64-bit operating system and Splunk instance created.
Distributed and clustered Splunk environments
When you want to migrate data on a distributed Splunk instance (that is, an indexer that is part of a group of servers that a search head has been configured to search for events, or a search head that's been configured to search indexers for data), the you should remove the instance from the distributed environment before attempting to migrate it.
Bucket IDs and potential bucket collision
If you migrate a Splunk instance to another Splunk instance that already has existing indexes with identical names, you must make sure that the individual buckets within those indexes have bucket IDs which do not collide. Splunk will not start if it encounters indexes with buckets that have colliding bucket IDs. When copying index data, you might need to rename the copied bucket files in order to prevent this condition.
How to migrate
To migrate your system from one version of Splunk to another, follow these instructions:
1. Stop Splunk on the server from which you want to migrate.
2. Copy the entire contents of the $SPLUNK_HOME directory from the old server to the new server.
Important: Be sure to note any considerations above which might apply to you when copying the files.
3. Install the appropriate version of Splunk for the target platform.
- On *nix systems, you can extract the tar file you downloaded directly over the copied files on the new system, or use your package manager to upgrade using the downloaded package.
- On Windows systems, the installer updates the Splunk files automatically.
4. Confirm that index configuration files (indexes.conf) contain the correct location and path specification for any non-default indexes.
5. Start Splunk on the new Splunk instance.
Note: On *nix systems, Splunk detects whether you are migrating and prompts you on whether or not to upgrade at this time.
6. Log into Splunk. You should be able to log in with your existing credentials.
7. Once logged in, confirm that your data is intact by searching it.
How to move index buckets from one server to another
If you're retiring a Splunk server and immediately moving the data to another Splunk server, you can move individual buckets of an index between servers, as long as:
- The source and target systems have the same endianness.
- You are not trying to restore a bucket created by a 4.2 or greater version of Splunk to a version of Splunk less than 4.2.
To move a bucket from one server to another:
1. Roll any hot buckets on the source system from hot to warm.
2. On the target system, create index(es) that are identical to the ones on the source system.
Note: Review indexes.conf on the old system to get a list of the indexes on that system.
3. Copy the index buckets from the source system to the target system.
Note: When copying individual bucket files, you must make sure that no bucket IDs conflict on the new system. Otherwise, Splunk will not start. You might need to rename individual bucket directories after you move them from the source system to the target system.
4. Restart Splunk.
Upgrade PDF printing for Splunk Web
Migrate to the new Splunk licenser
This documentation applies to the following versions of Splunk® Enterprise: 5.0, 5.0.1, 5.0.2, 5.0.3, 5.0.4, 5.0.5, 5.0.6, 5.0.7, 5.0.8, 5.0.9, 5.0.10, 5.0.11, 5.0.12, 5.0.13, 5.0.14, 5.0.15, 5.0.16, 5.0.17, 5.0.18