Splunk® Enterprise

Alerting Manual

Download manual as PDF

Download topic as PDF

Configure a script for an alert action

The run a script alert action is officially deprecated. It has been replaced with custom alert actions as a more scalable and robust framework for integrating custom actions. See About custom alert actions for information on building customized alert actions that can include scripts.

If you have Splunk Enterprise, you can configure an alert to run a shell script or batch file when the alert triggers. This topic shows how to access information about an alert in a script that runs as an alert action.

The script or batch file that an alert triggers must be at either of the following locations:

$SPLUNK_HOME/bin/scripts
$SPLUNK_HOME/etc/apps/<AppName>/bin/scripts

Working directories for scripts

Specify an absolute path whenever a path is needed. If you use relative paths, it is important to remember that they are rooted in the Search and Reporting app's bin folder.

Access arguments to scripts that are run as an alert action

When you run a script as an alert action, positional arguments that capture alert information are passed to the script. The positional arguments are also available as environment variables.

You can access information from each argument using the notation in the following table.

Arg Environment Variable Value
0 SPLUNK_ARG_0 Script name
1 SPLUNK_ARG_1 Number of events returned
2 SPLUNK_ARG_2 Search terms
3 SPLUNK_ARG_3 Fully qualified query string
4 SPLUNK_ARG_4 Name of report
5 SPLUNK_ARG_5 Trigger reason

For example, "The number of events was greater than 1."

6 SPLUNK_ARG_6 Browser URL to view the report.
7 SPLUNK_ARG_7 Not used for historical reasons.
8 SPLUNK_ARG_8 File in which the results for the search are stored.

Contains raw results in gzip file format.

You can reference the information captured by these arguments in UNIX shell scripts or Microsoft batch files, as shown below. In other languages, such as perl and python, use the methods native to the language to access script arguments.

# UNIX scripts can access environment variables and positional args
$SPLUNK_ARG_0
$0

# Microsoft batch files capture environment variables reliably
%SPLUNK_ARG_0%

Test script that accesses positional arguments

Use the following test script to see the results of accessing the positional arguments.

To use this test script, create an alert that runs the script as an alert action. Then check the contents of the generated echo_output.txt file:

# $SPLUNK_HOME/bin/scripts/echo.sh
# simple script that writes parameters 0-7 to 
# $SPLUNK_HOME/bin/scripts/echo_output.txt 
# $SPLUNK_ARG_0 and $0 show how to use the long and short form. 

read sessionKey
echo "'$SPLUNK_ARG_0' '$0' '$1' '$2' '$3' '$4' '$5' '$6' '$7' '$8' '$sessionKey'" >> \
"$SPLUNK_HOME/bin/scripts/echo_output.txt" 
  • Note: The sessionKey is URL encoded.


Script example: Write to syslog

You can configure a script for an alert to write to the system log daemon. This is useful if you have syslog set up to send alerts to other applications and you want to include alerts from your Splunk deployment.

  1. Create a script, logIt that calls logger, or any other program that writes to syslog.
    Place the script in $SPLUNK_HOME/bin/scripts.
  2. Add the following in logIt:
    logger $5

    The script can access any of the arguments available when called as an alert action.

  3. Create an alert on a report that runs logIt as an alert action.
    When the alert triggers, the log entry looks something like this:
    Aug 15 15:01:40 localhost logger: Report [j_myadmin]: The number of events(65) was greater than 10

See Best practices for using UDP when configuring a syslog input, a topic in the Splunk Community Wiki.

Script example: Write to the Windows Event Log

For Windows platforms, you can configure an alert action to run a script that writes to the Windows Event Log.

The following example shows a script that calls the EVENTCREATE utility that writes to the Event log. The script can access any of the environment variables available with an alert. You can substitute the EVENTCREATE utility with any command-line executable that writes to the Event Log.

  1. Create the following batch file, logIt.bat.
    Place the script in $SPLUNK_HOME/bin/scripts.
  2. Include the following command in the batch file:
    @echo off
    EVENTCREATE /T ERROR /SO Splunk /D %SPLUNK_ARG_5%
    Use the type that best suits the message contained in the argument. This example uses ERROR.

  3. Create an alert to a report that runs logIt.bat as an alert action.
PREVIOUS
Configure alerts in savedsearches.conf
 

This documentation applies to the following versions of Splunk® Enterprise: 6.3.0, 6.3.1, 6.3.2, 6.3.3, 6.3.4, 6.3.5, 6.3.6, 6.3.7, 6.3.8, 6.3.9, 6.3.10, 6.3.11, 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.5.0, 6.5.1, 6.5.1612 (Splunk Cloud only), 6.5.2, 6.5.3, 6.5.4, 6.6.0, 6.6.1


Comments

Hi @Madrum,

Thanks for your question and comment. I wanted to suggest the troubleshooting steps mentioned in this Answers post (you can ignore the fact that the question references Windows XP, as the troubleshooting steps in the answer are not dependent on this version):

https://answers.splunk.com/answers/6274/issues-triggering-alert-scripts-on-windows-xp.html

Try out the tests suggested here, and then I would suggest contacting Support if everything seems ok but the script is still not running:

https://www.splunk.com/content/splunkcom/en_us/about-us/contact.html#tabs/customer-support

Frobinson splunk, Splunker
May 10, 2017

I'm not able to get a script like "logit.bat" to run on a Windows machine. Any idea how to troubleshoot? I'm using Splunk Enterprise 6.5.3.

Madrum
May 10, 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