Search Manual

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.

   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 .

2. 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 executable

You also need to determine where to place the custom command executable file. The Splunk software expects to find the executable file in all of the appropriate application directories. In most cases, you should place your executable file in an app namespace.

The following table shows where the executable 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/apps/<app_name>/<PLATFORM>/bin/
$SPLUNK_HOME/etc/system/local	$SPLUNK_HOME/etc/system/bin

There is one exception. To use an external process to run your executable file, you do not place your executable file in the bin directory in your apps. Instead, you must specify the executable 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 executables.

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.

[fizbin]
chunked = true

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 executable before you actually add the stanza to the commands.conf file.

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

• The platform-specific application bin directory,

$SPLUNK_HOME/etc/apps/<app_name>/<PLATFORM>/bin/

• The default application bin directory, $SPLUNK_HOME/etc/apps/<app_name>/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:

$SPLUNK_HOME/etc/apps/<app_name>/linux_x86_64/bin/fizbin.sh
$SPLUNK_HOME/etc/apps/<app_name>/linux_x86_64/bin/fizbin.py
$SPLUNK_HOME/etc/apps/<app_name>/linux_x86_64/bin/fizbin.js
$SPLUNK_HOME/etc/apps/<app_name>/linux_x86_64/bin/fizbin
$SPLUNK_HOME/etc/apps/<app_name>/bin/fizbin.sh
$SPLUNK_HOME/etc/apps/<app_name>/bin/fizbin.py
$SPLUNK_HOME/etc/apps/<app_name>/bin/fizbin.js
$SPLUNK_HOME/etc/apps/<app_name>/bin/fizbin

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 executable in the default application bin directory, $SPLUNK_HOME/etc/apps/<app_name>/bin/. This is useful if someone runs your custom command executable on a platform that you did not provide an implementation for.

You can also explicitly specify the executable 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:

[fizbin]
chunked = true
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 executable is expected.

$SPLUNK_HOME/etc/apps/<app_name>/linux_x86_64/bin/fizbin.py
$SPLUNK_HOME/etc/apps/<app_name>/bin/fizbin.py

Processing file extensions

When your custom command executable 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 Node.js runtime $SPLUNK_HOME/bin/node, that is included with the Splunk software, is used to run your command.
The executable file has no extension, or the file extension is not recognized	The Splunk software attempts to run the executable directly, without an interpreter. On UNIX-based platforms, this means that the executable must have the executable bit set.

Specifying command arguments

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

[fizbin]
chunked = true
filename = fizbin.py
command.arg.1 = --verbose

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

[fizbin]
chunked = true
filename = java.path   #See the next section for filename examples
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 executables

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.

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

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

Java example

For example, you want to use a Java file to run the custom search. The Splunk software does not include a Java runtime environment (JRE). You need to specify the path to the JRE.

1. Create a .path file, such as $SPLUNK_HOME/etc/apps/<app_name>/bin/java.path. The .path file must be stored in one of the bin directories in your applications.
2. In the .path file, specify the path to the Java runtime environment (JRE). For example, /usr/bin/java.
3. In the commands.conf file, define your command by specifying the filename and the command.arg.N arguments. Absolute paths are not supported in the filename attribute. The following example shows the stanza for the fizbin command.

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

In this example, the Splunk software searches for the java.path file.

Any environment variables that are specified, such as $JAVA_HOME are substituted in the .path file.

Python example

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

1. Create a .path file, such as $SPLUNK_HOME/etc/apps/<app_name>/bin/system_python.path. The .path file must be stored in one of the bin directories in your apps.
2. In the .path file, specify the path to the Python interpreter. For example, /usr/bin/python.
3. In the commands.conf file, define your command by specifying the filename and command.arg.1 attributes. Absolute paths are not supported in the filename attribute. The following example shows the stanza for the fizbin command.

   [fizbin]
   chunked = true
   filename = system_python.path
   command.arg.1 = fizbin.py
   

In this example, the Splunk software searches for the system_python.path file.

Any environment variables that are specified, such as $PYTHON_PATH are substituted in .path file.

See also

Add the custom command to your Splunk deployment