Splunk® Enterprise

Search Manual

Download manual as PDF

Splunk Enterprise version 6.x is no longer supported as of October 23, 2019. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

Select a location for your custom search command

When you create a custom search command, you must update the commands.conf file in a local directory.

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.

Locate the correct commands.conf file

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.

Instead, you need to identify a local directory to put your custom search command in. Selecting the correct location is essential.

  1. Determine the scope of the command.
  2. Scope Description
    Application-specific custom command Add application-specific commands 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 Add system-wide commands 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.

Decide where to place the script

You also need to determine where to place the custom command script file. The Splunk software expects to find the script file 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

If your command is platform-specific, the location is:

$SPLUNK_HOME/etc/system/local $SPLUNK_HOME/etc/system/bin

There is one exception. To use an external process to run our script file, you do not place your script file in the bin directory in your apps. Instead, you must specify the script location in a .path file. The .path file must be stored in one of the bin directories in your apps. See Using external programs to process command scripts.

How the Splunk software finds your custom command

You register a custom search command by adding a stanza in the appropriate local commands.conf file.

For example, to add the custom command "fizbin" to your deployment, you would add the following stanza to the commands.conf file.


Adding the stanza is described in detail in the topic Add the custom command to your Splunk deployment. However, you need to understand how the software locates your custom command script before you actually add the stanza to the commands.conf file.

To find the script to run your custom search command, the Splunk software searches in two places:

  • The default application bin directory, $SPLUNK_HOME/etc/apps/<app_name>/bin/
  • The platform-specific application bin directory, $SPLUNK_HOME/etc/apps/<app_name>/<PLATFORM>/bin/

Platform-specific custom commands

The following table shows the supported platform-specific bin directories and the file extensions that are searched.

Platform architectures Directory File extensions
Linux on 64-bit x86_64 linux_x86_64/bin .sh, .py, .js, and no extension
Linux on 32-bit x86 linux_x86/bin .sh, .py, .js, and no extension
Mac OS X on 64-bit x86_64 darwin_x86_64/bin .sh, .py, .js, and no extension
Windows on 64-bit x86_64 windows_x86_64/bin .bat, .cmd, .py, .js, .exe
Windows on 64-bit x86_64 windows_x86_64/bin .bat, .cmd, .py, .js, .exe

For example, when you use the fizbin command on a Linux 64-bit Splunk instance, the following paths are searched:


The Splunk software stops searching when a file with the same name as the command is found, in this example fizbin.

It is a good idea to include a platform-neutral version of your script in the default application bin directory, $SPLUNK_HOME/etc/apps/<app_name>/bin/. This is useful if someone runs your custom command script on a platform that you did not provide an implementation for.

You can also explicitly specify the script that the Splunk software should look for by specifying the filename attribute in the commands.conf file. For example, assume the fizbin command is defined in the commands.conf file as follows:

filename = fizbin.py

In this example, the Splunk software does not attempt to guess file extension. Instead, the software searches for the fizbin.py file only in the locations where a Python script is expected.


Specifying command arguments

Your specify attributes to use when your command is run by adding command.arg.<N> arguments to the commands.conf file stanza. For example, if you want to pass a flag like --verbose to the fizbin.py script, you add the following attributes in the commands.conf file stanza:

filename = fizbin.py
command.arg.1 = --verbose

You can specify any number of command.arg.<N> arguments. For example:

filename = java.path
command.arg.1 = fizbin.jar
command.arg.2 = -classpath
command.arg.3 = <CLASSPATH>

The last segment of the argument must be a number. Arguments are sent for processing in numerical order. Any numbers that are skipped are ignored. Environment variables, such as $SPLUNK_HOME, are substituted in these arguments.

Using external programs to process command scripts

Searches are processed one command at a time. The results of the previous command are sent to the next command. When the search reaches a custom command, the search uses the protocol to send the results of the previous command to a separate process. The separate process can be a built-in process or an external process.

An image that shows a series of commands. The fizbin command is in the middle of the series. An arrow extends down from the fizbin command to a process for the custom command. An arrow extends from the process back up to the fizbin command. The image explains the the Splunk Custom Command Protocol transports the results to and from the process.

The Splunk software includes a Python interpreter and a JavaScript runtime environment. By default, if your custom command script is Python or JavaScript file, the command script is run on appropriate the script processor that is included with the Splunk software.

If your script is not a Python script or JavaScript file, or if you want to use a script processor that is on your system, you must specify the location of the external program that you want to use to process your script.

For example, you want to use the Python interpreter on your operating system instead of the Python interpreter that is included with the Splunk software.

  1. Create the following two directories:
    • /usr/bin/python
    • $SPLUNK_HOME/bin/python
  2. Create a .path file. The .path file must be stored in one of the bin directories in your apps.
  3. In the commands.conf file, define your command by specifying the filename and command.arg.1 attributes. For example:
    chunked = true
    filename = python.path
    command.arg.1 = fizbin.py

    Absolute paths are not supported in the filename attribute.

In this example, the Splunk software searches for the python.path file.
On 64-bit Linux, the Splunk software finds the <app_name>/linux_x86_64/bin/python.path file. The software reads the contents of the /usr/bin/python directory. The software then runs the script for the custom search command that is located in the /usr/bin/python/fizbin.py file.
On all other platforms, the software finds the <app_name>/bin/python.path file and runs the script located in the $SPLUNK_HOME/bin/python/fizbin.py file.
Any environment variables that are specified, such as $JAVA_HOME are substituted in .path file.

Processing file extensions

When your custom command script is located, the Splunk software looks for a file extension to determine how to run your command.

Filename extension Action
.py The Python interpreter $SPLUNK_HOME/bin/python, that is included with the Splunk software, is used to run your command.
.js The Javascript runtime $SPLUNK_HOME/bin/node, that is included with the Splunk software, is used to run your command.
The script file has no extension, or the file extension is not recognized The Splunk software attempts to run the script directly, without an interpreter. On UNIX-based platforms, this means that the script must have the executable bit set.
Last modified on 19 July, 2016
Write a custom search command
Add the custom command to Splunk Enterprise

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

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