Accessing and updating Splunk Enterprise configurations

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

If you have Splunk Cloud Platform, you cannot change the configuration files in your Splunk Cloud Platform deployment using text editors. Splunk Cloud Platform admins, however, can change configuration files by using the properties set of endpoints. You can also change configuration files in forwarders that you manage in your network.

Two sets of endpoints give access to configuration files.

properties/

configs/conf-{file}/

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

Setting permissions

Enabling or disabling a stanza in a configuration

Moving a resource

For reference information on these endpoints, see Configuration endpoint descriptions in the REST API Reference Manual.

Reading configuration files

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

properties endpoints

The properties set of endpoints give 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 names of configuration files.

GET properties/{file_name}

Returns the stanza names 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 key value.

For example, the search/properties/props GET 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 /search/properties/props/websphere_core GET operation returns the key/value pairs for the props.conf file websphere_core stanza.

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 /search/configs/conf-props GET 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 or editing stanzas to the file. How you do this differs between properties and configs/conf-{file} endpoints. Do DELETE operations from only the configs/conf-{file} endpoints.

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 written to the local version of the file. The default version of configurations can be overwritten when you update to a new Splunk version.

properties

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

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 /search/configs/conf-props POST 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 {name} stanza.

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