Configure endpoints, entities, and fields in setup.xml

A setup page uses the Splunk Enterprise REST API to manage the app's configuration. The setup page can configure Splunk Enterprise REST endpoints or custom endpoints that you create for your app.

In setup.xml, you specify the endpoints, entities, and fields to access 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 page.

See About configuration files in the Admin Manual to learn more about how to use configuration files to manage apps and Splunk Enterprise.

See the REST API Reference Manual to learn more about the REST API.

REST endpoints and configuration file settings

Splunk Enterprise uses REST endpoints to interact with other resources, both in memory and on disk. For setup pages, 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 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/app_name/saved/searches/MySearch

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 page, the user could specify a value, such as */5 * * * *.

Provide 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 page. In setup.xml, you can provide username and password fields to capture the user credentials.

For an example of how to provide fields for user credentials, see Setup page example with 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 because the script needs access to the decrypted password from Splunk.

For more information, see:

 

Use custom endpoints with a setup page

For more complex setups, you can write your own Python scripts.

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/your_app_name/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/app_name/bin/.
  4. Write setup.xml.

For a detailed example, see Setup page example using a custom endpoint.