Splunk® Enterprise

Admin Manual

Download manual as PDF

Download topic as PDF

About configuration files

Splunk Enterprise configuration information is stored in configuration files. These files are identified by the .conf extension and hold the information for different aspects of your configurations. These aspects include:

  • System settings
  • Authentication and authorization information
  • Index mappings and setting
  • Deployment and cluster configurations
  • Knowledge objects and saved searches

For a list of configuration files and an overview of the area each file covers, see "List of configuration files" in this manual.

Most configuration files come packaged with your Splunk software in the $SPLUNK_HOME/etc/system/default/ directory.

Use Splunk Web to manage configuration files

When you change your configuration in Splunk Web, that change is written to a copy of the configuration file for that setting. Splunk software creates a copy of this configuration file (if it does not exist), writes the change to that copy, and adds it to a directory under $SPLUNK_HOME/etc/.... The directory that the new file is added to depends on a number of factors that are discussed in "Configuration file directories" in this manual. The most common directory is $SPLUNK_HOME/etc/system/local, which is used in the example.

If you add a new index in Splunk Web, the software performs the following actions:

1. Checks for a copy of the file.

2. If no copy exists, the software creates a copy of indexes.conf and adds it to a directory, such as $SPLUNK_HOME/etc/system/local.

3. Writes the change to the copy of indexes.conf.

4. Leaves the default file unchanged in $SPLUNK_HOME/etc/system/default.

Editing the configuration file directly

While you can do a lot of configuration from Splunk Web or with CLI commands, you can also edit the configuration files directly for any setting. For some advanced customizations that Splunk Web does not support, edit the configuration files directly.

Note: Editing configuration files requires more frequent restarts than making your changes in Splunk Web. See When to restart Splunk Enterprise after a configuration file change.

Important: Never change, copy, or move the configuration files in the default directory. Default files must remain intact and in their original location. To change settings for a particular configuration file, you must first create a new version of the file in a non-default directory and then add the settings that you want to change. When you first create this new version of the file, start with an empty file. Do not start from a copy of the file in the default directory. For information on the directories where you can edit configuration files, see Configuration file directories.

Before you change any configuration files:

  • Learn about how the default configuration files work, and where to put the files that you edit. See Configuration file directories.
  • Learn about the structure of the stanzas that comprise configuration files and how the attributes you want to edit are set up. See Configuration file structure.
  • Learn how different versions of the same configuration files in different directories are layered and combined so that you know the best place to put your file. See Configuration file precedence.
  • Consult the product documentation, including the .spec and .example files for the configuration file. These documentation files reside in the file system in $SPLUNK_HOME/etc/system/README, as well as in the last chapter of this manual.

After you are familiar with the configuration file content and directory structure, and understand how to leverage Splunk Enterprise configuration file precedence, see How to edit a configuration file to learn how to safely modify your files.

PREVIOUS
Customize Splunk Web banner messages
  NEXT
Configuration file directories

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.3.12, 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.4.9, 6.5.0, 6.5.1, 6.5.1612 (Splunk Cloud only), 6.5.2, 6.5.3, 6.5.4, 6.5.5, 6.5.6, 6.6.0, 6.6.1, 6.6.2, 6.6.3, 6.6.4, 7.0.0, 7.0.1


Comments

Sideview -

Thanks for alerting us to this issue. I've updated the material to address the problem.

Sgoodman, Splunker
December 15, 2015

Addendum to my comment -- of course, what's written here is perfectly fine if the user never upgrades splunk ever. But as soon as there's a new splunk release the net effect of the fossilized default file now sitting in local is a big unknown and I've seen it cause both problems and confusion.

Sideview
December 14, 2015

"Do not edit a default configuration file directly. Instead, create a copy and place it in a different directory, the same way Splunk Web does."
This is a super dangerous thing to tell users to make a copy of the entire default file, because now all those stanzas and keys they are copying will override default forever.

What the docs should say is basically "never edit default but instead just add just the stanzas and keys that you need to add/override, to the local file"

Sideview
December 14, 2015

Arpoador, there are several topics in this manual specifically to help Windows customers. See http://docs.splunk.com/Documentation/Splunk/latest/Admin/IntroductionforWindowsadmins for information and navigation to the topics you need.

Cgales splunk
October 30, 2013

Just for fun, assume the user isn't using Linux. Update the doct't to indicate that for the two people using Splunk on Windows, we should look in "Program Files>Splunk>etc>system>local".<br />Sorry for being testy, but I'm running into a storm of poorly thought-out doct'n and it's consuming my whole day to get basic info as I stumble through stuff that should be easy. Eventually I'll learn it, but it won't be because of the Documentation.<br />Thanks. Dave. 650.678.1442

Arpoador
October 30, 2013

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