Poke at our API

With this tool:

$ splunk _internal call <relative rest path>
[-get:<param> <value>] ... [-post:<param> <value>] ...
[-method <http action>] [-multival] [-auth <user>:<pass>]

As mentioned in my previous post, exploring our endpoints is pretty simple to do, by pointing your browser at the Splunk management port. Actually making use of the endpoints requires more work, but this utility makes it easy to get started.

Restarting an input component is a handy example, such as restarting monitoring after editing inputs.conf by hand:

splunk _internal call /data/inputs/monitor/_reload
This is supported by the other components in /data/inputs, as well – browse there and look for the _reload links.

Parameters

• get:foo bar – adds an HTTP GET parameter to the request, with name ‘foo’ and value ‘bar’. Can be specified multiple times for different parameters, or for the same parameter with multival (see below).
• post:foo bar – adds an HTTP POST parameter to the request, with name ‘foo’ and value ‘bar’. Can be specified multiple times for different parameters, or for the same parameter with multival (see below).
  Will set the request method to POST instead of the default GET.
• method (GET|POST|DELETE) – changes the HTTP method that will be used to make the request. For example, GET is typically used to list configurations, while POST is used to edit them.
• multival – HTTP requests allow multiple values per parameter. Specifying this flag will cause multiple -get:param or -post:param arguments with the same param name to be honored. Note that most endpoints will not make use of multiple parameter values.
• auth user:pass – srsly?

More examples

Be sure to use -auth user:pass with these examples as necessary..

Input management

You can list all TCP inputs:

$ splunk _internal call /data/inputs/tcp/raw

Or restrict that listing to only inputs with a particular sourcetype:

$ splunk _internal call /data/inputs/tcp/raw -get:search sourcetype=foo

You’ll notice each returned input has a few links such as ‘edit’, assuming your user has permission to edit inputs:

<link href="/servicesNS/nobody/search/data/inputs/tcp/raw/7092" rel="edit"/>

Using this URI path provided by the server, we can change the sourcetype or any other parameter of that input:

$ splunk _internal call /servicesNS/nobody/search/data/inputs/tcp/raw/7092 -post:sourcetype bar -post:index bardata

These changes will be reflected in your configuration, and since this is an input method, the changes will take effect immediately (as with using the CLI & UI to make these changes).

User management

With a search, you can quickly find all roles with a particular capability. For example, to see which roles are allowed to edit indexes:

$ splunk _internal call /services/authentication/roles -get:search indexes_edit

Or search for all users with a particular role:

$ splunk _internal call /services/authentication/users -get:search helpdesk

And use the remove link in the returned Atom XML to get rid of each user:

$ splunk _internal call /services/authentication/users/bobbyd -method DELETE

Other configuration items

Creating configurations is also fairly standardized. The create link in the an endpoint lists required and optional arguments. For example, clicking on ‘create’ at /services/saved/searches reveals that the ‘name’ and ‘search’ parameters are required for creating a saved search.

With this knowledge, adding one via the API is easy:

$ splunk _internal call /services/saved/searches -post:name "my www errors" -post:search "404 OR 503"

Server management

The following request restarts the Splunk instance:

$ splunk _internal call /services/server/control/restart

Next…

Our REST API documentation is still in the works, but in the meantime feel free to poke around the management port on your own and see what’s available. As a guideline, most administration tasks available in the CLI or in SplunkWeb’s Manager section are done through the REST interface and thus can be incorporated into your own utilities to help accelerate common tasks.

For example, your Splunk administrator may want a small native desktop application that allows for targeting all of your Splunk servers individually to manage users. Alternatively, a set of checkboxes could allow an administrator to effect one particular configuration change across many servers in parallel. In fact, you even have the option of writing your own Splunk REST endpoint in Python, allowing you to expose any level of custom configuration via the API… but perhaps that’s best left to a future post. 😉

If you come up with a usage of the API that makes life easier for you, leave a comment – we might want to use it, too!

----------------------------------------------------
Thanks!
Amritpal Bath