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.

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 .

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

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:

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.

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.

In the .path file, specify the path to the Java runtime environment (JRE). For example, /usr/bin/java.

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.

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.

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.

In the .path file, specify the path to the Python interpreter. For example, /usr/bin/python.

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.

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

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.

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

Send me a copy of this feedback

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

Feedback submitted, thanks!

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

Your Comment Has Been Posted Above

We use our own and third-party cookies to provide you with a great online experience. We also use these cookies to improve our products and services, support our marketing campaigns, and advertise to you on our website and other websites. Some cookies may continue to collect information after you have left our website.
Learn more (including how to update your settings) here »