Splunk® Enterprise

Distributed Search

Download manual as PDF

Splunk Enterprise version 6.x is no longer supported as of October 23, 2019. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

Add search peers

To activate distributed search, you add search peers, or indexers, to a Splunk Enterprise instance that you designate as a search head. You do this by specifying each search peer manually.

Important: A search head should not perform a dual function as a search peer. The only exception to this rule is for the distributed management console, which functions as a "search head of search heads."

This topic describes how to connect a search head to a set of search peers.

Important: Indexer clusters also use search heads to search across the set of indexers, or peer nodes. You deploy and configure search heads very differently when they are part of an indexer cluster. To learn more about configuring search heads in indexer clusters, read "Configure the search head" in the Managing Indexers and Clusters of Indexers manual.

Configuration overview

You can set up distributed search on a search head using any of these configuration methods:

  • Splunk Web
  • Splunk CLI
  • The distsearch.conf configuration file

Splunk Web is the recommended method for most purposes.

You perform the configuration on the designated search head. The main step is to specify the search head's search peers. The distributed search capability itself is already enabled by default.

Important: Before an indexer can function as a search peer, you must change its password from the default "changeme". Otherwise, the search head will not be able to authenticate against it.

Aside from changing the password, no configuration is generally necessary on the search peers. Access to the peers is controllable through public key authentication. However, you do need to perform some configuration on the search peers if you mount the knowledge bundles, so that the peers can access them. See "Mount the knowledge bundle" for details.

Use Splunk Web

Specify the search peers

To specify the search peers:

1. Log into Splunk Web on the search head and click Settings at the top of the page.

2. Click Distributed search in the Distributed Environment area.

3. Click Search peers.

4. On the Search peers page, select New.

5. Specify the search peer, along with any authentication settings.

6. Click Save.

7. Repeat for each of the search head's search peers.

Configure miscellaneous distributed search settings

To configure other settings:

1. Log into Splunk Web on the search head and click Settings at the top of the page.

2. Click Distributed search in the Distributed Environment area.

3. Click Distributed search setup.

5. Change any settings as needed.

6. Click Save.

Use the CLI

To specify the search peers:

1. Navigate to the $SPLUNK_HOME/bin/ directory on the search head.

2. Invoke the splunk add search-server command for each search peer you want to add.

For example:

splunk add search-server -host -auth admin:password -remoteUsername admin -remotePassword passremote

Note the following:

  • Use the -host flag to specify the IP address and management port for the search peer.
  • Provide credentials for both the local (search head) and remote (search peer) instances. Use the -auth flag for the local credentials and the -remoteUsername and -remotePassword flags for the remote credentials (in this example, for search peer The remote credentials must be for an admin-level user on the search peer.

Edit distsearch.conf

In most cases, the settings available through Splunk Web provide sufficient options for configuring distributed search environments. Some advanced configuration settings, however, are only available by directly editing distsearch.conf. For information on the configuration options, see the distsearch.conf spec file.

For more information on configuration files in general, see "About configuration files".

Add the search peers

To run distributed searches:

1. Create or edit a distsearch.conf file on the search head.

2. Add the set of search peers to the [distributedSearch] stanza. For example:

servers =,

3. Restart the search head.

Distribute the key files

If you add search peers via Splunk Web or the CLI, Splunk Enterprise automatically handles authentication. However, if you add peers by editing distsearch.conf, you must distribute the key files manually. After adding the search peers and restarting the search head, as described above:

1. Copy the file $SPLUNK_HOME/etc/auth/distServerKeys/trusted.pem from the search head to $SPLUNK_HOME/etc/auth/distServerKeys/<searchhead_name>/trusted.pem on each search peer.

The <searchhead_name> is the search head's serverName. See "Manage distributed server names".

Authentication of multiple search heads from a single peer

Multiple search heads can search across a single peer. The peer must store a copy of each search head's certificate.

The search peer stores the search head keys in directories with the specification $SPLUNK_HOME/etc/auth/distServerKeys/<searchhead_name>.

For example, if you have two search heads, named A and B, and they both need to search one particular search peer, do the following:

1. On the search peer, create the directories $SPLUNK_HOME/etc/auth/distServerKeys/A/ and $SPLUNK_HOME/etc/auth/distServerKeys/B/.

2. Copy A's trusted.pem file to $SPLUNK_HOME/etc/auth/distServerKeys/A/ and B's trusted.pem to $SPLUNK_HOME/etc/auth/distServerKeys/B/.

3. Restart the search peer.

Last modified on 02 March, 2016
Designate the search head
Remove a search peer

This documentation applies to the following versions of Splunk® Enterprise: 6.0, 6.0.1, 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.0.7, 6.0.8, 6.0.9, 6.0.10, 6.0.11, 6.0.12, 6.0.13, 6.0.14, 6.0.15, 6.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 6.1.6, 6.1.7, 6.1.8, 6.1.9, 6.1.10, 6.1.11, 6.1.12, 6.1.13, 6.1.14

Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters