Configuration file directories
A Splunk Enterprise installation can have multiple versions of a configuration file located across several directories. For example, you might have the same configuration file with different settings located in each of the default, local, and app directories. Splunk Enterprise uses a layering scheme and rules to evaluate overlapping configurations and prioritize them.
When you need to override a setting that's been defined as a default, you can place a customized configuration file in a different folder path under the Splunk Enterprise installation. For a description and examples of how precedence is determined, see Configuration file precedence.
A detailed list of settings for each configuration file is provided in the .spec
file named for that configuration file. You can find the latest version of the .spec
and .example
files in the $SPLUNK_HOME/etc/system/README
folder of your Splunk Enterprise installation, or in the documentation at the configuration file reference.
About the default files
The default directory contains preconfigured versions of the configuration files with default settings. The location of the default directory in a Splunk Enterprise installation is $SPLUNK_HOME/etc/system/default
.
"all these worlds are yours, except /default - attempt no editing there" -- duckfez, 2010
You should never change a configuration file that's located in the $SPLUNK_HOME/etc/system/default
directory. The Splunk Enterprise upgrade process overwrites the contents in that folder automatically, which will remove any changes. If you want to retain a setting you've changed through an upgrade, place your configuration file into a local
folder path such as $SPLUNK_HOME/etc/system/local
or $SPLUNK_HOME/etc/apps/$app_name/local
as described below.
The upgrade process also inspects the content in the $SPLUNK_HOME/etc/system/local
Where you can place (or find) your modified configuration files
To change the settings in a particular configuration file, you must first create a new file of the same name in a non-default directory, and add the required settings and changed values to your new configuration file. A setting with a new value defined in a non-default directory will take precedence over a setting defined in the default directory.
When changing a default setting using a new configuration file, you only need to define the stanza category, the setting, and update the value. Do not make a complete copy of the configuration file from the default directory into another folder, as the settings in that copy will take precedence and override changes made during an upgrade.
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.
About configuration files | Configuration file structure |
This documentation applies to the following versions of Splunk® Enterprise: 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10, 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
Feedback submitted, thanks!