How to edit a configuration file
To customize a Splunk instance to meet your specific needs, you can edit the built-in configuration settings.
- 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
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/
- 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
localdirectory, open the
- If the configuration file does not exist in your preferred directory, create the file. You are creating an empty file.
- 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:
- Open the
outputs.conffile in your
- Find the
forwardedindex.0.whitelistsetting and change the value to null. For example:
- Save the
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
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
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.
Attribute precedence within a single props.conf file
When to restart Splunk Enterprise after a configuration file change
This documentation applies to the following versions of Splunk® Enterprise: 6.3.0, 6.3.1, 6.3.2, 6.3.3, 6.3.4, 6.3.5, 6.3.6, 6.3.7, 6.3.8, 6.3.9, 6.3.10, 6.3.11, 6.3.12, 6.3.13, 6.3.14, 6.4.0, 6.4.1, 6.4.2, 6.4.3, 6.4.4, 6.4.5, 6.4.6, 6.4.7, 6.4.8, 6.4.9, 6.4.10, 6.4.11, 6.5.0, 6.5.1, 6.5.2, 6.5.3, 6.5.4, 6.5.5, 6.5.6, 6.5.7, 6.5.8, 6.5.9, 6.5.10, 6.6.0, 6.6.1, 6.6.2, 6.6.3, 6.6.4, 6.6.5, 6.6.6, 6.6.7, 6.6.8, 6.6.9, 6.6.10, 6.6.11, 6.6.12, 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.4, 8.0.5