Splunk Enterprise 6.2.3REST API TutorialsGenerated: 5/01/2015 2:00 am

Copyright (c) 2015 Splunk Inc. All Rights Reserved

Table of ContentsREST API tutorials...............................................................................................1

Accessing and updating Splunk Enterprise configurations.......................1Creating searches using the REST API.....................................................6 Examples using the Splunk REST API...................................................12

i

REST API tutorials

Accessing and updating Splunk EnterpriseconfigurationsThis section describes how to use the Splunk Enterprise REST API to accessand update information contained in configuration files (*.conf files). For moreinformation on configuration files, see About Configuration Files andConfiguration File Precedence in the Splunk Admin manual.

Two sets of endpoints give access to configuration files:

properties/configs/conf-{file}/

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

Setting permissionsEnabling or disabling a stanza in a configurationMoving a resource

Reading configuration files

The way you read configurations files differs between properties/ andconfigs/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 thekey/value pairs.

GET propertiesReturns the names of configuration files.

GET properties/{file_name}

1

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 stanzanames for props.conf:

curl -k -u admin:passhttps://localhost:8089/servicesNS/nobody/search/properties/propsThe response:

props https://localhost:8089/servicesNS/nobody/search/properties/props/ . . .

ActiveDirectory https://localhost:8089/servicesNS/nobody/search/properties/props/ActiveDirectory 2011-09-14T15:48:40-07:00 PerformanceMonitor https://localhost:8089/servicesNS/nobody/search/properties/props/PerformanceMonitor 2011-09-14T15:48:40-07:00 . . .

wmi https://localhost:8089/servicesNS/nobody/search/properties/props/wmi 2011-09-14T15:48:40-07:00 wtmp https://localhost:8089/servicesNS/nobody/search/properties/props/wtmp

2

2011-09-14T15:48:40-07:00

The /search/properties/props/websphere_core GET operation returns thekey/value pairs for the props.conf file webshpere_core stanza.

curl -k -u admin:passhttps://localhost:8089/servicesNS/nobody/search/properties/props/websphere_coreThe response:

websphere_core https://localhost:8089/servicesNS/nobody/search/properties/props/websphere_core . . .

ANNOTATE_PUNCT https://localhost:8089/servicesNS/nobody/search/properties/props/websphere_core/ANNOTATE_PUNCT 2011-09-14T15:55:01-07:00 True BREAK_ONLY_BEFORE https://localhost:8089/servicesNS/nobody/search/properties/props/websphere_core/BREAK_ONLY_BEFORE 2011-09-14T15:55:01-07:00 ^NULL\s . . .

maxDist https://localhost:8089/servicesNS/nobody/search/properties/props/websphere_core/maxDist 2011-09-14T15:55:01-07:00 70

3

configs/conf-{file} endpoints

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

For example, the /search/configs/conf-props GET operation lists theprops.conf configuration for the default search application.

curl -k -u admin:passhttps://localhost:8089/servicesNS/nobody/search/configs/conf-propsThe response, showing elided fragments of a few stanzas in props.conf.

conf-props https://localhost:8089/servicesNS/nobody/search/configs/conf-props 2011-09-14T15:31:24-07:00 . . .

access_combined https://localhost:8089/servicesNS/nobody/system/configs/conf-props/access_combined . . .

1 1 . . .

28 1 . . .

exchange https://localhost:8089/servicesNS/nobody/system/configs/conf-props/exchange 2011-09-14T15:31:24-07:00 . . .

1 1 . . .

search nobody

4

100

Updating Configuration Files

You update a configuration file by adding or editing stanzas to the file. How youdo this differs between properties and configs/conf-{file} endpoints. DoDELETE operations from only the configs/conf-{file} endpoints.

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

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

properties

Use the POST operation with various properties endpoints to updateconfiguration 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 canalso specify key/value pairs for the newly added stanza. For example, the/search/configs/conf-props POST operation creates a new stanza andkey/value pairs in props.conf for the default search application.

curl -k -u admin:passhttps://localhost:8089/servicesNS/nobody/search/configs/conf-props \ -d name=myweblogs \ -d CHARSET=UTF-8 \ -d SHOULD_LINEMERGE=falseconfigs/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.

5

Creating searches using the REST APIUse the search/jobs endpoint to create a search job in Splunk. However, beforecreating searches you should be aware of how searches work and how tostructure a search so you can easily access the results.

Learn about searches

The best place to learn about searches and how to write searches is the SearchManual.

Here are some highlights from the Search Reference that can help you getstarted creating searches:

Search command cheat sheet Quick command reference complete withdescriptions and examples.

Write better searches Provides some simple rules of thumb and bestpractices to help you write searches that run more efficiently.

Popular search commands A list describing the more frequently usedsearch commands.

Execution costs Describes how to troubleshoot the efficiency of a search. Search job properties Lists and defines the properties of a search job. Search Command Reference Complete syntax of Splunk searchcommands.

REST endpoints for searches

Here is a brief description of some of the key endpoints for creating andaccessing searches.

/search/jobsCreate or access the results of search jobs. Returns a search ID (sid) that youuse when accessing the results of a search.

/search/jobs/exportStream search results as they become available. Does not create a search ID forlater access.

/search/jobs/{search_id}/controlExecute a job control command for a search, such as pause, setpriority, orfinalize.

6

/search/jobs/{search_id}/eventsReturn untransformed events of a search.

/search/jobs/{search_id}/resultsReturn transformed events of a search.

/search/jobs/{search_id}/summaryReturn summary information for fields of a search.

/search/jobs/{search_id}/timelineReturn event distribution over time of the so-far-read untransformed events.

/saved/searchesCreate or access the configuration of saved searches.

Tips on creating searches

When creating a search (POST /search/jobs), consider the following properties ofthe search:

max_countSet this parameter for searches returning more than the default maximum of10000 events. Otherwise you may not be able to retrieve results in excess of thedefault.

status_bucketsTo access summary and timeline information from a search job, specify a valuefor status_buckets. The default value is zero. For example, searches spawnedfrom the Splunk timeline specify status_buckets=300.

rfUse the rf parameter to add required fields to a search. Adding fields guaranteesresults for the endpoints that return events and a summary. (Therequired_fields parameter has been deprecated in favor of the rf parameter.)

Tips on accessing searches

When accessing the results of a search (GET /search/jobs/{search_id}), considerthe following:

search, offset, and count parametersUse these parameters to a GET operation to filter or limit the results returned.

7

dispatchStatedispatchState is one of the properties returned when accessing a search. Itprovides the state of a search, which can be any of the following:

QUEUEDPARSINGRUNNINGPAUSEDFINALIZINGFAILEDDONE

search job propertiesThe GET operation for /search/jobs returns all the properties of a search. Theseproperties are described in the parameters to the POST operation. Search jobproperties are also described in "View search job properties with the Search JobInspector".

performanceThe GET operation for /search/jobs returns information that helps youtroubleshoot the efficiency of a search. Refer to "Execution costs" in "Viewsearch job properties with the Search Job Inspector" for more information.

Example: Create a search

Many calls to Splunk's API involve running some kind of search. For example,you may wish to run a search within Splunk and POST the results to a third partyapplication. Use the endpoints located at the../services/search/ URIs.

When you run a search, Splunk launches a search process asynchronously. Thismeans that you must poll the jobs or events endpoint to see if your search hasfinished.

Create a search job

Create a search job using the POST operation at search/jobs/. Set your searchas the POST payload. For example:

curl -u admin:changeme -k https://localhost:8089/services/search/jobs-d search="search *"This simple example runs the search for *. It returns an XML response such as:

8

1258421375.19

You need the search ID to retrieve the search, which is returned within the tags. In the example above this is 1258421375.19.

Check status of a search

Check the status of a search job by accessing the GET operation of search/jobs/.If you know the search's ID, you can access search/jobs/{search_id} to getinformation about that search only:

curl -u admin:changeme -khttps://localhost:8089/services/search/jobs/1258421375.19If you're not sure what searches you're running, the GET operation at search/jobsendpoint returns a list of searches with their search IDs.

curl -u admin:changeme -k https://localhost:8089/services/search/jobs/ Get search results

Use the results endpoint located at /search/jobs//results/ to retrieve yoursearch results. This endpoint returns results only when your search hascompleted. You can also get output from the events endpoint located at/search/jobs/{search_id}/events/ while your search is still running. For completesearch results, use the results endpoint.

You can return search results in JSON, CSV or XML by setting the output_modeparameter. By default, results are returned in XML format.

For example, to retrieve search results in CSV format, make the following call.

Note: The curl listing includes --get because you are passing a parameter to aGET operation.

curl -u admin:changeme \ -khttps://localhost:8089/services/search/jobs/1258421375.19/results/ \ --get -d output_mode=csvNote: This is one method that you can use to export large numbers of searchresults out of Splunk Enterprise. For more information about exporting search

9

results with the REST API, as well as information about the other export methodsoffered by Splunk Enterprise, see "Export search results" in the Search Manual.

Python example

Here's an example of authenticating against a Splunk server and running asearch query in Python. After running the search, the script returns the search ID(sid).

#!/usr/bin/python -u

import urllibimport httplib2from xml.dom import minidom

baseurl = 'https://localhost:8089'userName = 'admin'password = 'pass'

searchQuery = 'sourcetype=access_common | head 5'# Authenticate with server.# Disable SSL cert validation. Splunk certs are self-signed.serverContent =httplib2.Http(disable_ssl_certificate_validation=True).request(baseurl +'/services/auth/login', 'POST', headers={}, body=urllib.urlencode({'username':userName,'password':password}))[1]

sessionKey =minidom.parseString(serverContent).getElementsByTagName('sessionKey')[0].childNodes[0].nodeValue

# check if the query has the search operatorif not searchQuery.startswith('search'): searchQuery = 'search ' + searchQuery

# Run the search.# Again, disable SSL cert validation.printhttplib2.Http(disable_ssl_certificate_validation=True).request(baseurl +'/services/search/jobs','POST', headers={'Authorization': 'Splunk %s' %sessionKey},body=urllib.urlencode({'search': searchQuery}))[1] Ruby example

The following example shows how to use Ruby to authenticate against theSplunk REST API with a generic user name and password. Then, run a search,delete a specific search job and list out available search jobs. Note that the list is

10

returned in XML and not parsed. To parse the results from endpoints, use anXML parser such as libxml. Also, you'll need to install the hpricot gem to get thisto work.

require 'net/https'require 'rubygems'require 'hpricot'

class SplunkClient HOST = 'localhost' PORT = 8089 USER = 'admin' PASSWORD = 'changeme'

def splunk_ssl_post_request(path, data = nil, headers = nil) http = Net::HTTP.new(HOST, PORT) http.use_ssl = true http.verify_mode = OpenSSL::SSL::VERIFY_NONE http.post(path, data, headers).body end

def session_key @session_key ||= load_session_key end

def load_session_key doc = Hpricot(splunk_ssl_post_request("/services/auth/login","username=#{USER}&password=#{PASSWORD}")) (doc/"//sessionkey").inner_html end

def create_job query search = "search index=internetmail #{query}" splunk_ssl_post_request("/services/search/jobs", "search=#{CGI::escape(search)}", { 'authorization' => "Splunk#{session_key}" })

end

def list_jobs xml = splunk_ssl_post_request("/services/search/jobs/", nil,{'authorization' => "Splunk #{session_key}"}) puts xml end

def search_results(sid) doc = Hpricot( splunk_ssl_post_request("/services/search/jobs/#{sid}/events", nil,

11

{'authorization' => "Splunk#{session_key}"})) (doc/"/results/result").collect do | result | log_text = (result/"field[@k='_raw']/v").inner_text Email.new log_text end end

def splunk_ssl_delete_request(path, headers = nil) http = Net::HTTP.new(HOST, PORT) http.use_ssl = true http.verify_mode = OpenSSL::SSL::VERIFY_NONE http.delete(path, headers).body end

def delete_job(sid) splunk_ssl_delete_request("/services/search/jobs/#{sid}", { 'authorization' => "Splunk#{session_key}" })

endend

# Here's the actual operating codeclient = SplunkClient.newputs client.list_jobs

Examples using the Splunk REST APIThis section shows some typical use cases for the Splunk REST API. Theseexamples show how to use the servicesNS endpoints to access resources withina user/app context. They also show some of the additional operations available,such as moving an object to a different app or changing the permissions of anobject.

Create a new Splunk object for a specific contextCreate a saved search for the user Alice that is available from the app, myapp.This saved search is private to Alice.

curl -k -u alice:passhttps://localhost:8089/servicesNS/alice/myapp/saved/searches/ \ -d name=mysearch \ -d search=*

12

Edit a Splunk objectChange the above search created for Alice.

Because this search is private to Alice, she can edit the search.

curl -k -u alice:passhttps://localhost:8089/servicesNS/alice/myapp/saved/searches/mysearch \ -d search="index=mai*"

Share an object to an app, modify its permissions, and edit itMake Alice's saved search, mysearch, available through the app, myapp. Allowall users permissions to read the saved search.

curl -k -u admin:passhttps://localhost:8089/servicesNS/alice/myapp/saved/searches/mysearch/acl \ -d perms.read=* \ -d owner=alice \ -d sharing=app

Edit the search at the shared location. Because the search is now a sharedresource, use for the context.

curl -k -u alice:passhttps://localhost:8089/servicesNS/nobody/myapp/saved/searches/mysearch \ -d search="index=main"

Move an object to a different appThe saved search that was previously available to all in the context of myapp isnow only available in the context of otherapp.

13

curl -k -u admin:passhttps://localhost:8089/servicesNS/nobody/myapp/saved/searches/mysearch/move \ -d user=nobody \ -d app=otherapp

Access objects available in all user/app contextsUsing wildcards, access all saved searches that you have permission to view.

For an admin user, this includes other user's private saved searches.

For a non-admin user, you retrieve only saved searches you have permission toview.

curl -k -u admin:passhttps://localhost:8089/servicesNS/-/-/saved/searches

curl -k -u alice:pwhttps://localhost:8089/servicesNS/-/-/saved/searches

14

Table of ContentsREST API tutorials Accessing and updating Splunk Enterprise configurations Creating searches using the REST API Examples using the Splunk REST API