Documentation > Splunk > REST API Reference > System

REST API Reference

 


REST API reference
Using Splunk's REST API

System

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.

Contents

System

Use the System endpoints to manage Splunk server configurations.

messages/*
server/*
Manage the settings of a Splunk server, including messages generated by the server.

messages

Provides access to Splunk system messages. Most messages are created by splunkd to inform the user of system problems.

Splunk Web typically displays these as bulletin board messages.

GET messages

Enumerate all systemwide messages. This is typically used for splunkd to advertise issues such as license quotas, license expirations, misconfigured indexes, and disk space.

Request

Name Type Required Default Description
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view messages.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
restart_required Splunk system message indicating that restarting Splunk is required.

Example

This example lists all system messages. 


curl -k -u admin:pass https://localhost:8089/services/messages



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>messages</title>
  <id>https://localhost:8089/services/messages</id>
  <updated>2011-07-08T01:14:21-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/messages/_new" rel="create"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>restart_required</title>
    <id>https://localhost:8089/services/messages/restart_required</id>
    <updated>2011-07-08T01:14:21-07:00</updated>
    <link href="/services/messages/restart_required" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/messages/restart_required" rel="list"/>
    <link href="/services/messages/restart_required" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="restart_required">Splunk must be restarted for changes to take effect.</s:key>
      </s:dict>
    </content>
  </entry>
</feed>




POST messages

Create a persistent message displayed at /services/messages.

Request

Name Type Required Default Description
name String
✓
 The primary key of this message.
value String
✓
 The text of the message.

Response Codes

Status Code Description
201 Created successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
402 The Splunk license in use has disabled this feature.
403 Insufficient permissions to create message.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.
503 This feature has been disabled in Splunk configuration files.

Returned Values

No values returned for this request.

Example

This example creates the Splunk system message, "hello world." 


curl -k -u admin:pass https://localhost:8089/services/messages \
	-d name=message \
	-d value="hello world"



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>messages</title>
  <id>https://localhost:8089/services/messages</id>
  <updated>2011-07-08T01:14:21-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/messages/_new" rel="create"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
</feed>




messages/{name}

DELETE messages/{name}

Deletes a message identified by {name}.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Deleted successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to delete message.
404 Message does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

No values returned for this request.

Example

This example deletes the message named message.

After invoking this operation, the message no longer displays on Splunk Web. 


curl -k -u admin:pass --request DELETE https://localhost:8089/services/messages/message



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>messages</title>
  <id>https://localhost:8089/services/messages</id>
  <updated>2011-07-08T01:14:21-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/messages/_new" rel="create"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
</feed>

GET messages/{name}

Get the entry corresponding to a single message identified by {name}.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view message.
404 Message does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
eai:attributes See Accessing Splunk resources
message The system message.

Example

This example lists the message named "message." 


curl -k -u admin:pass https://localhost:8089/services/messages/message



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>messages</title>
  <id>https://localhost:8089/services/messages</id>
  <updated>2011-07-08T01:14:21-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/messages/_new" rel="create"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>message</title>
    <id>https://localhost:8089/services/messages/message</id>
    <updated>2011-07-08T01:14:21-07:00</updated>
    <link href="/services/messages/message" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/messages/message" rel="list"/>
    <link href="/services/messages/message" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="eai:attributes">
          <s:dict>
            <s:key name="optionalFields">
              <s:list/>
            </s:key>
            <s:key name="requiredFields">
              <s:list/>
            </s:key>
            <s:key name="wildcardFields">
              <s:list/>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="message">hello world</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

server/control

Allows access to controls, such as restarting server.

GET server/control

Lists the actions that can be performed at this endpoint.

Request

Name Type Required Default Description
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view server controls.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

No values returned for this request.

Example

Displays actions available at server control endpoint. 


curl -k -u admin:pass https://localhost:8089/services/server/control



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>server-control</title>
  <id>https://localhost:8089/services/server/control</id>
  <updated>2011-07-12T00:17:53-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/server/control/restart" rel="restart"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
</feed>

server/control/restart

Allows for restarting Splunk.

POST server/control/restart

Restarts the Splunk server.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Restart requested successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
402 The Splunk license in use has disabled this feature.
403 Insufficient permissions to restart Splunk.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.
503 This feature has been disabled in Splunk configuration files.

Returned Values

No values returned for this request.

Example

Requests the Splunk process to restart. 


curl -k -u admin:pass https://localhost:8089/services/server/control/restart -X POST



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>server-control</title>
  <id>https://localhost:8089/services/server/control</id>
  <updated>2011-07-12T00:18:08-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/server/control/restart" rel="restart"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
</feed>


server/info

Provides access to configuration information about the server.

GET server/info

Enumerates the following information about the running splunkd: 

 build
 cpu_arch (CPU architecure)
 guid (GUID for this splunk instance)
 isFree
 isTrial
 licenseKeys (hashes)
 licenseSignature
 licenseState
 license_labels
 master_guid (GUID of the license master)
 mode
 os_build
 os_name
 os_version
 rtsearch_enabled
 serverName
 version

Request

Name Type Required Default Description
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view server configuration info.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
build The build number for this version of Splunk.
cpu_arch The architecture type for the CPU hosting splunkd.
eai:acl See Access control lists for Splunk objects
guid Globally unique identifier for this server.
isFree Indicates if this server is running Splunk under a free license.
isTrial Indicates if this server is using a trial license.
licenseKeys License key unique for each license.
licenseSignature Hash signature for the license for this server.
licenseState Specifies the status of the license, which can be either OK or Expired.
license_labels Labels associated with the license for this server.
master_guid Globally unique identifier for this server.
mode Indicates whether the server is a dedicated forwarder. Possible values are:
normal
dedicated forwarder
os_build Version information for the operating system running splunkd.
os_name Operating system for this server.
os_version Operating system version for this server.
rtsearch_enabled Indicates if real-time search is enabled for this server.
serverName Fully qualified name for the running version of splunkd.
version The version of Splunk running on this server.

Example

Lists information about the Splunk server. 


curl -k -u admin:pass https://localhost:8089/services/server/info



<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>server-info</title>
  <id>https://localhost:8089/services/server/info</id>
  <updated>2012-01-17T08:33:04-08:00</updated>
  <generator version="114250"/>
  <author>
    <name>Splunk</name>
  </author>
  <opensearch:totalResults>1</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>server-info</title>
    <id>https://localhost:8089/services/server/info/server-info</id>
    <updated>2012-01-17T08:33:04-08:00</updated>
    <link href="/services/server/info/server-info" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/info/server-info" rel="list"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="build">114250</s:key>
        <s:key name="cpu_arch">i386</s:key>
        <s:key name="eai:acl">. . .</s:key>
        <s:key name="guid">3C2EDE80-1A6E-4578-A427-327256E4DBA7</s:key>
        <s:key name="isFree">0</s:key>
        <s:key name="isTrial">0</s:key>
        <s:key name="licenseKeys"><s:list><s:item>89672015C88809FD401CB9DFCA4710C439BE718B0140876E2239CB9D0E46DB78</s:item></s:list></s:key>
        <s:key name="licenseSignature">9348ee9808623d14c0202cdd8ebf225a</s:key>
        <s:key name="licenseState">OK</s:key>
        <s:key name="license_labels"><s:list><s:item>Splunk 4.3 Beta</s:item></s:list></s:key>
        <s:key name="master_guid">3C2EDE80-1A6E-4578-A427-327256E4DBA7</s:key>
        <s:key name="mode">normal</s:key>
        <s:key name="os_build">Darwin Kernel Version 10.8.0: Tue Jun  7 16:33:36 PDT 2011; root:xnu-1504.15.3~1/RELEASE_I386</s:key>
        <s:key name="os_name">Darwin</s:key>
        <s:key name="os_version">10.8.0</s:key>
        <s:key name="rtsearch_enabled">1</s:key>
        <s:key name="serverName">vgenovese-mbp15.splunk.com</s:key>
        <s:key name="version">4.3</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

server/info/{name}

GET server/info/{name}

Provides the identical information as /services/server/info. The only valid {name} here is server-info.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view server configuration info.
404 Server configuration info does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

No values returned for this request.

Example

Retrieves the "server-info" node, which is the only valid value for {name}. 


curl -k -u admin:pass https://localhost:8089/services/server/info/server-info


See the response for services/server/info endpoint.


server/logger

Provides access to splunkd logging categories, either specified in code or in $SPLUNK_HOME/etc/log.cfg.

GET server/logger

Enumerates all splunkd logging categories, either specified in code or in $SPLUNK_HOME/etc/log.cfg.

Request

Name Type Required Default Description
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view logger info.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
eai:acl See Access control lists for Splunk objects
level Logger level for this server.

Valid values: (FATAL | CRIT | WARN | INFO | DEBUG)

Beginning with Splunk 4.3.4, Splunk does not support the CRIT logger level.

Example

This example lists all logging categories for the Splunk server. 


curl -k -u admin:pass https://localhost:8089/services/server/logger



<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>logger</title>
  <id>https://mrt:8089/services/server/logger</id>
  <updated>2011-05-16T20:29:38-0700</updated>
  <generator version="98144"/>
  <author>
    <name>Splunk</name>
  </author>
  <opensearch:totalResults>418</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>AdminHandler:AuthenticationHandler</title>
    <id>https://mrt:8089/services/server/logger/AdminHandler%3AAuthenticationHandler</id>
    <updated>2011-05-16T20:29:38-0700</updated>
    <link href="/services/server/logger/AdminHandler%3AAuthenticationHandler" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/logger/AdminHandler%3AAuthenticationHandler" rel="list"/>
    <link href="/services/server/logger/AdminHandler%3AAuthenticationHandler" rel="edit"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="eai:acl">. . .</s:key>
        <s:key name="level">WARN</s:key>
      </s:dict>
    </content>
  </entry>
  . . .
  <entry>
    <title>Application</title>
    <id>https://mrt:8089/services/server/logger/Application</id>
    <updated>2011-05-16T20:29:38-0700</updated>
    <link href="/services/server/logger/Application" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/logger/Application" rel="list"/>
    <link href="/services/server/logger/Application" rel="edit"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="eai:acl">. . .</s:key>
        <s:key name="level">WARN</s:key>
      </s:dict>
    </content>
  </entry>
  <entry>
    <title>ApplicationManager</title>
    <id>https://mrt:8089/services/server/logger/ApplicationManager</id>
    <updated>2011-05-16T20:29:38-0700</updated>
    <link href="/services/server/logger/ApplicationManager" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/logger/ApplicationManager" rel="list"/>
    <link href="/services/server/logger/ApplicationManager" rel="edit"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="eai:acl">. . .</s:key>
        <s:key name="level">WARN</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

server/logger/{name}

GET server/logger/{name}

Describes a specific splunkd logging category.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view logger info.
404 Logger info does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
eai:acl See Access control lists for Splunk objects
eai:attributes See Accessing Splunk resources
level Logger level for this server.

Valid values: (FATAL | CRIT | WARN | INFO | DEBUG)

Beginning with Splunk 4.3.4, Splunk does not support the CRIT logger level.

Example

Describes the logger for the Application Manager. 


curl -k -u admin:pass https://localhost:8089/services/server/logger/Application



<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>logger</title>
  <id>https://localhost:8089/services/server/logger</id>
  <updated>2011-07-02T15:10:44-07:00</updated>
  <generator version="100492"/>
  <author>
    <name>Splunk</name>
  </author>
  <opensearch:totalResults>1</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>Application</title>
    <id>https://localhost:8089/services/server/logger/Application</id>
    <updated>2011-07-02T15:10:44-07:00</updated>
    <link href="/services/server/logger/Application" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/logger/Application" rel="list"/>
    <link href="/services/server/logger/Application" rel="edit"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="eai:acl">. . .</s:key>
        <s:key name="eai:attributes">
          <s:dict>
            <s:key name="optionalFields">
              <s:list/>
            </s:key>
            <s:key name="requiredFields">
              <s:list>
                <s:item>level</s:item>
              </s:list>
            </s:key>
            <s:key name="wildcardFields">
              <s:list/>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="level">WARN</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

POST server/logger/{name}

Sets the logging level for a specific logging category.

Request

Name Type Required Default Description
level Enum
✓
 Valid values: (FATAL | CRIT | WARN | INFO | DEBUG)

The desired logging level for this category.

Beginning with Splunk 4.3.4, Splunk does not support the CRIT logger level.

Response Codes

Status Code Description
200 Updated successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
402 The Splunk license in use has disabled this feature.
403 Insufficient permissions to edit logger configuration.
404 Logger configuration does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.
503 This feature has been disabled in Splunk configuration files.

Returned Values

No values returned for this request.

Example

Sets the level of ApplicationManager logger to INFO. 


curl -k -u admin:pass https://localhost:8089/services/server/logger/Application \
	-d level=INFO



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>logger</title>
  <id>https://localhost:8089/services/server/logger</id>
  <updated>2011-07-07T00:24:02-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <s:messages/>
</feed>


server/settings

Provides access to server configuration information for an instance of Splunk.

GET server/settings

Returns the server configuration of an instance of Splunk.

Request

Name Type Required Default Description
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view server settings.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
SPLUNK_DB Absolute filepath to the default index for this instance of Splunk.
SPLUNK_HOME Absolute filepath to the local installation of this instance of Splunk.
enableSplunkWebSSL Indicates if https and SSL is enabled for Splunk Web.
host The default hostname to use for data inputs that do not override this setting.
httpport Port on which Splunk Web is listening for this instance of Splunk.

Defaults to 8000. If using SSL, set to the HTTPS port number.

mgmtHostPort The port on which Splunk Web is listening for management operations. Defaults to 8089.
minFreeSpace Safe amount of space in MB that must exist for splunkd to continue operating.

minFreespace affects search and indexing:

Before attempting to launch a search, splunk requires this amount of free space on the filesystem where the dispatch directory is stored ($SPLUNK_HOME/var/run/splunk/dispatch).

Applied similarly to the search quota values in authorize.conf and limits.conf.

For indexing, periodically, the indexer checks space on all partitions that contain splunk indexes as specified by indexes.conf. When you need to clear more disk space, indexing is paused and Splunk posts a ui banner + warning.

pass4SymmKey Password string that is prefixed to the splunk symmetric key, generating the final key to sign all traffic between master/slave licenser.
serverName Name used to identify this Splunk instance for features such as distributed search.
sessionTimeout Time range string to set the amount of time before a user session times out, expressed as a search-like time range. Default is 1h (one hour).

For example:

24h: (24 hours)

3d: (3 days)

7200s: (7200 seconds, or two hours)

startwebserver Indicates if Splunk Web is started.
trustedIP The IP address of the authenticating proxy. Set to a valid IP address to enable SSO.

Disabled by default. Normal value is '127.0.0.1'

Example

List the server configuration of this instance of Splunk. 


curl -k -u admin:pass https://localhost:8089/services/server/settings



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>server-settings</title>
  <id>https://localhost:8089/services/server/settings</id>
  <updated>2011-07-08T01:56:40-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>settings</title>
    <id>https://localhost:8089/services/server/settings/settings</id>
    <updated>2011-07-08T01:56:40-07:00</updated>
    <link href="/services/server/settings/settings" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/settings/settings" rel="list"/>
    <link href="/services/server/settings/settings" rel="edit"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="SPLUNK_DB">/home/amrit/temp/curl/splunk/var/lib/splunk</s:key>
        <s:key name="SPLUNK_HOME">/home/amrit/temp/curl/splunk</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="enableSplunkWebSSL">0</s:key>
        <s:key name="host">MrT</s:key>
        <s:key name="httpport">8001</s:key>
        <s:key name="mgmtHostPort">8085</s:key>
        <s:key name="minFreeSpace">2000000</s:key>
        <s:key name="pass4SymmKey">changeme</s:key>
        <s:key name="serverName">MrT</s:key>
        <s:key name="sessionTimeout">1h</s:key>
        <s:key name="startwebserver">1</s:key>
        <s:key name="trustedIP"/>
      </s:dict>
    </content>
  </entry>
</feed>

server/settings/{name}

GET server/settings/{name}

Returns the server configuration of this instance of Splunk.

"settings" is the only valid value for {name} in this endpoint. This endpoint returns the same information as GET server/settings.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view server settings.
404 Server settings do not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

No values returned for this request.

Example

Displays server settings. "settings" is the only valid value for {name} in this endpoint.

Returns the same information that GET server/settings returns. 

curl -k -u admin:pass https://localhost:8089/services/server/settings/settings

See the response for GET server/settings.

POST server/settings/{name}

Updates the server configuration of this instance of Splunk.

"settings" is the only valid value for {name} in this endpoint.

Request

Name Type Required Default Description
SPLUNK_DB String Path to the default index for this instance of Splunk.

The default location is:

$SPLUNK_HOME/var/lib/splunk/defaultdb/db/

enableSplunkWebSSL Boolean Toggles between https and http. If true, enables https and SSL for Splunk Web.
host String The default hostname to use for data inputs that do not override this setting.
httpport String Specifies the port on which Splunk Web is listening for this instance of Splunk. Defaults to 8000. If using SSL, set to the HTTPS port number.

httpport must be present for SplunkWeb to start. If omitted or 0 the server will NOT start an http listener.

mgmtHostPort String The port on which Splunk Web is listening for management operations. Defaults to 8089.
minFreeSpace Number Specifies, in MB, a safe amount of space that must exist for splunkd to continue operating.

minFreespace affects search and indexing:

Before attempting to launch a search, splunk requires this amount of free space on the filesystem where the dispatch directory is stored ($SPLUNK_HOME/var/run/splunk/dispatch).

Applied similarly to the search quota values in authorize.conf and limits.conf.

For indexing, periodically, the indexer checks space on all partitions that contain splunk indexes as specified by indexes.conf. When you need to clear more disk space, indexing is paused and Splunk posts a ui banner + warning.

pass4SymmKey String Password string that is prefixed to the splunk symmetric key, generating the final key to sign all traffic between master/slave licenser.
serverName String Specify an ASCII String to set the name used to identify this Splunk instance for features such as distributed search. Defaults to <hostname>-<user running splunk>.
sessionTimeout String Specify a time range string to set the amount of time before a user session times out, expressed as a search-like time range. Default is 1h (one hour).

For example:

24h: (24 hours)

3d: (3 days)

7200s: (7200 seconds, or two hours)

startwebserver Boolean Specify 1 to enable Splunk Web. 0 disables Splunk Web. Default is 1.
trustedIP String The IP address of the authenticating proxy. Set to a valid IP address to enable SSO.

Disabled by default. Normal value is '127.0.0.1'

Response Codes

Status Code Description
200 Updated successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
402 The Splunk license in use has disabled this feature.
403 Insufficient permissions to edit server settings.
404 Server settings do not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.
503 This feature has been disabled in Splunk configuration files.

Returned Values

Attribute Description
SPLUNK_DB Path to the default index for this instance of Splunk.

The default location is:

$SPLUNK_HOME/var/lib/splunk/defaultdb/db/

SPLUNK_HOME Absolute filepath to the local installation of this instance of Splunk.
enableSplunkWebSSL Indicates if https and SSL is enabled for Splunk Web.
host The default hostname to use for data inputs that do not override this setting.
httpport Port on which Splunk Web is listening for this instance of Splunk.

Defaults to 8000. If using SSL, set to the HTTPS port number.

mgmtHostPort The port on which Splunk Web is listening for management operations. Defaults to 8089.
minFreeSpace Safe amount of space in MB that must exist for splunkd to continue operating.

minFreespace affects search and indexing:

Before attempting to launch a search, splunk requires this amount of free space on the filesystem where the dispatch directory is stored ($SPLUNK_HOME/var/run/splunk/dispatch).

Applied similarly to the search quota values in authorize.conf and limits.conf.

For indexing, periodically, the indexer checks space on all partitions that contain splunk indexes as specified by indexes.conf. When you need to clear more disk space, indexing is paused and Splunk posts a ui banner + warning.

pass4SymmKey Absolute filepath to the local installation of this instance of Splunk.
serverName Name used to identify this Splunk instance for features such as distributed search.
sessionTimeout Time range string to set the amount of time before a user session times out, expressed as a search-like time range. Default is 1h (one hour).

For example:

24h: (24 hours)

3d: (3 days)

7200s: (7200 seconds, or two hours)

startwebserver Indicates if Splunk Web is started.
trustedIP The IP address of the authenticating proxy. Set to a valid IP address to enable SSO.

Disabled by default. Normal value is '127.0.0.1'

Example

Update the timout period for a user session to two hours. 


curl -k -u admin:pass https://localhost:8089/services/server/settings/settings \
	-d sessionTimeout=2h



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>server-settings</title>
  <id>https://localhost:8089/services/server/settings</id>
  <updated>2011-07-08T01:56:40-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>settings</title>
    <id>https://localhost:8089/services/server/settings/settings</id>
    <updated>2011-07-08T01:56:40-07:00</updated>
    <link href="/services/server/settings/settings" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/settings/settings" rel="list"/>
    <link href="/services/server/settings/settings" rel="edit"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="SPLUNK_DB">/home/amrit/temp/curl/splunk/var/lib/splunk</s:key>
        <s:key name="SPLUNK_HOME">/home/amrit/temp/curl/splunk</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="enableSplunkWebSSL">0</s:key>
        <s:key name="host">MrT</s:key>
        <s:key name="httpport">8001</s:key>
        <s:key name="mgmtHostPort">8085</s:key>
        <s:key name="minFreeSpace">2000000</s:key>
        <s:key name="pass4SymmKey">changeme</s:key>
        <s:key name="serverName">MrT</s:key>
        <s:key name="sessionTimeout">2h</s:key>
        <s:key name="startwebserver">1</s:key>
        <s:key name="trustedIP"/>
      </s:dict>
    </content>
  </entry>
</feed>
Retrieved from "http://docs.splunk.com/Documentation/Splunk/4.3/RESTAPI/RESTsystem"

This documentation applies to the following versions of Splunk: 4.2.2 , 4.2.3 , 4.2.4 , 4.2.5 , 4.3 , 4.3.1 , 4.3.2 , 4.3.3 , 4.3.4 , 4.3.5 , 4.3.6 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!