About configuration files

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.
• $SPLUNK_HOME/etc/apps/<app_name>/local
  • 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 such that the change only applies to a certain app, copy the file to the app's /local directory 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 files contain 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

"all these worlds are yours, except /default - attempt no editing there"

-- duckfez, 2010

When you edit a configuration file, you should not edit the version in $SPLUNK_HOME/etc/system/default. Instead, make a copy of the file and put it in another configuration directory. Since Splunk always looks at the default directory last, the edited version can go into any of the other available directories, according to whether the edit applies at the system, app, or user level. 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 as described in "Configuration file precedence", but for most deployments, you can just use the $SPLUNK_HOME/etc/system/local directory to make configuration changes.

Another reason not to edit the copies of the configuration files in $SPLUNK_HOME/etc/system/default is that when you upgrade Splunk, all your changes will be overwritten. Changes you make to files in other directories are not overwritten and will continue to take effect post-upgrade.

Important: Some configuration files are not created by default -- if you want to enable the features they manage, you must create the configuration files from scratch. These configuration files still have .spec and .example files for you to review.

Creating and editing configuration files on non-UTF-8 operating systems

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.

Here's the basic pattern:

[stanza1_header]
<attribute1> = <val1>
# comment 
<attribute2> = <val2>
...

[stanza2_header]
<attribute1> = <val1>
<attribute2> = <val2>
...

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.

Note: To add a comment in a configuration file, start the line with a "#" character, as shown above. Comments must comment the whole line. You cannot put a comment on the same line as a stanza heading or an attribute/value pair.

This is the right way to comment

     # do not change this setting
     setting = 25

This way does not work

     setting = 25 # <- comment on the same line is WRONG

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:

[tcpout]
indexAndForward=true

[tcpout:my_indexers]
autoLB=true
compressed=true
server=mysplunk_indexer1:9997, mysplunk_indexer2:9996

[tcpout-server://mysplunk_indexer1:9997]
compressed=false

This example file has three levels of stanzas:

• The global [tcpout], with settings that affect all tcp forwarding.
• The more specific [tcpout:my_indexers], whose settings affect only the target group of indexers named "my_indexers" (whose members are defined within the stanza).
• The most specific [tcpout-server://mysplunk_indexer1:9997], whose settings affect only one specific indexer in the target group.

The setting for compressed in [tcpout-server://mysplunk_indexer1:9997] overrides that attribute's setting in [tcpout:my_indexers], for the indexer "mysplunk_indexer1" only.

For more information on forwarders and outputs.conf, see Configure forwarders with outputs.conf.

List of configuration files, and what's in them

The following is an up-to-date list of the available spec and example files associated with each conf file. Some conf files do not have spec or example files; contact Support before editing a conf file that does not have an accompanying spec or example file.

Important: Do not edit the default copy of any conf file in $SPLUNK_HOME/etc/system/default/. Make a copy of the file in $SPLUNK_HOME/etc/system/local/ or $SPLUNK_HOME/etc/apps/<app_name>/local and edit that copy.

File	Purpose
admon.conf	Configure Windows active directory monitoring.
alert_actions.conf	Create an alert.
app.conf	Configure your custom app.
audit.conf	Configure auditing and event hashing.
authentication.conf	Toggle between Splunk's built-in authentication or LDAP, and configure LDAP.
authorize.conf	Configure roles, including granular access controls.
commands.conf	Connect search commands to any custom search script.
crawl.conf	Configure crawl to find new data sources.
default.meta.conf	A template file for use in creating app-specific default.meta files.
deploymentclient.conf	Specify behavior for clients of the deployment server.
distsearch.conf	Specify behavior for distributed search.
eventdiscoverer.conf	Set terms to ignore for typelearner (event discovery).
event_renderers.conf	Configure event-rendering properties.
eventtypes.conf	Create event type definitions.
fields.conf	Create multivalue fields and add search capability for indexed fields.
indexes.conf	Manage and configure index settings.
inputs.conf	Set up data inputs.
limits.conf	Set various limits (such as maximum result size or concurrent real-time searches) for search commands.
literals.conf	Customize the text, such as search error strings, displayed in Splunk Web.
macros.conf	Define search language macros.
multikv.conf	Configure extraction rules for table-like events (ps, netstat, ls).
outputs.conf	Set up forwarding behavior.
pdf_server.conf	Configure the Splunk pdf server.
procmon-filters.conf	Monitor Windows process data.
props.conf	Set indexing property configurations, including timezone offset, custom source type rules, and pattern collision priorities. Also, map transforms to event properties.
pubsub.conf	Define a custom client of the deployment server.
regmon-filters.conf	Create filters for Windows registry monitoring.
restmap.conf	Create custom Splunk REST endpoints.
savedsearches.conf	Define saved searches and their associated schedules and alerts.
searchbnf.conf	Configure the search assistant.
segmenters.conf	About segmentation.
server.conf	Enable SSL for Splunk's back-end and specify certification locations.
serverclass.conf	Define deployment server classes for use with deployment server.
serverclass.seed.xml.conf	Configure how to seed a deployment client with apps at start-up time.
source-classifier.conf	Terms to ignore (such as sensitive data) when creating a source type.
sourcetypes.conf	Machine-generated file that stores source type learning rules.
sysmon.conf	Set up Windows registry monitoring.
tags.conf	Configure tags for fields.
tenants.conf	Configure deployments in multi-tenant environments.
times.conf	Define custom time ranges for use in the Search app.
transactiontypes.conf	Add additional transaction types for transaction search.
transforms.conf	Configure regex transformations to perform on data inputs. Use in tandem with props.conf.
user-seed.conf	Set a default user and password.
web.conf	Configure Splunk Web, enable HTTPS.
wmi.conf	Set up Windows management instrumentation (WMI) inputs.
workflow_actions.conf	Configure workflow actions.

• Was this topic useful?
• Post a comment