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.

1. Using a shell prompt, go to the folder $SPLUNK_HOME/bin in *nix or %SPLUNK_HOME%\bin in Windows.
2. 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.

1. Using a shell prompt, go to the folder $SPLUNK_HOME/bin in *nix or %SPLUNK_HOME%\bin in Windows.
2. 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.

1. Using a shell prompt, go to the folder $SPLUNK_HOME/bin in *nix or %SPLUNK_HOME%\bin in Windows.
2. 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.

1. Using a shell prompt, go to the folder $SPLUNK_HOME/bin in *nix or %SPLUNK_HOME%\bin in Windows.
2. 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.

1. Using a shell prompt, go to the folder $SPLUNK_HOME/bin in *nix or %SPLUNK_HOME%\bin in Windows.
2. 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.

1. Using a shell prompt, go to the folder $SPLUNK_HOME/bin in *nix or %SPLUNK_HOME%\bin in Windows.
2. 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.

1. Using a shell prompt, go to the folder $SPLUNK_HOME/bin in *nix or %SPLUNK_HOME%\bin in Windows.
2. 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."

1. Using a shell prompt, go to the folder $SPLUNK_HOME/bin in *nix or %SPLUNK_HOME%\bin in Windows.
2. 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 switch btool --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.