About configuration files

Splunk's configuration information is stored in configuration files, identified by their .conf extension. These files are located under $SPLUNK_HOME/etc.

When you make a change to a configuration setting in Splunk Manager in Splunk Web, the change gets written to the relevant configuration file. This change is written to a copy of the configuration file in a directory under $SPLUNK_HOME/etc (the actual directory depends on a number of factors, discussed later), and the default value of the attribute is left alone in $SPLUNK_HOME/etc/system/default.

You can do a lot of configuration from Manager, but for some more advanced customizations, you must edit the configuration files directly.

The configuration directory structure

The following is the configuration directory structure that exists under $SPLUNK_HOME/etc:

$SPLUNK_HOME/etc/system/default

This contains the pre-configured configuration files. Do not modify the files in this directory.

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

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.

A single Splunk instance typically has multiple versions of some configuration files, across several of these directories. For example, you can have configuration files with the same names in your default, local, and app directories. This provides a layering effect that allows Splunk to determine configuration priorities based on factors such as the current user and the current app. Be sure to review the topic "Configuration file precedence" to understand the precedence rules governing Splunk configuration files. That topic explains how Splunk determines which files have priority.

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.

The default directory

Default configuration files are located in $SPLUNK_HOME/etc/system/default. Never edit the default version of a configuration file. Default files get overwritten each time you upgrade Splunk.

Instead of touching the default files, create or edit versions of the files in any of the other configuration directories, such as $SPLUNK_HOME/etc/system/local. These directories do not get overwritten during upgrades.

Splunk always looks at the default directory last, so any attributes or stanzas that you change in one of the other configuration directories will take precedence over the default version. You can layer several versions of a configuration file on top of one-another, with different attribute values filtering through and being used by Splunk, according to the layering scheme described in "Configuration file precedence". For most deployments, however, you can just use the $SPLUNK_HOME/etc/system/local directory to make configuration changes.

It is also a bad idea to copy a default configuration file to another configuration directory and then edit the copy there. If a default configuration file gets changed by a Splunk upgrade, the change might get blocked by the version of the file you've copied. For example, consider a scenario where some default configuration file has some attribute with a value of 50. Then the Splunk engineering organization subsequently determines that the attribute works better if set to 100, rather than 50. So they change the attribute's value to 100 in a subsequent release. When you next upgrade Splunk, the new version of the file, with the attribute value of 100, overwrites the old version. That's all well and good. However, if in the meantime you've put a copy of the previous version of the file in $SPLUNK_HOME/etc/system/local, Splunk will continue to use the value of 50, since attribute values in $SPLUNK_HOME/etc/system/local take precedence over values in the default directory.

Under limited circumstances and with great care, you can, however, copy a stanza from a default file, edit it, and then put the edited stanza in a new version of the file in $SPLUNK_HOME/etc/system/local or some other such location. But only do this for stanzas and attributes that you need to edit; for the reasons described above, do not copy over more of the configuration file than you actually need to change.

Note: Some configuration files do not have default versions. These configuration files still have .spec and .example files you can look at.

Splunk expects configuration files to be in ASCII/UTF-8. If you are editing or creating a configuration file on an operating system that is non-UTF-8, you must ensure that the editor you are using is configured to save in ASCII/UTF-8.

The structure of configuration files

Configuration files consist of one or more stanzas, or sections. Each stanza begins with a stanza header, designated by square brackets. Following the header is a series of attribute/value pairs that specify configuration settings. Depending on the stanza type, some of the attributes might be required, while others could be optional.

Important: Attributes are case-sensitive. For example, sourcetype = my_app is not the same as SOURCETYPE = my_app. One will work; the other won't.

Stanza scope

Configuration files frequently have stanzas with varying scopes, with the more specific stanzas taking precedence. For example, consider this example of an outputs.conf configuration file, used to configure forwarders:

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 »