TIPS & TRICKS

API 4TW

Ok, here’s a real blog post to make up for that last one. You may have heard that one of the major features of Splunk 4.0 is a brand new REST API. This is the interface that both the CLI and the web UI use to manage Splunk inputs, retrieve splunkd status, perform searches, etc. You, too, can use this API for doing all sorts of good or evil – read on.

Explore a bit…

Exploring it is easy – point Firefox at your your local Splunk instance’s management port. For example, https://localhost:8089/services is the default. Adjust https vs http as necessary, as well as the port. Note that this is the management port, not the web interface port (which is 8000 by default).

In a decent browser (my favorite, Konqueror, doesn’t seem to cut it :( ), you’ll see a list of links, with smaller links beneath each. This is just a user-friendly rendering of our Atom XML feed. View the raw XML by right clicking and choosing View Source, if you wish.

You can use this set of links to inspect the state of your running splunkd. Drilling down into data/inputs/monitor, for example, displays all Monitor inputs that Splunk knows about. If one of these is a directory, clicking the members link below it will display all the files being monitored within that dir. Note that not all of the links will work by simply clicking on them. The remove action, for example, requires an HTTP DELETE action, whereas edit requires an HTTP POST containing the parameters you’d like to change.

But APIs are serious business…

Agreed, you’re not going to use the browser with the API for anything more than playing around (although the Poster extension for Firefox is quite useful…).

If you’re familiar with HTTP/REST, choose your favorite library and run with it. Start by making a POST to /services/auth/login with the parameters username=<username> and password=<password>. You’ll get a response like the following:

  <response>
  <sessionKey>a48fe44eb76ecf08674954e47c403f24</sessionKey>
  </response>

Then, simply include this session key in the HTTP headers for any requests you make to the API:

  Authorization: Splunk a48fe44eb76ecf08674954e47c403f24

And if I’m lazy?

Don’t worry, I’m lazy too. Splunk includes a handy little tool that lets you easily make calls to the Splunk API. For example:

  splunk _internal call /data/inputs/monitor -auth admin:changeme

Will perform an HTTP GET on https://localhost:8089/services/data/inputs/monitor. Since this is a Splunk utility, it will read your config files and automatically enable/disable SSL on the request, as well as change the destination port as necessary. You can also use -uri to point the request to other servers. :)

The tool allows for POSTs and other HTTP actions, but more on that in my next post…

Enough shenanigans, I want a real example.

Sure.. how about this thing?

A KDE 4 desktop widget monitoring a handful of boxes around the office.  1 outta 5 ain\'t so bad, is it?

This is a Plasmoid for the KDE 4 desktop environment. It’s written in C++ using the cross-platform Qt toolkit and KDE’s Plasma library.

The entire code will be linked further down this post, but the most important parts are the HTTP request, and the XML parsing.

We first make a request (using our handy CLI tool, because it’s easy) to our REST endpoint for messages, where highly important notices end up:

  // build args.
  QStringList args;
  args << "_internal"
       << "call"
       << "/admin/messages"
       << "-auth" << userPass; // this is OK even in the free version.
  if (!uri.isEmpty())
    args << "-uri" << (QString("http") + (info.useSSL ? "s" : "") + "://" + uri);

(Note that the password is sent as a command line argument - not the most secure thing to do on a multi-user system. Luckily, this is just a tech demo.)

When the process completes, we check the return code, and then use an XPath query to parse any messages out of the XML returned on stdout:

  // build xpath query with splunk's namespace info.
  QXmlQuery query;
  query.bindVariable("data", &xmlData);
  query.setQuery("declare namespace a='http://www.w3.org/2005/Atom';"
                 "declare namespace s='http://dev.splunk.com/ns/rest';"
                 // choose only the s:key nodes that match their entry node's title.
                 "doc($data)/a:feed/a:entry/a:content/s:dict/string(s:key[(../../../a:title = @name)])");

  if (!query.evaluateTo(&messages))
    messages << "Parsing of status failed.";

...and throw it up on the screen. But you'll have read the code to find that part. 😛

I wanna try it!

The source code is here, give it a shot.

Installation instructions:

  • tar -jxvf splunk_status*.tar.bz2
  • cd splunk_status-version
  • cmake . (don't miss that dot!)
  • make
  • At this point you can try 'make install', but on my system I had to manually copy things to the right locations: cp lib/splunk_status.so /usr/lib/kde4/splunk_status.so and cp splunk_status.desktop /usr/share/kde4/services/
  • Rebuild KDE's cache: kbuildsycoca4
  • Restart the Plasma workspace: kquitapp plasma && sleep 1 && plasma

    Before you enable it in KDE4, you need to create a small config file by hand. It will look something like the following.

    ~/.kde/share/config/splunkstatusrc:

      [settings]
      cmdPath = /opt/splunk/bin/splunk
    
      [servers]
      localhost:8089 = admin,changeme,ssl
      amritdesktop:8089 = admin,changeme,nossl
      tiny:1236 = admin,changeme
      spacecake:57089 = admin,changeme,ssl
      10.1.1.50:9089 = admin,changeme,ssl
    

    The settings/cmdPath variable is required, as is at least one entry under servers. The latter is formatted as host:port = username,password,(ssl|nossl). Remember that the port here is your management port, not your web interface port. The SSL specification is optional, and defaults to ssl. Be sure you get that one right as well (SSL is enabled on default Splunk installs).

    Now...

    Is anyone actually gonna try this thing? :)

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

Splunk
Posted by

Splunk

Join the Discussion