Splunk® Enterprise

Admin Manual

Download manual as PDF

Splunk version 4.x reached its End of Life on October 1, 2013. Please see the migration information.
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

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

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

Instead, create or edit 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.

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.

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:

[tcpout]
indexAndForward=true
compressed=true

[tcpout:my_indexersA]
autoLB=true
compressed=false
server=mysplunk_indexer1:9997, mysplunk_indexer2:9997

[tcpout:my_indexersB]
autoLB=true
server=mysplunk_indexer3:9997, mysplunk_indexer4:9997

This example file has two levels of stanzas:

  • The global [tcpout], with settings that affect all tcp forwarding.
  • Two [tcpout:<target_list>] stanzas, whose settings affect only the indexers defined in each target group.

The setting for compressed in [tcpout:my_indexersA] overrides that attribute's setting in [tcpout], for the indexers in the my_indexersA target group only.

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

A few syntax notes

There are a couple of miscellaneous things to keep in mind when editing configuration files.

Clear attributes

You can clear any attribute by setting it to null. For example:

forwardedindex.0.whitelist = 

This overrides any previous value that the attribute held, including any value set in its default file, causing the system to consider the value entirely unset.

Use comments

You can insert comments in configuration files. To do so, use the # sign:

# This stanza forwards some log files.
[monitor:///var/log]

Important: Start the comment at the left margin. Do not put the comment on the same line as the stanza or attribute:

[monitor:///var/log]    # This is a really bad place to put your comment.

For an attribute, such as

a_setting = 5  #5 is the best number

This sets the a_setting attribute to the value "5 #5 is the best number", which may cause unexpected results.

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.
PREVIOUS
About Splunk Manager
  NEXT
Configuration file precedence

This documentation applies to the following versions of Splunk® Enterprise: 4.3, 4.3.1, 4.3.2, 4.3.3, 4.3.4, 4.3.5, 4.3.6, 4.3.7


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