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.

Common editing mistakes

While editing your configuration files, be careful to avoid some common mistakes:

• Spell the name of the setting correctly. For best results, copy the setting name from the corresponding specification file.
  
  
• Watch capitalization in the names of settings. As with passwords, case matters. 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 thus require you to place them within the stanza for that context.
  
  As an example, indexer clustering settings in server.conf must be placed under the [clustering] stanza. The specification files provide clear guidance on stanza requirements.
  
  
• 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 top 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 indexes.conf, 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 setting twice within the same context. If you do, the final instance of the setting will take effect, but you might find yourself confused at some later date. For example: say you add a stanza and setting:
  
  [some stanza]
setting=foo.
  
  Then someone later comes along and 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 will have the value of "bar", because the second instance is further down in the file. However, confusion might result when someone later tries to change the setting and encounters the first instance of the setting but not the second.