Migrate from a standalone search head to a search head cluster
You can migrate settings from an existing standalone search head to all members in a search head cluster.
Important: You cannot migrate the search head instance itself, only its settings. You can only add clean, new Splunk Enterprise instances to a search head cluster.
Important points to consider
There are a few points to keep in mind when migrating your settings to a search head cluster.
Do not migrate default apps
When you migrate apps to the search head cluster, do not migrate any default apps, that is, apps that ship with Splunk Enterprise, such as the search app. If you push default apps to cluster members, you overwrite the version of those apps residing on the members, and you do not want to do this.
You can, however, migrate custom settings from a default app:
- You can migrate any private objects associated with the default apps. Private objects are located under the
etc/usersdirectory, not under
- You can migrate custom settings in the app itself by moving them to a new app and exporting them globally. The migration procedure in this topic includes a step for this.
Migrated settings get placed in default directories
The deployer puts all migrated settings into default directories on the cluster members. This includes any runtime changes that were made while the apps were running on the standalone search head.
Because users cannot change settings in default directories, this means that users cannot perform certain runtime operations on migrated entities:
- Delete. Users cannot delete any migrated entities.
- Move. Users cannot move these settings from one app to another.
- Change sharing level. Users cannot change sharing levels. For example, a user cannot change sharing from private to app-level.
Users can override existing attributes by editing entities in place. Runtime changes get put in the local directories on the cluster members. Local directories override default directories, so the changes override the default settings.
For more information on where deployed settings reside on the cluster members, see See "Location on the cluster members."
Note: Splunk does not support migration of per-user search history files.
Migrate settings to a search head cluster
Note: This procedure assumes that you have already deployed the search head cluster. See "Deploy a search head cluster."
To migrate settings:
1. Copy the
$SPLUNK_HOME/etc/users directories on the standalone search head to a temporary directory on the deployer where you can edit them.
2. If you want to migrate custom settings from a default app, you can move them to a new app and export them globally. For example, to migrate settings from the search app :
- a. Copy the
.../search/localdirectory in the temporary directory to a new app directory, such as
search_migration_app, in the temporary directory. Do not name this new app "search."
- b. Export the settings globally to make them available to all apps, including the search app. To do this, create a
.../search_migration_app/metadata/local.metafile and populate it with the following content:
- See the default.meta specification file for details.
3. In the temporary directory, delete these subdirctories:
- Any default apps, such as the search app. Do not push default apps to the cluster members. If you do, they will overwrite the versions of those apps already on the members.
- Any apps already existing in the deployer's distribution directory. Otherwise, the versions from the standalone search head will overwrite the versions already on the members.
4. Copy all the remaining subdirectories from the temporary location to the distribution directory on the deployer. The distribution directory is located at
$SPLUNK_HOME/etc/shcluster. Leave any subdirectories already in the distribution directory unchanged.
For details on the distribution directory file structure, see "What the configuration bundle contains."
5. If you need to add new cluster members, you must deploy clean instances. You cannot reuse the existing search head. For information on adding cluster members, see "Add a cluster member."
6. Use the deployer to push the configuration bundle, including the migrated settings, to the cluster members. See "Push the configuration bundle."
Important: If you point the cluster members at the same set of search peers previously used by the standalone search head, the cluster will need to rebuild any report acceleration summaries or data model summaries resident on the search peers. It does this automatically. It does not, however, automatically remove the old set of summaries.
Use a load balancer with search head clustering
Migrate from a search head pool to a search head cluster
This documentation applies to the following versions of Splunk® Enterprise: 6.2.4, 6.2.5, 6.2.6