Developing Dashboards, Views, and Apps for Splunk Web

 


Step 7: Configure a setup screen

NOTE - 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.

Step 7: Configure a setup screen

You can make life easier for your users by creating a setup screen for your app or add-on. Setup screens make it easier to distribute apps to different environments, or to customize an app for a particular usage. When the user first runs the app, the setup screen displays that allows the user to specify configurations for the app without having to edit the configuration files directly. The user can later run the setup screen from Splunk > Manager > Apps > Actions.

A setup screen uses the Splunk REST API to manage the app’s configuration. For example, you can use the setup screen to enable or disable a scripted input or set the frequency and alerting for a saved search. The setup screen can configure REST endpoints available from the Splunk API or custom endpoints that you create for your app.

Sample Setup Screen

This topic walks you through creating a setup screen. You can jump ahead to view the following examples:

Create a setup screen

To create a setup screen:

  1. Create a setup.xml file in your app's default directory: $SPLUNK_HOME/etc/apps/<AppName>/default/setup.xml.
  2. Supply initial values for the fields in your app's configuration files. The setup screen uses these values to populate the input fields in the setup screen.

See setup.xml syntax below for information on creating setup.xml.

View the setup.xml spec file.

Endpoints, entities, and fields

Splunk uses its REST API to update configurations specified in a setup screen. In setup.xml, you specify the endpoints, entities, and fields which Splunk accesses when updating a configuration.

Here are summary descriptions of endpoint, entities and fields to help you understand how they are used in setup.xml:

endpoint Directly or indirectly indicates which configuration file to update. Most of the configuration files within Splunk have one or more corresponding endpoints. For example, inputs.conf has a number of corresponding endpoints, including data/inputs/monitor (for monitored files) and data/inputs/script (for scripted inputs).

Navigate to the following location to see the endpoints available to all apps in your Splunk installation.

https://localhost:8089/servicesNS/nobody/
entity The object ID listed by the endpoint. Typically maps to a stanza in a configuration file.

Use URI encoding to specify paths to entities.

field Maps to an attribute of an entity. Typically, this is a setting in the stanza of a configuration files. The user specifies values for the attribute in the setup screen.

See About configuration files to learn more about how Splunk uses configuration files to manage apps and Splunk.

See Splunk's API is RESTful to learn more about Splunk's REST API.

REST endpoints and configuration file settings

Splunk uses REST endpoints to interact with other Splunk resources, both in memory and on disk. For setup screens, you typically access configuration files to allow a user to easily configure an app for their specific circumstances without having to manually update the configuration files.

The name of Splunk REST endpoint parameters usually, but not always, map directly to the name of the setting in a configuration file. For example, the following stanza in savedsearches.conf enables a scheduled search:

[MySearch]
search = sourcetype=access_combined ( 404 OR 500 OR 503 ) 
dispatch.earliest_time = -1d
cron_schedule = */5 * * * *
enableSched = 1

You can view the corresponding REST endpoints here:

https://localhost:8089/servicesNS/nobody/<AppName>/saved/searches/WebSearch

At this REST endpoint, the names search, dispatch.earliest_time, and cron_schedule match the names of the attributes in savedsearches.conf. But the REST endpoint parameter for enableSched is is_scheduled. In the setup.xml, you reference is_scheduled to modify the setting for enableSched.

Example settings for endpoint, entity, and field

For example, in setup.xml for an app called sampleApp:

  • endpoint saved/searches
Maps to the configuration file savedsearches.conf. You can view the REST destination from a web browser at:
https://localhost:8089/servicesNS/nobody/sampleApp/saved/searches)
  • entity sample_scheduled_search
In savedsearches.conf, refers to the stanza, [sample_scheduled_search].
  • field cron_schedule
Maps to the setting in [sample_scheduled_search] to update. In the setup screen, the user could specify a value, such as */5 * * * *.


Providing credentials to access scripts

If your app contains scripted inputs that require a user name and password, you can capture the credentials for the script in your setup screen. In setup.xml, you can provide username and password fields to capture the user credentials.

See Setup screen example with user credentials for an example on how to provide fields for user credentials.

The password field masks input with a ‘*’ character. Splunk encrypts the credentials and stores them in a stanza in the app’s app.conf configuration file. app.conf is at:

$SPLUNK_HOME/etc/apps/local/app.conf

Here is the stanza, which is generated by splunkd, that contains the encrypted credentials. <realm> is optional:

[credential:<realm>:<username>]
password = $1$<encrypted-password>
Caution: security implications
Splunk stores the encrypted password and encryption key on the same machine. This is because the script needs access to the decrypted password from Splunk.

For more information see:


Running the setup screen

If your app contains a setup.xml file, when the user first runs the app the setup screen opens, displaying default configuration values for items listed on the setup screen. The user can choose to accept the default configuration, or specify new values.

The user can later run the setup screen from the Splunk Manager > Apps > Actions. Click on the Set up link for your app to open the setup screen.

Note: The setup screen writes changes made to the app’s configuration to the $SPLUNK_HOME/etc/apps/<app>/local directory. The local directory overrides any settings in the app’s default directory.

Creating setup screens for custom endpoints

For more complex setups, you can write your own Python scripts. For example, the setup screen for the WebSphere® app (available from Splunkbase) takes a single user input, the path to profileRegistry.xml for a WebSphere Application Server instance. From this registry file, the app extracts the locations of the WAS log files and configures inputs.conf to monitor all of them.

To use a custom endpoint in your setup:

  1. Create your custom configuration file with the initial values for the fields in the stanzas. (Alternately, you could initialize the values for the fields in a python script.)
  2. Create a stanza in $SPLUNK_HOME/etc/apps/<AppName>/default/restmap.conf that maps your endpoint to your custom configuration file.
  3. Write a python script for your endpoint and place it in: $SPLUNK_HOME/etc/<AppName>/bin/
  4. Write setup.xml.

See Setup screen example using a custom endpoint for a detailed example.


setup.xml syntax

setup.xml defines the setup screen that prompts users for configuration settings. You place setup.xml in your app’s default directory:

$SPLUNK_HOME/etc/<AppName>/default/setup.xml


<setup>

The base element of a setup screen. It contains any number of block elements. Block elements cannot be nested inside other block elements.

<block>

The block element defines the UI for the setup screen. A block element can contain one or more of the following:

  • text element
  • input element

A block element can declare the following attributes:

<block> attributes

attribute description
title (Required) Displays a header for the block.
endpoint (optional) Specifies a Splunk REST endpoint for your app. The endpoint attribute is inherited by all input child elements. Splunk uses its REST API to access specified endpoints. Each endpoint is relative to:
https://hostname:port/servicesNS/nobody/<AppName>
For example, the endpoint: saved/searches corresponds to this REST endpoint, which you can access in a web browser:
https://localhost:8089/servicesNS/nobody/<appName>/saved/searches
This endpoint maps to the savedsearches.conf configuration file.
entity (optional) Specifies the object at the endpoint to modify. Typically, entity maps to a stanza in a configuration file.

This attribute can only be set for a block that specifies an endpoint. The entity attribute is inherited by all input child elements.

entity= "_new" creates a new entity. Typically, this results in a new stanza in the configuration file pointed to by the REST endpoint.

mode (optional) Sets how to process an entity attribute when you define the entity with a regex, such as *. All entities matching the regex are configured. Note: Splunk interprets '*' as '.*'.

The value of mode can be either iter or bulk.

iter: Iterates through all matching entities at that endpoint, displaying separate inputs for each matching entity. Allows the user to specify different values for each entity. For example, the user can set the polling interval separately for a number of scripted inputs.

bulk: Displays a single input for all matching entities. For example, lets the user set a single polling interval for a number of scripted inputs. When using bulk, all values for the matching entities should have the same type, such as string or number.

<text>

An optional element that provides descriptive text for the setup screen.

The text element can only be used inside block elements.


<input>

The input element collects input from the user. It associates the input with the specified field. The type element within an input element defines the user interface control to display.

When the user clicks Save on the setup screen, Splunk uses the POST method to update the fields for the specified endpoint/entity pair.

The input element can contains the following child elements:

  • <label> (required)
  • <type> (required)


<input> attributes

attribute description
endpoint (required) Specifies the REST endpoint that Splunk uses. See the description of endpoint for the <block> element.

Each input element has one (and only one) endpoint. The endpoint can be inherited from a parent block.

entity (required) Specifies the object at the endpoint to modify. Typically, entity maps to a stanza in a configuration file.

The entity can be inherited from a parent block.

entity="_new" creates a new entity. Typically, this results in a new stanza in the configuration file pointed to by the REST endpoint.

field Specifies the setting to be configured in the stanza specified by entity.

When used with entity= "_new" creates a new setting in the new stanza.

mode (optional) Sets how to process an entity attribute when you define the entity with a regex, such as *. All entities matching the regex are configured. Note: Splunk interprets '*' as '.*'.

The value of mode can be either iter or bulk.

iter: Iterates through all matching entities at that endpoint, displaying separate inputs for each matching entity. Allows the user to specify different values for each entity. For example, the user can set the polling interval separately for a number of scripted inputs.

bulk: Displays a single input for all matching entities. For example, lets the user set a single polling interval for a number of scripted inputs.


<label>

Required element in an <input> element. The description of the input field which is displayed on the setup screen.

Specify $name$ to display the name of the entity. Specify $field_name$ to specify the value of a specified field.

For example, if iterating through a list of entities (mode = "iter"), use $name$ to display the name of each entity to the user. Use $search$ to display the value of the search field defined in each entity.

<type>

Required element in an <input> element. Specifies the UI control for capturing user input.

Allowed values for the type element:

  • bool: Displays a checkbox that allows the user to choose true or false values.
  • text: Displays a text field to input string values.
  • password: Creates a password text field that masks passwords with the ‘*’ character. The UI displays a second password text field to ensure that the user types the same password twice.
  • list: Displays values from a comma separated list, allowing the user to select a single value.

This documentation applies to the following versions of Splunk: 4.3 , 4.3.1 , 4.3.2 , 4.3.3 , 4.3.4 , 4.3.5 , 4.3.6 , 4.3.7 View the Article History for its revisions.


You must be logged into splunk.com in order to post comments. Log in now.

Was this documentation topic helpful?

If you'd like to hear back from us, please provide your email address:

We'd love to hear what you think about this topic or the documentation as a whole. Feedback you enter here will be delivered to the documentation team.

Feedback submitted, thanks!