• Overview
  • Overview
• User Interface
  • User Interface
    • Skinning SplunkWeb
  • Splunk toolbar for Firefox
  • Permalinks
    • Parameters
    • Unsupported Parameters
    • Examples
  • Configuring SplunkWeb
    • Skins
    • Localization
  • Scripting the Splunk search command
  • REST API
    • Messages
    • Authentication
    • Search
    • Enabling/disabling REST configuration options
    • Examples
  • SOAP API
    • How Splunk uses SOAP
    • Using the PCL to Make SOAP Requests
    • Additional PCL Search Examples
    • Creating SOAP Requests
    • SOAP Message Examples
    • SOAP error messages
• Data Inputs
  • Data Inputs
  • Input config
  • Scripted inputs
    • Configuration
    • Example
  • Understanding modules and processors
    • Default processors and pipelines
    • Pipeline data keys
    • Changing the default parsing and indexing sequence
    • Adding custom processors
  • Coding C/C++ processors
    • Writing Your Callback Function
    • Write Main
    • Add a Processor Config Stanza to Pipeline
  • Complete C Example
  • Complete C++ Example
  • Selecting events to process with a bundle
    • Create the Processor
    • Create the Module
    • Create the Bundle
    • Add an Additional Processor
• Data Outputs
  • Data Outputs
  • Customizing alert options
    • Email alerts
  • CLI for search
    • Actions
    • Default Argument
    • Parameters
    • Example
  • TCP Output
  • XML API for data output
• Management
  • Management
  • Authentication
    • Command Authentication
    • Parameters
    • Examples
    • Session Authentication
    • Examples
  • CLI for management
    • User Accounts
    • Controls
  • Configuring splunkd
    • Creating default logins on first startup
    • Changing the SSL configuration
  • XML API for management

Scripting the Splunk search command

You can create custom scripts to handle your Splunk search results and function as a new search command. To build a search script, put a Python script in $SPLUNK_HOME/etc/searchscripts. Python scripts in the searchscripts directory are available in the search language and can be used in a search.

Some things to know about passing results to and from a search command:

• Results are passed in with stdin and out with stdout.
• Arguments are passed from the search line directly to you.

If your Python script is called myNewCommand.py, it can be used in a search as follows:

access denied | myNewCommand

Please note:

• Only Python or Perl scripts are currently supported. If you use Perl, you must parse the search results on your own.
• If you make changes to your files, restart your Splunk Server to pick up the changes.
• The input to your Python script are all the events selected by the preceding search. By default, only the top 100 results are passed to the script to run. To override this value, append your search with a new value for maxinputs; for example, maxinputs=10000.
• Extracted fields are not available in the results array that is passed to the script. To expose extracted fields, first pipe the search into kv before piping to the custom search script.

The splunk.Intersplunk module directs events from Splunk to your Python search scripts.

• Calling getOrganizedResults will return a list of Python dictionaries, each of which represents a single event.
• Calling outputResults with a list of dictionaries will pass those events back to Splunk.

The output of your script can then be fed back into Splunk as events. In the simplest case, your script does nothing and just returns what it received. To accomplish this, you would write the following script:

import sys,splunk.Intersplunk

# this call populates the results variable with all the events passed into the search script:
results,dummyresults,settings = splunk.Intersplunk.getOrganizedResults()

# hand the results right back to Splunk
splunk.Intersplunk.outputResults(results)

Although this code snippet does not do much, it shows you how you get the events and how you pass the data back to Splunk. If you want to change some of the events, you would add a loop to iterate over all the events. Each event is comprised of a set of key-value pairs for every extracted field.

import sys,splunk.Intersplunk

# this call populates the results variable with all the events passed into the search script:
results,dummyresults,settings = splunk.Intersplunk.getOrganizedResults()

# Iterate over all the events:
for result in results:
  # for all the events, you want to iterate over all the extracted fields:
  for key,value in result.items():
    # change the result items. This example makes all the values lowercase.
    value = value.lowercase()
    # add the changed values to a new array that is later passed back to Splunk.
    newresults.append( {key:value} )

# hand the results right back to Splunk
splunk.Intersplunk.outputResults(newresults)

The above is probably the most common use-case for what you are trying to do; changing events with your own command. You do not necessarily have to return the entire original set of events. You can return any key-value pairs back to Splunk. The following is absolutely legitimate:

# This prepares the return value for the script
newresults = [ { "afterglowFilename" : "afterglow.html" } ]

splunk.Intersplunk.outputResults(newresults)

This example returns only one key/value pair. This could then be combined with a field action to execute some action on this field, for example displaying the html file indicated in the value part.