Splunk® Enterprise

Search Manual

Download manual as PDF

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

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

PREVIOUS
Write a custom search command
  NEXT
Add the custom command to your Splunk deployment

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.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.6.0, 6.6.1, 6.6.2, 6.6.3, 6.6.4, 7.0.0


Comments

Hello DUThibault -
Thank you for your comments.
In the "How the Splunk software finds your custom command" section, I corrected the directory order.
In the "Specifying command arguments" section and "Using external programs to process command executables" section, I have clarified the information by adding specific examples for Java and Python. The paragraphs that referenced specific platforms has been removed and information added to explain this better.

Lstewart splunk, Splunker
November 16, 2017

In the "How the Splunk software finds your custom command" section, the Splunk search directories are in the wrong order. They should be (as the example shows):

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/

In the "Specifying command arguments" section, I suppose <app_name>/linux_x86_64/bin/java.path will contain the path to fizbin.jar, but what about the path to the java executable? What if we don't want to use the default /usr/bin/java?

In the "Using external programs to process command executables" section, the page omits a very important information: the contents of the python.path files. (Stating "Create a .path file" is misleading since it's a python.path file that is created) I suspect the content is /usr/bin/python in the 64-bit Linux case and $SPLUNK_HOME/bin/python for other platforms.

DUThibault
October 31, 2017

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