
Add the custom command to your Splunk deployment
You must add the custom command to the appropriate commands.conf
configuration file.
Prerequisites
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.conf
file in a local directory. - Add a new stanza to the
commands.conf
file 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:
[<stanza_name>]
chunked=true
filename = <string>
The 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.
The chunked=true
attribute specifies that the command uses the Version 2 protocol.
The filename
attribute specifies the name of your custom command script.
The 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 commands.conf
file.
[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.
Attribute | Description |
---|---|
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 delete and dump . To determine if your custom command is risky, see Safeguards for risky commands in the Securing Splunk Enterprise manual.
|
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
- Generating
- Transforming
- 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
streaming
orgenerating
parameter 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
retainevents
parameter.
- 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 retainevents
attribute:
retainsevents = [true|false]
- Specify 'true' if the command retains events, similar to the
sort
,dedup
, orcluster
commands. Specify 'false' if the command transforms events, similar to thestats
command. - 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.
See also
PREVIOUS Select a location for your custom search command |
NEXT Control access to the custom command and script |
This documentation applies to the following versions of Splunk® Enterprise: 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.1612 (Splunk Cloud only), 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.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4
Feedback submitted, thanks!