Splunk® Enterprise

Distributed Search

Acrobat logo 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.
Acrobat logo Download topic as PDF

Add search peers to the search head

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.

If you need to connect multiple search heads to a set of search peers, you can repeat the process for each search head individually. However, if you require multiple search heads, the best practice is to deploy them in a search head cluster.

Important: Clusters establish connectivity between search heads and search peers differently from the procedures described in this topic:

Configuration overview

To set up the connection between a search head and its search peers, configure the search head through one of these methods:

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

Splunk Web is the simplest method for most purposes.

The configuration occurs on the search head. For most deployments, no configuration is necessary on the search peers. Access to the peers is controlled through public key authentication.


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.

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. The remote credentials must be for an admin-level user on the search peer.

Edit distsearch.conf

The settings available through Splunk Web provide sufficient options for most configurations. Some advanced configuration settings, however, are only available by directly editing distsearch.conf. This section discusses only the configuration settings necessary for connecting search heads to search peers. For information on the advanced configuration options, see the distsearch.conf spec file.

Add the search peers

To connect the search peers:

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

2. Add the set of search peers to the [distributedSearch] stanza as a set of comma-separated values (IP addresses with management ports). 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 configures 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, specified in server.conf.

2. Restart each search peer.

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.

Group the search peers

You can group search peers into distributed search groups. This allows you to target searches to subsets of search peers. See "Create distributed search groups".

View search peer status

After you add search peers to the search head, you can view the search peers' status:

1. On the search head, click Settings at the top of the Splunk Web page.

2. Click Distributed search in the Distributed Environment area.

3. Click Search peers.

There is a row for each search peer.

Last modified on 02 March, 2016
System requirements and other deployment considerations for distributed search
Best practice: Forward search head data to the indexer layer

This documentation applies to the following versions of Splunk® Enterprise: 6.3.0, 6.3.1, 6.3.2, 6.3.3, 6.3.4, 6.3.5, 6.3.6, 6.3.7, 6.3.8, 6.3.9, 6.3.10, 6.3.11, 6.3.12, 6.3.13

Was this documentation topic helpful?

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