Splunk® Enterprise

REST API Reference Manual

Download manual as PDF

Splunk Enterprise version 5.0 reached its End of Life on December 1, 2017. Please see the migration information.
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

Accessing and updating Splunk configurations

This section describes how to use the Splunk REST API to access and update information contained in Splunk configuration files (*.conf files). For more information on configuration files, see About Configuration Files and Configuration File Precedence in the Splunk Admin manual.

Splunk uses two sets of endpoints for access to configuration files:

properties/
configs/conf-{file}/

These endpoints essentially accomplish the same task for updating configurations, but their implementation differs. In most cases, you can use properties endpoints for updating configurations. However, there are times where you can only use the configs/conf-{file} endpoints. For example, use the configs/conf-{file} endpoints to do the following:

Setting permissions
Enabling or disabling a stanza in a configuration
Moving a resource

Reading configuration files

The way you read configurations files differs between properties/ and configs/conf-{file}/ endpoints.

GET operations for properties/ endpoints
GET operations for configs/conf-{file}/ endpoints

properties endpoints

The properties set of endpoints provide various options for listing configurations. GET operations are available to drill down from the list of configuration files to the key/value pairs.

GET properties
Returns the name of each Splunk configuration file.
GET properties/{file_name}
Returns the name of each stanza in {file_name}.conf.
GET properties/{file_name}/{stanza_name}
Returns the key/value pairs for the named stanza.
GET properties/{file_name}/{stanza_name}/{key_name}
Returns the value of the specified key.

For example, the following operation returns all the stanza names for props.conf:

curl -k -u admin:pass https://localhost:8089/servicesNS/nobody/search/properties/props


The response:

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest">
  <title>props</title>
  <id>https://localhost:8089/servicesNS/nobody/search/properties/props/</id>
  . . .
  <entry>
    <title>ActiveDirectory</title>
    <id>https://localhost:8089/servicesNS/nobody/search/properties/props/ActiveDirectory</id>
    <updated>2011-09-14T15:48:40-07:00</updated>
    <link href="/servicesNS/nobody/search/properties/props/ActiveDirectory" rel="alternate"/>
  </entry>
  <entry>
    <title>PerformanceMonitor</title>
    <id>https://localhost:8089/servicesNS/nobody/search/properties/props/PerformanceMonitor</id>
    <updated>2011-09-14T15:48:40-07:00</updated>
    <link href="/servicesNS/nobody/search/properties/props/PerformanceMonitor" rel="alternate"/>
  </entry>
  . . .
  <entry>
    <title>wmi</title>
    <id>https://localhost:8089/servicesNS/nobody/search/properties/props/wmi</id>
    <updated>2011-09-14T15:48:40-07:00</updated>
    <link href="/servicesNS/nobody/search/properties/props/wmi" rel="alternate"/>
  </entry>
  <entry>
    <title>wtmp</title>
    <id>https://localhost:8089/servicesNS/nobody/search/properties/props/wtmp</id>
    <updated>2011-09-14T15:48:40-07:00</updated>
    <link href="/servicesNS/nobody/search/properties/props/wtmp" rel="alternate"/>
  </entry>
</feed>


The following operation returns the key/value pairs for the webshpere_core stanza in props.conf.

curl -k -u admin:pass https://localhost:8089/servicesNS/nobody/search/properties/props/websphere_core


The response:

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest">
  <title>websphere_core</title>
  <id>https://localhost:8089/servicesNS/nobody/search/properties/props/websphere_core</id>
  . . .
  <entry>
    <title>ANNOTATE_PUNCT</title>
    <id>https://localhost:8089/servicesNS/nobody/search/properties/props/websphere_core/ANNOTATE_PUNCT</id>
    <updated>2011-09-14T15:55:01-07:00</updated>
    <link href="/servicesNS/nobody/search/properties/props/websphere_core/ANNOTATE_PUNCT" rel="alternate"/>
    <content type="text">True</content>
  </entry>
  <entry>
    <title>BREAK_ONLY_BEFORE</title>
    <id>https://localhost:8089/servicesNS/nobody/search/properties/props/websphere_core/BREAK_ONLY_BEFORE</id>
    <updated>2011-09-14T15:55:01-07:00</updated>
    <link href="/servicesNS/nobody/search/properties/props/websphere_core/BREAK_ONLY_BEFORE" rel="alternate"/>
    <content type="text">^NULL\s</content>
  </entry>
  . . .
  <entry>
    <title>maxDist</title>
    <id>https://localhost:8089/servicesNS/nobody/search/properties/props/websphere_core/maxDist</id>
    <updated>2011-09-14T15:55:01-07:00</updated>
    <link href="/servicesNS/nobody/search/properties/props/websphere_core/maxDist" rel="alternate"/>
    <content type="text">70</content>
  </entry>
</feed>


configs/conf-{file} endpoints

GET operations for these endpoints return entries for the stanzas in the named configuration file, detailing the contents of the stanza as key/value pairs.

For example, the following operation lists the props.conf configuration for the default search application.

curl -k -u admin:pass https://localhost:8089/servicesNS/nobody/search/configs/conf-props

The response, showing elided fragments of a few stanzas in props.conf.

<feed xmlns="http://www.w3.org/2005/Atom" 
  xmlns:s="http://dev.splunk.com/ns/rest" 
  xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>conf-props</title>
  <id>https://localhost:8089/servicesNS/nobody/search/configs/conf-props</id>
  <updated>2011-09-14T15:31:24-07:00</updated>
  . . .
  <entry>
    <title>access_combined</title>
    <id>https://localhost:8089/servicesNS/nobody/system/configs/conf-props/access_combined</id>
    . . .
    <content type="text/xml">
      <s:dict>
        <s:key name="ANNOTATE_PUNCT">1</s:key>
        <s:key name="BREAK_ONLY_BEFORE"></s:key>
        <s:key name="BREAK_ONLY_BEFORE_DATE">1</s:key>
        . . .
        <s:key name="maxDist">28</s:key>
        <s:key name="pulldown_type">1</s:key>
      </s:dict>
    </content>
  </entry>
  . . .
  <entry>
    <title>exchange</title>
    <id>https://localhost:8089/servicesNS/nobody/system/configs/conf-props/exchange</id>
    <updated>2011-09-14T15:31:24-07:00</updated>
   . . .
   <content type="text/xml">
      <s:dict>
        <s:key name="ANNOTATE_PUNCT">1</s:key>
        <s:key name="BREAK_ONLY_BEFORE"></s:key>
        <s:key name="BREAK_ONLY_BEFORE_DATE">1</s:key>
        . . .
        <s:key name="eai:appName">search</s:key>
        <s:key name="eai:userName">nobody</s:key>
        <s:key name="maxDist">100</s:key>
      </s:dict>
    </content>
  </entry>
</feed>


Updating Configuration Files

You update a configuration file by adding and/or editing stanzas to the file. How you do this differs between properties and configs/conf-{file} endpoints. Only perform DELETE operations from the configs/conf-{file} endpoints.

Note: The DELETE operation is available from the properties endpoint, but is deprecated. Instead, use the DELETE operations from configs/conf-{file} endpoints.

When you update a configuration, updates are always written to the local version of the file. The default version of configurations can be overwritten when you update Splunk to a new version.

properties

Use the POST operation with various properties endpoints to update configuration files.

The DELETE operation from the properties is deprecated and will be removed from future releases. Instead, use DELETE operations from the configs/conf-{file} endpoints.

configs/conf-{file}

Use the POST operation to add a stanza to the named configuration file. You can also specify key/value pairs for the newly added stanza. For example, the following operation creates a new stanza and key/value pairs in props.conf for the default search application.

curl -k -u admin:pass https://localhost:8089/servicesNS/nobody/search/configs/conf-props \
	-d name=myweblogs \
	-d CHARSET=UTF-8 \
	-d SHOULD_LINEMERGE=false


configs/conf-{file}/{name}

Use the POST operation to create or update key/value pairs in the stanza specified by {name}.

Use the DELETE operation to remove a stanza from a configuration file.

PREVIOUS
Accessing Splunk resources
  NEXT
Creating searches using the REST API

This documentation applies to the following versions of Splunk® Enterprise: 5.0, 5.0.1, 5.0.2, 5.0.3, 5.0.4, 5.0.5, 5.0.6, 5.0.7, 5.0.8, 5.0.9, 5.0.10, 5.0.11, 5.0.12, 5.0.13, 5.0.14, 5.0.15, 5.0.16, 5.0.17, 5.0.18


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