Splunk® Enterprise

Admin Manual

Download manual as PDF

Splunk version 4.x reached its End of Life on October 1, 2013. Please see the migration information.
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

Configure scripted alerts

Configure scripted alerts with savedsearches.conf. Use the $SPLUNK_HOME/etc/system/README/savedsearches.conf.example as an example, or create your own savedsearches.conf. Edit this file in $SPLUNK_HOME/etc/system/local/, or your own custom application directory in $SPLUNK_HOME/etc/apps/. For more information on configuration files in general, see "About configuration files".

Script options

Your alert can trigger a shell script or batch file, which must be located in $SPLUNK_HOME/bin/scripts. Use the following attribute/value pairs:

action.script = <string>

Splunk currently enables you to pass arguments to scripts both as command line arguments and as environment variables. This is because command line arguments don't always work with certain interfaces, such as Windows.

The values available in the environment are as follows:

  • SPLUNK_ARG_0 Script name
  • SPLUNK_ARG_1 Number of events returned
  • SPLUNK_ARG_2 Search terms
  • SPLUNK_ARG_3 Fully qualified query string
  • SPLUNK_ARG_4 Name of saved search
  • SPLUNK_ARG_5 Trigger reason (for example, "The number of events was greater than 1")
  • SPLUNK_ARG_6 Browser URL to view the saved search
  • SPLUNK_ARG_8 File in which the results for this search are stored (contains raw results)

SPLUNK_ARG_7 is not used for historical reasons.

These can be referenced in UNIX shell as $SPLUNK_ARG_0 and so on, or in Microsoft batch files via %SPLUNK_ARG_0% and so on. In other languages (perl, python, and so on), use the language native methods to access the environment.

These values are also available as positional arguments passed on the command line of the script. You can use these as well if they are more convenient. Relatively old versions of Splunk do not provide the environment variables. However, due to platform reasons, they are not entirely reliable in Microsoft Windows.

The command line arguments that Splunk passes to the script are:

  • 0 = Script name
  • 1 = Number of events returned
  • 2 = Search terms
  • 3 = Fully qualified query string
  • 4 = Name of saved search
  • 5 = Trigger reason (i.e. "The number of events was greater than 1")
  • 6 = Browser URL to view the saved search
  • 7 = This option has been deprecated and is no longer used
  • 8 = File where the results for this search are stored (contains raw results)

Note: Splunk encourages Windows users to use the $SPLUNK_ARG_<number> environment variables when passing arguments to scripts.

If you want to run a script written in a different language (for example PERL, Python, VBScript) you must specify the interpreter you want Splunk to use in the first line of your script, following the #!. For example:

to run a PERL script:

---- myscript.pl ----
#!/path/to/perl
......
......

to use Python to interpret the script file:

---- myscript.py -----
#!/path/to/python
.....
.....

For an example of how to configure scripts to work with alerts, see send SNMP traps.

*nix Example

You can configure Splunk to send alerts to syslog. This is useful if you already have syslog set up to send alerts to other applications, and you want Splunk's alerts to be included.

Check the Splunk Wiki for information about the best practices for using UDP when configuring Syslog input.

Write a script that calls logger (or any other program that writes to syslog). Your script can call any number of the variables your alert returns.

Create the following script and make it executable:

logger $5

Put your script in $SPLUNK_HOME/bin/scripts.

Now create an alert that calls your script. See "Create an alert" in the User manual for help with alert creation through Splunk Web. You'll need to provide the script filepath.

Note: If you'd rather configure the alert in savedsearches.conf, see "Set up alerts in savedsearches.conf" in this chapter.

Edit your saved search to call the script. If your script is in $SPLUNK_HOME/bin/scripts you don't have to specify the full path.

30 admin7 syslog-logit.jpg

The logit script logs the trigger reason to syslog:

Aug 15 15:01:40 localhost logger: Saved Search [j_myadmin]: The number of events(65) was greater than 10

Windows Example

If you're running Windows, you can configure Splunk to send an alert to the Windows Event Log.

In this example, write a script that calls the EVENTCREATE utility (or any other command-line executable that can write to the Event Log). Your script can call any number of the variables your alert returns.

Create the following batch file:

@echo off
EVENTCREATE /T ERROR /SO Splunk /D %SPLUNK_ARG_5%

Note: You can use the type that best suits the message contained in the argument, ERROR is only used here as an example.

Put the batch file in %SPLUNK_HOME%/bin/scripts.

Now create an alert that calls your script. See "Create an alert" in the User manual for help with alert creation through Splunk Web. You'll need to provide the script filepath.

Note: If you'd rather configure the alert in savedsearches.conf, see "Set up alerts in savedsearches.conf" in this chapter.

Edit your saved search to call the script. If your script is in $SPLUNK_HOME/bin/scripts you don't have to specify the full path.

Troubleshoot

Check out this excellent topic on troubleshooting alert scripts on the Splunk Community Wiki.

PREVIOUS
Set up alerts in savedsearches.conf
  NEXT
Send SNMP traps to other systems

This documentation applies to the following versions of Splunk® Enterprise: 4.3, 4.3.1, 4.3.2, 4.3.3, 4.3.4, 4.3.5, 4.3.6, 4.3.7


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