Splunk® Enterprise

Admin Manual

Download manual as PDF

Splunk Enterprise version 5.0 reached its End of Life on December 1, 2017. Please see the migration information.
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF


The following are the spec and example files for distsearch.conf.


#   Version 5.0.3
# This file contains possible attributes and values you can use to configure distributed search.
# To set custom configurations, place a distsearch.conf in $SPLUNK_HOME/etc/system/local/.  
# For examples, see distsearch.conf.example. You must restart Splunk to enable configurations.
# To learn more about configuration files (including precedence) please see the documentation 
# located at http://docs.splunk.com/Documentation/Splunk/latest/Admin/Aboutconfigurationfiles
# These attributes are all configured on the search head, with the exception of the optional attributes listed 
# under the SEARCH HEAD BUNDLE MOUNTING OPTIONS heading, which are configured on the search peers.

# Use the [default] stanza to define any global settings.
#     * You can also define global settings outside of any stanza, at the top of the file.
#     * Each conf file should have at most one default stanza. If there are multiple default
#       stanzas, attributes are combined. In the case of multiple definitions of the same
#       attribute, the last definition in the file wins.
#     * If an attribute is defined at both the global level and in a specific stanza, the
#       value in the specific stanza takes precedence.

* Set distributed search configuration options under this stanza name.
* Follow this stanza name with any number of the following attribute/value pairs.  
* If you do not set any attribute, Splunk uses the default value (if there is one listed).

disabled = [true|false]
* Toggle distributed search off (true) and on (false).
* Defaults to false (your distributed search stanza is enabled by default).

heartbeatMcastAddr = <IP address>
* This setting is deprecated

heartbeatPort = <port>
* This setting is deprecated

ttl = <integer>
* This setting is deprecated

heartbeatFrequency = <int, in seconds>
* This setting is deprecated

statusTimeout = <int, in seconds>
* Set connection timeout when gathering a search peer's basic info (/services/server/info).
* Note: Read/write timeouts are automatically set to twice this value.
* Defaults to 10.
checkTimedOutServersFrequency = <integer, in seconds>
* Rechecks servers at this frequency (in seconds).  
* If this is set to 0, then no recheck will occur.
* Defaults to 60.   

autoAddServers = [true|false]
* This setting is deprecated

bestEffortSearch = [true|false]
* Whether to remove a peer from search when it does not have any of our bundles. 
* If set to true searches will never block on bundle replication, even when a peer is first adde - the 
* peers that don't have any common bundles will simply not be searched.
* Defaults to false

skipOurselves = [true|false]
* This setting is deprecated

servers = <comma separated list of servers>
* Initial list of servers.  

disabled_servers = <comma separated list of servers>
* A list of configured but disabled search peers.

shareBundles = [true|false]
* Indicates whether this server will use bundle replication to share search time configuration
  with search peers. 
* If set to false, the search head assumes that all the search peers can access the correct bundles 
  via share storage and have configured the options listed under "SEARCH HEAD BUNDLE MOUNTING OPTIONS".
* Defaults to true.

useSHPBundleReplication = <bool>|always
* Relevant only in search head pooling environments. Whether the search heads in the pool should compete 
* with each other to decide which one should handle the bundle replication (every time bundle replication 
* needs to happen) or whether each of them should individually replicate the bundles. 
* When set to always and bundle mounting is being used then use the search head pool guid rather than 
* each individual server name to identify bundles (and search heads to the remote peers).
* Defaults to true

serverTimeout = <int, in seconds>
* DEPRECATED, please use  connectionTimeout, sendTimeout, receiveTimeout 

connectionTimeout = <int, in seconds>
* Amount of time in seconds to use as a timeout during search peer connection establishment.

sendTimeout = <int, in seconds>
* Amount of time in seconds to use as a timeout while trying to write/send data to a search peer.

receiveTimeout = <int, in seconds>
* Amount of time in seconds to use as a timeout while trying to read/receive data from a search peer.

authTokenConnectionTimeout = <int, in seconds>
* Maximum number of seconds to connect to a remote search peer, when getting its auth token
* Default is 5

authTokenSendTimeout = <int, in seconds>
* Maximum number of seconds to send a request to the remote peer, when getting its auth token
* Default is 10

authTokenReceiveTimeout = <int, in seconds>
* Maximum number of seconds to receive a response from a remote peer, when getting its auth token
* Default is 10

trySSLFirst = [true|false]
* Controls whether the search head attempts HTTPS or HTTP connection when a new peer is added, or
* during a restart. If value is missing true is assumed.
* Defaults to true



certDir = <directory>
* This directory contains the local Splunk instance's distributed search key pair.
* This directory also contains the public keys of servers that distribute searches to this Splunk instance.

publicKey = <filename>
* Name of public key file for this Splunk instance.

privateKey = <filename>
* Name of private key file for this Splunk instance.

genKeyScript = <command>
* Command used to generate the two files above.



connectionTimeout = <int, in seconds>
* The maximum number of seconds to wait before timing out on inital connection to a peer.

sendRcvTimeout = <int, in seconds>
* The maximum number of seconds to wait for the sending of a full replication to a peer.

replicationThreads = <int>
* The maximum number of threads to use when performing bundle replication to peers.
* Must be a positive number
* Defaults to 5.

maxMemoryBundleSize = <int>
* The maximum size (in MB) of bundles to hold in memory. If the bundle is larger than this
* the bundles will be read and encoded on the fly for each peer the replication is taking place. 
* Defaults to 10

maxBundleSize = <int>
* The maximum size (in MB) of the bundle for which replication can occur. If the bundle is larger than this
* bundle replication will not occur and an error message will be logged.
* Defaults to: 1024 (1GB)

concerningReplicatedFileSize = <int>
* Any individual file within a bundle that is larger than this value (in MB) will trigger a splunkd.log message.
* Where possible, avoid replicating such files, e.g. by customizing your blacklists.
* Defaults to: 50

allowStreamUpload = <bool>
* Whether to enable streaming bundle replication. 
* Defaults to: false

allowSkipEncoding = <bool>
* Whether to avoid URL-encoding bundle data on upload.
* Defaults to: true

allowDeltaUpload = <bool>
* Whether to enable delta-based bundle replication. 
* Defaults to: true

sanitizeMetaFiles = <bool>
* Whether to sanitize or filter *.meta files before replication.
* This feature can be used to avoid unnecessary replications triggered by writes to *.meta files that have no real effect on search behavior.
* The types of stanzas that "survive" filtering are configured via the replicationSettings:refineConf stanza.
* The filtering process removes comments and cosmetic whitespace.
* Defaults to: true


replicate.<conf_file_name> = <bool>
* Controls whether Splunk replicates a particular type of *.conf file, along with any associated permissions in *.meta files.
* These settings on their own do not cause files to be replicated. A file must still be whitelisted (via replicationWhitelist) to be eligible for inclusion via these settings.
* In a sense, these settings constitute another level of filtering that applies specifically to *.conf files and stanzas with *.meta files.
* Defaults to: false



<name> = <whitelist_pattern>
* Controls Splunk's search-time conf replication from search heads to search nodes.
* Only files that match a whitelist entry will be replicated.
* Conversely, files which are not matched by any whitelist will not be replicated.
* Only files located under $SPLUNK_HOME/etc will ever be replicated in this way.
    * The regex will be matched against the filename, relative to $SPLUNK_HOME/etc.
      Example: for a file "$SPLUNK_HOME/etc/apps/fancy_app/default/inputs.conf"
               this whitelist should match "apps/fancy_app/default/inputs.conf"
    * Similarly, the etc/system files are available as system/... 
      user-specific files are available as users/username/appname/...
* The 'name' element is generally just descriptive, with one exception: if <name>
  begins with "refine.", files whitelisted by the given pattern will also go through
  another level of filtering configured in the replicationSettings:refineConf stanza.
* The whitelist_pattern is the Splunk-style pattern matching, which is primarily
  regex-based with special local behavior for '...' and '*'.
  * ... matches anything, while * matches anything besides directory separators.  
    See props.conf.spec for more detail on these.
  * Note '.' will match a literal dot, not any character.
* Note that these lists are applied globally across all conf data, not to any
  particular app, regardless of where they are defined.  Be careful to pull in
  only your intended files.



<name> = <blacklist_pattern>
* All comments from the replication whitelist notes above also apply here.
* Replication blacklist takes precedence over the whitelist, meaning that a
  file that matches both the whitelist and the blacklist will NOT be replicated.
* This can be used to prevent unwanted bundle replication in two common scenarios:
   * Very large files, which part of an app may not want to be replicated,
     especially if they are not needed on search nodes.
   * Frequently updated files (for example, some lookups) will trigger retransmission of
     all search head data.
* Note that these lists are applied globally across all conf data. Especially
  for blacklisting, be careful to constrain your blacklist to match only data
  your application will not need.

# You set these attributes on the search peers only, and only if you also set shareBundles=false 
# in [distributedSearch] on the search head. Use them to achieve replication-less bundle access. The 
# search peers use a shared storage mountpoint to access the search head bundles ($SPLUNK_HOME/etc).

* <searchhead-splunk-server-name> is the name of the related searchhead installation.
* This setting is located in server.conf, serverName = <name>

mounted_bundles = [true|false]
* Determines whether the bundles belong to the search head specified in the stanza name are mounted.
* You must set this to "true" to use mounted bundles.
* Default is "false".

bundles_location = <path_to_bundles>
* The path to where the search head's bundles are mounted. This must be the mountpoint on the search peer, 
* not on the search head. This should point to a directory that is equivalent to $SPLUNK_HOME/etc/. It must
* contain at least the following subdirectories: system, apps, users.


#   Version 5.0.3
# These are example configurations for distsearch.conf. Use this file to configure distributed search.  For all 
# available attribute/value pairs, see distsearch.conf.spec.
# There is NO DEFAULT distsearch.conf.
# To use one or more of these configurations, copy the configuration block into distsearch.conf 
# in $SPLUNK_HOME/etc/system/local/.  You must restart Splunk to enable configurations.
# To learn more about configuration files (including precedence) please see the documentation 
# located at http://docs.splunk.com/Documentation/Splunk/latest/Admin/Aboutconfigurationfiles

servers =,

# This entry distributes searches to,
# Attributes not set here will use the defaults listed in distsearch.conf.spec.

#this stanza controls the timing settings for connecting to a remote peer and the send timeout
connectionTimeout = 10
sendRcvTimeout = 60

#this stanza controls what files are replicated to the other peer each is a regex
allConf = *.conf

# Mounted bundles example.
# This example shows two distsearch.conf configurations, one for the search head and another for each of the
# search head's search peers. It shows only the attributes necessary to implement mounted bundles.

# On a search head whose Splunk server name is "searcher01":
shareBundles = false

# On each search peer:
mounted_bundles = true
bundles_location = /opt/shared_bundles/searcher01


This documentation applies to the following versions of Splunk® Enterprise: 5.0.3


Tphi - You're right. That statement is obsolete. I'll expunge it.

November 4, 2013

In your document above I see the following:<br /><br />"# There is NO DEFAULT distsearch.conf."<br /><br />This is incorrect as I have found it in version 5.0.3:<br /><br />-bash-3.2$ pwd<br />.../splunk/etc/system/default<br />-bash-3.2$ ls -la distsearch.conf <br />-r--r----- 1 splunk splunk 1910 May 15 12:34 distsearch.conf

November 2, 2013

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