Splunk® Enterprise

Search Manual

Download manual as PDF

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

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:

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

  1. Determine the scope of the command.
  2. Scope Description
    Application-specific custom command Application-specific commands need to be added to the commands.conf file in the local directory for the application. The location of an application local directory is $SPLUNK_HOME/etc/apps/<app_name>/local.
    System-wide custom command System-wide commands need to be added to the commands.conf file in local directory for the system. The location of the system local directory is $SPLUNK_HOME/etc/system/local .
  3. Determine whether the commands.conf file already exists in your preferred local directory. If the file does not exist in the directory, create an empty commands.conf file in that directory. Do not copy the commands.conf file from the default directory.
  4. Edit the local commands.conf file, 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:

[<STANZA_NAME>]
filename = <string>

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

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]
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
$SPLUNK_HOME/etc/apps/<app_name>/local $SPLUNK_HOME/etc/apps/<app_name>/bin
$SPLUNK_HOME/etc/system/local $SPLUNK_HOME/etc/system/bin

Describe the command

The 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 generating and 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 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.
  • 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.

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.2.0, 6.2.1, 6.2.2, 6.2.3, 6.2.4, 6.2.5, 6.2.6, 6.2.7, 6.2.8, 6.2.9, 6.2.10, 6.2.11, 6.2.12, 6.2.13, 6.2.14, 6.2.15, 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


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters