Splunk® Enterprise

Developing Views and Apps for Splunk Web

Acrobat logo Download manual as PDF


Splunk Enterprise version 7.1 is no longer supported as of October 31, 2020. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.
Acrobat logo Download topic as PDF

Set up custom alert configuration files

Learn how to define custom alert action app settings in configuration files.

Custom alert action app configuration files

Here are all of the configuration files that you can use to manage a custom alert action app. Some files are required to make the app work and others are optional.

File Description Required?
alert_actions.conf Contains settings for the custom alert action. Yes
app.conf Package and UI information about the app. Yes
savedsearches.conf Define instance settings for saved search actions. A local copy is required on the Splunk platform instance but not in the custom alert action app directory.
restmap.conf Define attribute/value pairs for REST endpoints and provide validation rules. Optional
setup.xml Configure startup values for the app. Optional
alert_actions.conf.spec Describes attributes and possible values for configuring global saved search actions in alert_actions.conf. Optional
savedsearches.conf.spec Describes attributes and possible values for saved search entries in savedsearches.conf. Optional
default.meta Defines alert action permission and scope. Optional

Set up required configurations

Only users with file system access, such as system administrators, can edit configuration files. If you are using Splunk Cloud and want to edit a configuration file, open a Support ticket.

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. Make the changes in the local directory.

Review the steps in How to edit a configuration file in the Admin Manual.

alert_actions.conf

Create a stanza in alert_actions.conf to configure the custom alert action.

Stanza naming
Follow these guidelines when naming the alert action stanza.

  • The stanza name must be unique. Two apps cannot define the same alert action.
  • The stanza name can contain only the following characters.
    • alphanumeric characters
    • underscores
    • hyphens
  • The stanza name cannot contain spaces.

Typically, developers name stanzas using lower case letters separated by underscores as needed. Once you have a stanza name, match the name of the script or executable file for the custom alert action to the stanza name.


Alert action attributes
The following attributes can be set in the alert action stanza within alert_actions.conf.

Attribute Type Default Description
is_custom boolean 0 Indicates if the app implements a custom alert action. Custom alert action developers should set this value to 1.
label text N/A Display name of the alert action in the Splunk Enterprise UI.
icon_path relative file path to the custom alert action icon. The icon appears in the Splunk Web user interface. To enable the custom alert action icon, indicate the relative path to the icon image file from

$SPLUNK_HOME$/etc/[app]/appserver/static/.

The best practice is to use a 48 x 48 px PNG file. The icon displays at 24 x 24 pixels.

The custom alert action icon is not the same as the app icon that appears on Splunkbase. To use the Splunkbase app icon for the custom alert action icon in Splunk Web, specify appIcon.png as the icon_path value.

alert.execute.cmd text Provide the name/path of the script or binary to invoke, especially to avoid conflicts for modular inputs and custom alert actions with the same name or scheme. If specifying a binary outside of the [app]/bin search path, use a *.path file, where the content of the file is the absolute path of the binary. Environment variables are replaced when reading path files.
alert.execute.cmd.arg.<n> text Change the command line arguments passed to the script when it is invoked.
payload_format (xml | json) xml Indicates format for payload sent to STDIN of the user-provided script.
disabled boolean 0 Indicates whether the alert action is disabled. Set to "1" to disable the alert action.
param.[param_name] Custom alert action parameter that is passed to the script as part of the payload. All parameters in the alert action stanza are treated as custom settings for the custom alert action. They are all passed to the alert script as part of the XML or JSON configuration payload.


These additional settings from alert_actions.conf are also honored. For more details, see alert_actions.conf.

Attribute Type Default Description
command search string to invoke 
sendalert $action_name$ results_file="$results.file$" results_link="$results.url$"
Partial search string executed by the scheduler when the alert is triggered. Developers can override default behavior to invoke a different custom search command or to pre-process the data before piping to sendalert.
hostname Custom hostname.
maxtime
maxresults
ttl 		Limit the number of results for an action and the time a triggered alert takes to execute an action.


Example
The following example shows a stanza in the alert_actions.conf for a custom alert action.

$SPLUNK_HOME$/etc/apps/[name]/default/alert_actions.conf 

[logger]
is_custom = 1
label = My Alert Action 
icon_path = myicon.png 
payload_format = json
disabled = 0
# Custom params
param.foo = bar
param.param1 = I can use a token: $result.host$

savedsearches.conf

A local copy of savedsearches.conf captures alert action user configurations for a particular Splunk instance.

For each Splunk platform instance, savedsearches.conf user settings override any global alert_actions.conf alert action settings.

Example
In this example, the alert_actions.conf file for a custom alert action defines a global parameter and setting for the alert action.

alert_actions.conf 

[my_custom_alert]
param.email_option = 0

In a Splunk platform instance, the following setting for the same parameter in the local savedsearches.conf file overrides the global setting from the app.

savedsearches.conf 

action.my_custom_alert.param.email_option= 1

How configurations propagate to the alert action

When the custom alert action script runs, it reads in payload information about the system and the alert. The payload includes alert action configurations merged from alert_actions.conf and savedsearches.conf.

The following example payload includes a <configuration> element with parameters and settings from the two files. 

<alert>
    <server_host>localhost:8089</server_host>
    <server_uri>https://localhost:8089</server_uri>
    <session_key>1234512345</session_key>
    <results_file>
      /opt/splunk/var/run/splunk/12938718293123.121/results.csv.gz
    </results_file>
    <results_link>
       http://splunk.server.local:8000/en-US/app/search?sid=12341234.123
    </results_link>
    <sid>12341234.123</sid>
    <search_name>My Saved Search</search_name>
    <owner>admin</owner>
    <app>search</app>
    <configuration>
        <stanza name="[my_custom_alert]">
            <param name="[param_name_1]">[some value]</param>
            <param name="[param_name_2]">[other value]</param>
        </stanza>
    </configuration>
</alert>
  • Note: For searches generated using the advanced search option, results_file and results_link parameters are not included in the payload passed to the custom alert action script.

Optional configurations

For information on optional configuration files, see Optional custom alert action components.

Last modified on 01 October, 2018
PREVIOUS
Custom alert action component reference 		  NEXT
Create a custom alert action script

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.3.12, 6.3.13, 6.3.14, 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.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.1.10

Was this documentation topic helpful?

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