Splunk® Enterprise

Troubleshooting Manual

Download manual as PDF

Splunk Enterprise version 7.2 will no longer be supported as of April 30, 2021. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.
Download topic as PDF

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.

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 questions and answers about using btool

See what questions and answers the Splunk community has using btool.

Watch a Splunk Support engineer talk about btool

If you want to watch how Splunk Support uses the btool command to troubleshoot configurations:

Last modified on 10 February, 2020
PREVIOUS
Determine which version of Splunk Enterprise you're running
  NEXT
Splunk on Splunk app

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, 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.4, 8.0.5, 8.0.6, 8.1.0


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