Use btool to troubleshoot configurations
The Splunk Enterprise configuration file system supports many overlapping configuration files in many different locations. How these configuration files interact with and take precedence over one another is described in Configuration file precedence in the Admin Manual. This flexibility can make it hard to figure out exactly which configuration value Splunk Enterprise is using.
To help you out, Splunk provides
btool. This is a command line tool that can help you troubleshoot configuration file issues or see what values are being used by your Splunk Enterprise installation.
Btool displays merged on-disk configurations. That is, btool shows you the merged settings in the .conf files. It does not necessarily show you what Splunk software is currently using. So for example if you edit a .conf file and do not restart (and the edit requires a restart), btool reports the newly edited settings rather than the settings that are currently being used. To view current in-memory configurations, query the REST endpoint
btool is not officially supported by Splunk. That said, it is what our Support team uses when trying to troubleshoot your issues.
Investigate configuration values of your entire Splunk software instance
You can run
btool to see all the configuration values in use by your Splunk software instance.
./splunk cmd btool <conf_file_prefix> list
<conf_file_prefix> is the name of the configuration file you're interested in (minus the
.conf extension). The
list literal specifies that you want to list the options.
For example, to see what settings transforms.conf is using, type:
./splunk cmd btool transforms list
You probably want to send the results of btool into a text file that you can peruse then delete, like this:
./splunk cmd btool transforms list > /tmp/transformsconfigs.txt
or if not to a file, at least pipe to grep like this:
./splunk cmd btool server list --debug | grep '\['
which determines which server.conf stanzas are being recognized.
Redirecting the output to a file is handy for all use cases of btool, but for simplicity we'll only explicitly mention it this once.
Investigate configuration values in one app
You can also run
btool for a specific app in your Splunk instance. It lists all the configuration values in use by that app for a given configuration file.
btool, go to
$SPLUNK_HOME/bin and type:
./splunk cmd btool --app=<app_name> <conf_file_prefix> list
<app_name> is the name of the app you want to see the configurations for.
For example, if you want to know what configuration options are being used in
props.conf by the Search app, type:
./splunk cmd btool --app=search props list
This returns a list of the
props.conf settings currently being used for the Search app.
The app name is not required. In fact, it is often a good idea not to specify the app when using
btool. In the case of
btool, insight into all of your configurations can be helpful.
Learn where configuration values come from
Another thing you can do with
btool is find out from which specific app Splunk is pulling its configuration parameters for a given configuration file. To do this, add the
--debug flag to
btool like in this example for props.conf:
./splunk cmd btool props list --debug
btool syntax in Command line tools for use with Support.
Check for typos in stanza and setting names
There is a conf checker that runs on "splunk start". You can manually invoke it with the following command:
./splunk cmd btool check
Any typos are printed to stdout. The
cmd is optional.
For example, say your local
indexes.conf has an incorrectly capitalized setting like the following:
$ cat $SPLUNK_HOME/etc/system/local/indexes.conf [hello] #This should be capitalized "homePath". homepath = $SPLUNK_DB/hello/db
The command and its output look like the following:
$ splunk btool check Possible typo in stanza [hello] in /opt/splunk/etc/system/local/indexes.conf, line 3: homepath = $SPLUNK_DB/hello/db
Watch a video on using btool to troubleshoot configuration issues by a Splunk Support engineer.
Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has using btool.
Determine which version of Splunk Enterprise you're running
Splunk on Splunk app
This documentation applies to the following versions of Splunk® Enterprise: 4.3, 4.3.1, 4.3.2, 4.3.3, 4.3.4, 4.3.5, 4.3.6, 4.3.7, 5.0, 5.0.1, 5.0.2, 5.0.3, 5.0.4, 5.0.5, 5.0.6, 5.0.7, 5.0.8, 5.0.9, 5.0.10, 5.0.11, 5.0.12, 5.0.13, 5.0.14, 5.0.15, 5.0.16, 5.0.17, 5.0.18, 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, 6.2.0, 6.2.1, 6.2.2, 6.2.3, 6.2.4, 6.2.5, 6.2.6, 6.2.7, 6.2.8, 6.2.9, 6.2.10, 6.2.11, 6.2.12, 6.2.13, 6.2.14, 6.2.15, 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, 6.3.14, 6.4.0, 6.4.1, 6.4.2, 6.4.3, 6.4.4, 6.4.5, 6.4.6, 6.4.7, 6.4.8, 6.4.9, 6.4.10, 6.4.11, 6.5.0, 6.5.1, 6.5.1612 (Splunk Cloud only), 6.5.2, 6.5.3, 6.5.4, 6.5.5, 6.5.6, 6.5.7, 6.5.8, 6.5.9, 6.5.10, 6.6.0, 6.6.1, 6.6.2, 6.6.3, 6.6.4, 6.6.5, 6.6.6, 6.6.7, 6.6.8, 6.6.9, 6.6.10, 6.6.11, 6.6.12, 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.3.0, 7.3.1