Add the custom command to your Splunk deployment
You must add the custom command to the appropriate
commands.conf configuration file.
Review the following topics.
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 tasks to add a custom command to your deployment 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.
Add a new stanza to the local commands.conf file
Edit the local
commands.conf file, to add a stanza for the command.
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 also 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.
chunked=true attribute specifies that the command uses the Version 2 protocol.
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] chunked = true filename = fizbin.py
Other attributes that you can use to describe the custom command are explained later in this topic.
Describe the command (Version 2 protocol)
Version 2 of the Custom Search Command protocol dynamically determines if the command is a generating command, a streaming command, or a command that generates events.
Additionally, an authentication token is always sent to search commands that use the protocol.
The attributes that you can specify with the protocol are described in the following table.
|command.arg.<N>||Additional command-line arguments to use when invoking the custom search command script. Environment variables such as $SPLUNK_HOME, are substituted.|
|filename||The name of the script to run when the custom search command is used.|
|is_risky||When users click a link or type a URL that loads a search into Splunk Web, if the search contains risky commands a warning appears. This warning does not appear when users create ad hoc searches. Specify this attribute if your custom search command is risky. Examples of build-in risky commands are |
|maxchunksize||The maximum size chunk, the size of metadata plus the size of the body, that the external command can produce. If the command tries to produce a chunk that is larger than the maxchunksiz value, the command is terminated.|
|maxwait||The maximum number of seconds the custom search command can pause before producing output.|
Read more about these configuration attributes in the commands.conf.spec topic in the Admin Manual.
Describe the command (Version 1 protocol)
Some of the attributes you can use to describe your custom command using the Version 1 protocol specify the type of command.
- You need to understand the differences between the types of commands. There are four broad categorizations for all the search commands:
- Distributable streaming
- Centralized streaming
- For a comprehensive explanation about the command types, see Types of commands in this manual. For a complete list of the built-in commands that are in each of these types, see Command types in the Search Reference.
- Describe the type of custom search command in the commands.conf file.
- Specify either the
generatingparameter in commands.conf file. Use these attributes to specify whether it is a generating command, a streaming command, or a command that generates events.
- You can also specify whether your custom command retains or transforms events with the
- Specify either the
For a list of configurable settings, see the commands.conf reference in the Admin Manual. 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
clustercommands. Specify 'false' if the command transforms events, similar to the
- Default is false.
These are only a few of the attributes that you can specify in the stanza for your custom search command.
You can see the full list of configuration attributes in the commands.conf.spec topic in the Admin Manual.
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 Cloud™: 6.6.3, 7.2.3, 7.0.0, 7.0.2, 7.0.3, 7.0.5, 7.1.3