
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 emptycommands.conf
file in that directory. Do not copy thecommands.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
|
$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.
- Create a
.path
file, such as$SPLUNK_HOME/etc/apps/<app_name>/bin/java.path
. The.path
file must be stored in one of thebin
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 thefilename
and thecommand.arg.N
arguments. Absolute paths are not supported in thefilename
attribute. The following example shows the stanza for thefizbin
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.
- In this example, the Splunk software searches for the
- Any environment variables that are specified, such as
$JAVA_HOME
are substituted in the.path
file.
- Any environment variables that are specified, such as
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 thebin
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 thefilename
andcommand.arg.1
attributes. Absolute paths are not supported in thefilename
attribute. The following example shows the stanza for thefizbin
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.
- In this example, the Splunk software searches for the
- Any environment variables that are specified, such as
$PYTHON_PATH
are substituted in.path
file.
- Any environment variables that are specified, such as
See also
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.4.10, 6.4.11, 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.5.7, 6.5.8, 6.5.9, 6.5.10, 6.6.0, 6.6.1, 6.6.2, 6.6.3, 6.6.4, 6.6.5, 6.6.6, 6.6.7, 6.6.8, 6.6.9, 6.6.10, 6.6.11, 6.6.12, 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 8.0.0
Comments
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.
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.