Splunk® Enterprise

Admin Manual

Download manual as PDF

Download topic as PDF

Configuration file directories

A single Splunk instance typically has multiple versions of configuration files across several of directories. You can have configuration files with the same names in your default, local, and app directories. This creates a layering effect that allows Splunk to determine configuration priorities based on factors such as the current user and the current app.

To learn more about how configurations are prioritized by Splunk, see "Configuration file precedence".

Note: The most accurate list of settings available for a given configuration file is in the .spec file for that configuration file. You can find the latest version of the .spec and .example files in the "Configuration file reference", or in $SPLUNK_HOME/etc/system/README.

About the default files

"all these worlds are yours, except /default - attempt no editing there"

-- duckfez, 2010

The default directory contains preconfigured versions of the configuration files. The location of the default directory is $SPLUNK_HOME/etc/system/default.

Important: Never change or copy the configuration files in the default directory. Default files must remain intact and in their original location. The Splunk Enterprise upgrade process overwrites the default directory, so any changes that you make in the default directory are lost on upgrade. Changes that you make in non-default configuration directories, such as $SPLUNK_HOME/etc/system/local or $SPLUNK_HOME/etc/apps/<app_name>/local, persist through upgrades.

To change attribute values for a particular configuration file, you must first create a new version of the file in a non-default directory and then modify the values there. Values in a non-default directory have precedence over values in the default directory.

Note: When you first create this new version of the file, start with an empty file and add only the attributes that you need to change. Do not start from a copy of the default directory. If you copy the entire default file to a location with higher precedence, any changes to the default values that occur through future Splunk Enterprise upgrades cannot take effect, because the values in the copied file will override the updated values in the default file.

Where you can place (or find) your modified configuration files

You can layer several versions of a configuration files, with different attribute values used by Splunk according to the layering scheme described in "Configuration file precedence".

Never edit files in their default directories. Instead, create and/or edit your files in one of the configuration directories, such as $SPLUNK_HOME/etc/system/local. These directories are not overwritten during upgrades.

For most deployments you can use the $SPLUNK_HOME/etc/system/local directory to make configuration changes. However, in certain situations you may want to work with the files in other directories. The following is the configuration directory structure in $SPLUNK_HOME/etc:

  • $SPLUNK_HOME/etc/system/local
    • Local changes on a site-wide basis go here; for example, settings you want to make available to all apps. If the configuration file you're looking for doesn't already exist in this directory, create it and give it write permissions.
  • $SPLUNK_HOME/etc/slave-apps/[_cluster|<app_name>]/[local|default]
    • For cluster peer nodes only.
    • The subdirectories under $SPLUNK_HOME/etc/slave-apps contain configuration files that are common across all peer nodes.
    • Do not change the content of these subdirectories on the cluster peer itself. Instead, use the cluster master to distribute any new or modified files to them.
    • The _cluster directory contains configuration files that are not part of real apps but that still need to be identical across all peers. A typical example is the indexes.conf file.
    • For more information, see "Update common peer configurations" in the Managing Indexers and Clusters manual.
  • $SPLUNK_HOME/etc/apps/<app_name>/[local|default]
    • If you're in an app when a configuration change is made, the setting goes into a configuration file in the app's /local directory. For example, edits for search-time settings in the default Splunk search app go here: $SPLUNK_HOME/etc/apps/search/local/.
    • If you want to edit a configuration file so that the change only applies to a certain app, copy the file to the app's /local directory (with write permissions) and make your changes there.
  • $SPLUNK_HOME/etc/users
    • User-specific configuration changes go here.
  • $SPLUNK_HOME/etc/system/README
    • This directory contains supporting reference documentation. For most configuration files, there are two reference files: .spec and .example; for example, inputs.conf.spec and inputs.conf.example. The .spec file specifies the syntax, including a list of available attributes and variables. The .example file contains examples of real-world usage.
About configuration files
Configuration file structure

This documentation applies to the following versions of Splunk® Enterprise: 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.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.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.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.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.5.0, 6.5.1, 6.5.1612 (Splunk Cloud only), 6.5.2, 6.5.3, 6.5.4, 6.6.0, 6.6.1


Sideview - Thanks for noting the issue with copying the default files. I've updated the material to correct this.

Sgoodman, Splunker
December 15, 2015

" You should never modify the files in this directory. Instead, you should edit a copy of the file in your local or app directory:" -- doing this is not a best practice, as it basically casts that release's version of the default file in stone. When the admin upgrades Splunk the old defaults will apply to the new build and this can cause both problems and user confusion.

December 14, 2015

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