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.

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

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.

$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.

Comments

Bkarumuri - That's an interesting point. Not sure about "override", but perhaps "version" would work as a substitute. I'll give it some thought.

Sgoodman, Splunker

June 3, 2019

`store copies of the configuration files that you want to change`.
These are really not copies of the configuration files but overrides for the default configuration files. I see `copy of` used in lot of places, which could be misleading.

Bkarumuri splunk, Splunker

May 30, 2019

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.

Enter your email address, and someone from the documentation team will respond to you:

Send me a copy of this feedback

Please provide your comments here. Ask a question or make a suggestion.

Feedback submitted, thanks!

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

Your Comment Has Been Posted Above

We use our own and third-party cookies to provide you with a great online experience. We also use these cookies to improve our products and services, support our marketing campaigns, and advertise to you on our website and other websites. Some cookies may continue to collect information after you have left our website.
Learn more (including how to update your settings) here Â»