Add the custom command to Splunk Enterprise
After you write your custom search command, you must add the custom command to the appropriate
commands.conf configuration file.
If you use Splunk Cloud, you do not have filesystem access to your Splunk Cloud deployment. You must file a Support ticket to add a custom search command to your deployment.
The main tasks are:
- Create or edit the
commands.conffile in a local directory.
- Add a new stanza to the
commands.conffile that describes the command.
- Restart Splunk Enterprise.
Locating the correct commands.conf file
When you create a custom search command, you must update the
commands.conf file in a local directory.
The default directory,
$SPLUNK_HOME/etc/system/default, contains preconfigured versions of the configuration files. 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.
- Determine the scope of the command.
Scope Description Application-specific custom command Application-specific commands need to be added to the
commands.conffile in the local directory for the application. The location of an application local directory is
System-wide custom command System-wide commands need to be added to the
commands.conffile in local directory for the system. The location of the system local directory is
- Determine whether the
commands.conffile already exists in your preferred local directory. If the file does not exist in the directory, create an empty
commands.conffile in that directory. Do not copy the
commands.conffile from the default directory.
- Edit the local
commands.conffile, to add a stanza for the command.
Add a new stanza to the local commands.conf file
Each stanza in the
commands.conf file represents the configuration for a specific search command. The following example shows a stanza that enables your custom command script:
filename = <string>
STANZA_NAME is the keyword that is used in searches to invoke the command. The
STANZA_NAME is the name of the search command. Search command names must be lowercase and consist only of alphanumeric (a-z and 0-9) characters. Command names must be unique. The
STANZA_NAME cannot be the same as any other custom or built-in commands.
filename attribute specifies the name of your custom command script.
filename attribute also specifies the location of the custom command script.
For example, to create the custom command "fizbin", you create a stanza in the
[fizbin] filename = fizbin.py
Other attributes that you can use to describe the custom command are explained later in this topic.
Where to place the script
The Splunk software expects the custom command script to be in all of the appropriate application directories. In most cases, you should place your script file in an app namespace.
The following table shows where the script file should be located, based on the location of the
commands.conf file that contains the stanza for the custom command.
|Commands.conf file location||Required script file location|
Describe the command
filename attribute merely tells the location of the search script. You can use other attributes to describe the type of command you are adding to the Splunk software. For example, use the
streaming attributes to specify whether it is a generating command, a streaming command, or a command that generates events. For example:
generating = [true|false|stream]
- Specify whether your command generates new events.
- If stream, then your command generates new events (generating = true) and is streamable (streaming = true).
- Defaults to false.
streaming = [true|false]
- Specify whether the command is streamable.
- Defaults to false.
If the custom search command retains or transforms events, include the
retainsevents = [true|false]
- Specify 'true' if the command retains events, similar to the sort, dedup, or cluster commands. Specify 'false' if the command transforms events, similar to the stats command.
- Defaults to false.
Restart Splunk Enterprise
After you add the custom command to the appropriate
commands.conf file, you must restart Splunk Enterprise.
Changes to your custom command script, or to the parameters of an existing command in the
commands.conf file, do not require a restart.
Select a location for your custom search command
Control access to the custom command and script
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