Configuration file directories

A single Splunk instance typically has multiple versions of configuration files across several directories. You can have configuration files with the same name 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.

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 file, with different attribute values used by Splunk according to the layering scheme described in "Configuration file precedence".

Never edit configuration files in their default directories. Instead, create and 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 store copies of the configuration files that you want to change. 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 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.