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.
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.confmust 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:
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:
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.
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.5.7, 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, 7.3.7, 7.3.8, 7.3.9, 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.4, 8.0.5, 8.0.6, 8.0.7, 8.0.8, 8.0.9, 8.0.10, 8.1.0, 8.1.1, 8.1.2, 8.1.3, 8.1.4, 8.1.5, 8.1.6, 8.1.7, 8.1.8, 8.1.9, 8.1.10, 8.1.11, 8.2.0, 8.2.1, 8.2.2, 8.2.3, 8.2.4, 8.2.5, 8.2.6, 8.2.7, 9.0.0, 9.0.1