How to edit a configuration file

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

Prerequisites

You must meet the following prerequisites to edit configuration files:

• You must be a user with file system access, such as a system administrator.
• You must understand how the configuration system works across your deployment and where to make the changes.

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

What to know	Documentation
You can have configuration files with the same name in your default, local, and app directories. This layering effect that allows your Splunk platform 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 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 files in order of importance.	See Configuration file precedence.
If your deployment includes search head or indexer clusters, some changes you make to configuration files may need to be made to configuration files on every search head cluster member or indexer peer node. Before you edit a configuration file, you need to understand whether to make the same change to the configuration file on every search head or indexer in the cluster.	See Use the deployer to distribute apps and configuration updates in Distributed Search and Update common peer configurations and apps in Managing Indexers and Clusters of Indexers.

Customize a configuration file

To customize a configuration file, create a new file with the same name in a local or app directory. 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/<app_name>/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. 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 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 you customized the setting. 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 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 within 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 Alex Garcia and Wei Zhang.
a_setting = 5 

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

Where not to put your comments

Do not put comments 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 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.

Best practices for editing configuration files

When editing your configuration files, follow these best practices:

Best practice	Description
Spell the name of the setting correctly.	For best results, copy the setting name from the corresponding specification file.
Verify the capitalization is correct in the names of settings.	Setting names are case-sensitive. That is, for a setting named someAttribute, you cannot substitute SomeAttribute or someattribute.
Place the setting in the stanza where it belongs. Many settings only operate within a particular context and require you to place them within the stanza for that context.	Refer to the specification files for guidance on stanza requirements. As an example, indexer clustering settings in the server.conf file must be placed within the [clustering] stanza.
Place the setting so that it applies to the desired scope. Some settings can be applied either globally or within a specific scope.	To apply the setting globally, place the setting towards the start of the configuration file, prior to any stanza. When the setting has a specific scope, place the setting within the stanza for that scope. For example, in the indexes.conf file, some settings can be applied either on a per-index basis or globally, for all indexes. If you want a particular value for the setting to apply to just a single index, place the setting under that index's stanza. Similarly, if you want a setting to apply to all indexes, place the setting above all stanzas. You can also place a setting with one value above the stanzas and then add the setting with a different value to one or more index stanzas. That way, each index uses the global value except where the setting's value has been modified for a specific index.
Do not add the same setting twice within the same context. If you do, the final instance of the setting will take effect.	If you add the same setting twice within the same context, you might find yourself confused at some later date. For example, say you add this stanza and setting: [some stanza] setting=foo Then, someone later adds a stanza with the same name but a different value for the setting further down in the file: [some stanza] setting=bar The setting now has a value of bar, because the second instance is further down in the file. However, this can cause confusion if someone later tries to change the setting and encounters the first instance of the setting but not the second.