Search Manual

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.

• Write a custom search command
• Select a location for your custom search command

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:

1. Create or edit the commands.conf file in a local directory.
2. Add a new stanza to the commands.conf file that describes the command.
3. 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.

1. 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.

2. Describe the type of custom search command in the commands.conf file.
   1. Specify either the streaming or generating 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.
   2. You can also specify whether your custom command retains or transforms events with the retainevents parameter.

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, or cluster commands. Specify 'false' if the command transforms events, similar to the stats 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

Control access to the custom command and script