Migrate settings 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.

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.

Types of objects to migrate

There are two types of objects to migrate:

• Custom app configurations. These originate under etc/apps on the standalone search head.

• Private user configurations. These originate under etc/users on the standalone search head.

In both cases, you copy the relevant directories from the search head to the search head cluster's deployer. You then use the deployer to propagate these directories to the cluster.

The deployer pushes the configurations to the cluster, using a different method for each type. Post-migration, the app configurations obey different rules from the user configurations.

For information on where deployed settings reside on the cluster members, see "Where deployed configurations live on the cluster members."

Custom app configurations

When it migrates an app's custom settings, the deployer places them in the appropriate directories on the cluster members based on the deployer_push_mode setting in app.conf. This includes any runtime changes that were made while the apps were running on the standalone search head.

When migrating apps from a single search head to a search head cluster, set the deployer_push_mode to full before you push app configurations from the deployer to the cluster. This mode lets you retain the exact local and default directory configurations as they appear on the original search head. See Choose a deployer push mode.

Cluster 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.

Private user configurations

The deployer copies user configurations to the captain only. The captain then replicates the settings to all the cluster members through its normal method for replicating configurations, as described in "Configuration updates that the cluster replicates."

Unlike custom app configurations, the user configurations reside in the normal user locations on the cluster members and can later be deleted, moved, and so on. They behave just like any runtime settings created by cluster users through Splunk Web.

When you migrate user configurations to an existing search head cluster, the deployer respects attributes that already exist on the cluster. It does not overwrite any existing attributes within existing stanzas.

For example, say the cluster members have an existing file $SPLUNK_HOME/etc/users/admin/search/local/savedsearches.conf containing this stanza:

[my search]
search = index=_internal | head 1

and on the deployer, there's the file $SPLUNK_HOME/etc/shcluster/users/admin/search/local/savedsearches.conf with these stanzas:

[my search]
search = index=_internal | head 10
enableSched = 1

[my other search]
search = FOOBAR

This will result in a final merged configuration on the members:

[my search]
search = index=_internal | head 1
enableSched = 1

[my other search]
search = FOOBAR

The [my search] stanza, which already existed on the members, keeps the existing setting for its search attribute, but adds the migrated setting for the enableSched attribute, because that attribute did not already exist in the stanza. The [my other search] stanza, which did not already exist on the members, gets added to the file, along with its search attribute.

Note: Splunk does not support migration of per-user search history files.

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 default apps. Private objects are located under the etc/users directory, not under etc/apps.

• 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.

Migrate settings to a search head cluster

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/apps and $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 :
   1. Copy the .../search/local directory 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."
   2. 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.meta file and populate it with the following content:

         []
         export=system
      

      See the default.meta specification file for details.

3. In the temporary directory, delete these subdirectories:
   • 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, located at $SPLUNK_HOME/etc/shcluster. Leave any subdirectories already in the distribution directory unchanged.
   For details on the distribution directory file structure, see Where to place the configuration bundle on the deployer.
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. Set the deployer_push_mode to full. See Set the deployer push mode.
7. Run the splunk apply shcluster-bundle command on the deployer to push the configuration bundle, including the migrated settings, to the cluster. See Push the configuration bundle.
   
   In full mode, the deployer pushes etc/apps/default directly to the cluster members. It pushes both etc/apps/local and etc/users to the captain, which asynchronously replicates the settings to the other cluster members.
   
   

   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.