Setup.xml syntax

The setup.xml file, which should be located in $SPLUNK_HOME/etc/your_app_name/default/, defines the setup page that prompts users for configuration settings.

<setup>

The base element of a setup page, which 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 page. 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 Enterprise uses its REST API to access specified endpoints. Each endpoint is relative to:

https://hostname:port/servicesNS/nobody/app_name

For example, the endpoint: saved/searches corresponds to this REST endpoint, which you can access in a web browser:

https://localhost:8089/servicesNS/nobody/app_name/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 page.

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 page, 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. 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. "*" is interpreted 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 page.

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.