Use btool to troubleshoot configurations
If you're trying to figure out what settings are set on a Splunk Enterprise instance, and you want to see where those settings are configured, use the btool command-line tool.
Splunk software configuration files, also referred to as conf files, are loaded and merged to make a working set of configurations that are used by Splunk software when performing tasks. The conf files can be placed in many different folders under the Splunk software installation. The btool command simulates the merging process using the on-disk conf files and creates a report showing the merged settings.
The report output is sent to the command prompt in order of precedence. To learn the rules for merging and precedence of conf file settings, see Configuration file precedence in the Admin Manual.
The report does not necessarily represent what's loaded in memory. If a conf file change is made that requires a service restart, the btool report shows the change even though that change isn't active.
The btool command is unsupported and receives infrequent updates. However, it is a very useful validation tool that is included with all Splunk software releases. The output from the btool command is often requested in support cases and is automatically included when generating diag files.
btool does not display the default stanza of an inputs.conf file.
Review the merged settings for a conf file
You might want to see all input configurations on the forwarder.
- Using a shell prompt, go to the folder
$SPLUNK_HOME/bin
in *nix or%SPLUNK_HOME%\bin
in Windows. - Run the following command:
splunk btool <conf_file_prefix> list
*nix example | Windows example |
---|---|
./splunk btool inputs list |
splunk btool inputs list |
Review the merged settings for a conf file in an app context
You might want to see all input configurations contained in the search app on the forwarder.
- Using a shell prompt, go to the folder
$SPLUNK_HOME/bin
in *nix or%SPLUNK_HOME%\bin
in Windows. - Run the following command:
splunk btool --app=<app> <conf_file_prefix> list
*nix example | Windows example |
---|---|
./splunk btool --app=search inputs list |
splunk btool --app=search inputs list |
Review the settings for a conf file and see where the settings are merged from
You might want to see all input configurations on the forwarder and in what context they are set.
- Using a shell prompt, go to the folder
$SPLUNK_HOME/bin
in *nix or%SPLUNK_HOME%\bin
in Windows. - Run the following command:
splunk btool <conf_file_prefix> list --debug
*nix example | Windows example |
---|---|
./splunk btool inputs list --debug |
splunk btool inputs list --debug |
Review the settings for a conf file and see where the settings are merged from in an app context
You might want to see all props configurations set in the search app on the forwarder, and in what context they are set.
- Using a shell prompt, go to the folder
$SPLUNK_HOME/bin
in *nix or%SPLUNK_HOME%\bin
in Windows. - Run the following command:
splunk btool <conf_file_prefix> list --app=<app> --debug
*nix example | Windows example |
---|---|
./splunk btool props list --app=search --debug |
splunk btool props list --app=search --debug |
Find a specific setting for a conf file
You might want to find an input stanza on the forwarder and you know the stanza name.
- Using a shell prompt, go to the folder
$SPLUNK_HOME/bin
in *nix or%SPLUNK_HOME%\bin
in Windows. - Run the following command:
splunk btool <conf_file_prefix> list | grep <string>
*nix example | Windows example |
---|---|
./splunk btool inputs list | grep splunktcp |
splunk btool inputs list | findstr splunktcp |
Find a specific setting for a conf file and see where the setting is merged from
You might want to find an input stanza on the forwarder and in what context it's set, and you know the stanza name.
- Using a shell prompt, go to the folder
$SPLUNK_HOME/bin
in *nix or%SPLUNK_HOME%\bin
in Windows. - Run the following command:
splunk btool <conf_file_prefix> list --debug | grep <string>
*nix example | Windows example |
---|---|
./splunk btool inputs list --debug | grep splunktcp |
splunk btool inputs list --debug | findstr splunktcp |
Find a specific setting for a conf file, see where the settings is merged from, and place the report into a file
You might want to find an input stanza on the forwarder and in what context it's set, and you know the stanza name. And you want the report in a file.
- Using a shell prompt, go to the folder
$SPLUNK_HOME/bin
in *nix or%SPLUNK_HOME%\bin
in Windows. - Run the following command:
splunk btool <conf_file_prefix> list --debug | grep <string> > /tmp/$filename
*nix example | Windows example |
---|---|
./splunk btool inputs list --debug | grep splunktcp > /tmp/inputs_splunktcp |
splunk btool inputs list --debug | findstr splunktcp > C:\Windows\Temp\inputs_splunktcp.txt |
Look for the error if you see a "typo in stanza" message
When restarting services, you notice the Splunk Enterprise instance reports that there's a "typo in stanza."
- Using a shell prompt, go to the folder
$SPLUNK_HOME/bin
in *nix or%SPLUNK_HOME%\bin
in Windows. - Run the following command:
splunk btool check
*nix example | Windows example |
---|---|
./splunk btool check
|
splunk btool check
|
What the btool command can't do
Here are some limitations to btool:
- The btool command only accepts one conf file at a time for analysis. See List of configuration files in the Admin Manual. To search for configurations across multiple conf files, use your operating system's search tool.
- If the user running btool does not have read access to a conf file due to permission issues, the settings in those files are not shown in the report.
- The switch
btool --app
does not consider metadata inheritance, and misreports settings that are inherited from other apps. - The switch
btool --user
must be used with switchbtool --app
. If a user is set, an app context must also be set. - The switch
btool --user
does not consider knowledge object permissions when evaluating the user.
Additional resources
See more btool command syntax in Command line tools for use with Support.
See what questions and answers the Splunk community has using btool: https://community.splunk.com/t5/tag/btool/tg-p.
Determine which version of Splunk Enterprise you're running | What Splunk software logs about itself |
This documentation applies to the following versions of Splunk® Enterprise: 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.2.8, 7.2.9, 7.2.10, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.7, 7.3.8, 7.3.9, 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.4, 8.0.5, 8.0.6, 8.0.7, 8.0.8, 8.0.9, 8.0.10, 8.1.0, 8.1.1, 8.1.2, 8.1.3, 8.1.4, 8.1.5, 8.1.6, 8.1.7, 8.1.8, 8.1.9, 8.1.10, 8.1.11, 8.1.12, 8.1.13, 8.1.14, 8.2.0, 8.2.1, 8.2.2, 8.2.3, 8.2.4, 8.2.5, 8.2.6, 8.2.7, 8.2.8, 8.2.9, 8.2.10, 8.2.11, 8.2.12, 9.0.0, 9.0.1, 9.0.2, 9.0.3, 9.0.4, 9.0.5, 9.0.6, 9.0.7, 9.0.8, 9.0.9, 9.0.10, 9.1.0, 9.1.1, 9.1.2, 9.1.3, 9.1.4, 9.1.5, 9.1.6, 9.2.0, 9.2.1, 9.2.2, 9.2.3, 9.3.0, 9.3.1
Feedback submitted, thanks!