Admin Manual

How to edit a configuration file

To customize a Splunk instance to meet your specific needs, you can edit the built-in configuration settings.

Prerequisites:

• Only users with file system access, such as system administrators, can edit Splunk Enterprise configuration files.
• Before you edit a configuration file, be sure you understand how the entire configuration system works across your Splunk Enterprise deployment and where to make the changes.

The following table describes what you need to know and where to find that information:

You need to know	Learn more
You can have configuration files with the same name in your default, local, and app directories. This creates a layering effect that allows your Splunk deployment to determine configuration priorities. Before you edit a configuration file, you need to know where to create the custom version of the configuration file.	See Configuration file directories.
Configuration files consist of stanzas. Each stanza identifies settings that specify the Splunk Enterprise configuration. Before you edit a configuration file, you need to understand how the file's stanzas are structured.	See Configuration file structure.
Splunk software uses configuration files to set defaults and limitations. A Splunk platform deployment can have multiple copies of the same configuration file in different directories. The ways these copies are layered in the directories affect either the user, an app, or the system as a whole. When you are editing a configuration file, you need to understand how Splunk software evaluates the files in order of importance.	See Configuration file precedence.

Customize a configuration file

To customize a configuration file, create a new file with the same name in a local or app directory. You will then add the specific settings that you want to customize to the local configuration file.

Never change or copy the configuration files in the default directory. The files in the default directory must remain intact and in their original location. The Splunk Enterprise upgrade process overwrites the default directory. 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//local, persist through upgrades.

1. Determine whether the configuration file already exists in your preferred directory. For example, if you want to make changes to a configuration file in your local directory, open the $SPLUNK_HOME/etc/system/local directory.
2. If the configuration file does not exist in your preferred directory, create the file. You are creating an empty file.
3. Edit the configuration file in the preferred directory and add only the stanzas and settings that you want to customize in the local file.

Clear a setting

You can clear a setting to override any previous value that the setting held, including the value set in the default directory. Clearing a setting causes the system to consider the value entirely unset.

You clear a setting by changing its value to null.

For example, suppose you want to clear the forwardedindex.0.whitelist setting in the output.conf file that is in your local directory. You would follow these steps to clear the setting:

1. Open the outputs.conf file in your local directory.
2. Find the forwardedindex.0.whitelist setting and change the value to null. For example:
   
   

   forwardedindex.0.whitelist = 
   

3. Save the outputs.conf file.

Because the settings in the local directory take precedence over the settings in the default directory, when the Splunk software reads the settings, the null setting for forwardedindex.0.whitelist is used.

Insert a comment

When you customize a setting, it is useful to explain why the setting has been customized. Adding comments to configuration files in your local or apps directory is a great way to add these explanations, both for you and for others who might view these files.

To add a comment to a configuration file, insert the pound sign ( # ) before the comment. Start the comment at the beginning of a line.

The best location to put your comment is either before the stanza that setting is under, or before the setting itself. For example:

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

If you have multiple settings in a stanza, then add the comments before each setting. Consider including a date in your comment or placing your comments in all capital letters. For example:

[stanza_name]

# 1/30/2020 - 5 is optimal for our current configuration. 
# This was discussed with both David Mayer and Wei Zhang.
a_setting = 5 

# 9/15/2019 - WE'VE CHANGED THIS SETTING TO "TRUE" BECAUSE IT ENABLES US TO  <your_reason_goes_here>.
b_setting = true

Where not to put your comments

Do not put the comment on the same line as the stanza or the setting.

This example shows where not to place your comments.

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

Placing comments on the same line as a stanza or setting might cause unexpected results. In the following example, the comment is placed on the same line as the setting:

a_setting = 5  #5 is the best number

This sets a_setting to the value 5 #5 is the best number and not to 5 as intended.

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

The Splunk platform works with configuration files with ASCII/UTF-8 encoding.

On operating systems where UTF-8 is not the default character set, such as Windows, configure your text editor to write files in the default character set for that operating system.