amrit

API 4TW

amrit — Thu, 27 Aug 2009 19:03:41 +0000

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= and password=. You’ll get a response like the following:

  
  a48fe44eb76ecf08674954e47c403f24

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?

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?

Reload 4 Auth

amrit — Thu, 20 Aug 2009 19:54:40 +0000

This will be a very brief post, to fulfill my obligations. I’ll share something a little more informative, perhaps even more interesting, in an upcoming post (soon… I promise (kinda) this time).

As of Splunk 4.0, our old somewhat-of-an-API has been replaced with an entirely new REST API, invalidating my old post on reloading authentication from the command line.

Sooo….. in 4.x, you can restart the authentication system with the following command:

$ splunk _internal call /authentication/providers/services/_reload -auth admin:changeme

Any errors should be obvious in the resulting XML. As of 4.0.3, you’ll also get a non-zero return code upon receiving errors from the API. And I’ve filed a bug (just now) to expose this as a real CLI command, so soon this post will no longer be very important.

Happy now, Simeon?

Reloading the auth system via CLI

amrit — Wed, 26 Nov 2008 19:26:20 +0000

Note: Tina pointed out that this does not apply to the authorize.conf file. This will be fixed in an upcoming version of splunk.

This comes up every once in a while on the support channel (EFnet/#splunk), so I guess that means I should do a blog post on it.

If you’re making changes to the authentication.conf file and want to reload Splunk’s auth system without going through the web UI, you can use one of our internal functions to do it at the command line:

$ splunk _internal rpc-auth ‘’

This fires off the same call that the UI would use to reload the auth system, so it functions identically. Note that this is an authenticated call, so you’ll need to use one of the standard authentication methods (-auth, splunk login, or the SPLUNK_USERNAME/SPLUNK_PASSWORD env vars…).

Saving the environment, one beer pong game at a time.

amrit — Mon, 05 Nov 2007 21:42:07 +0000

Recycling is universally considered to be a good thing, right?

Good. Then that means that we at Splunk are obligated to play play beer pong every Friday! I figure that with all the bottles and cans that subsequently go into the recycling bin, we’re probably offsetting a small percentage of the many computers we use here… amirite?

If you disagree, you can voice your opinions in person. See you here Friday at 5PM.

Things you don’t want to hear at work

amrit — Wed, 10 Oct 2007 01:21:08 +0000

Lots of things are said here that are… hmm, what’s the word… inappropriate? disgusting? TMI? omgwtfbbq?

My boss just told me, “Amrit, I have a camera on my computer. And when I’m at home, anytime you want, I can turn on the camera and you can watch.”

There was more, but I think my ears reflexively closed in on themselves.

Administering remote Splunk servers via the CLI

amrit — Tue, 03 Jul 2007 15:02:46 +0000

It’s a little known (mainly because it’s undocumented) fact that it is possible to use the Splunk CLI to manage remote Splunk servers. This capability has been built into the product since version 2.1, and allows one to do things such as remotely manage data inputs, run searches, manage users, etc. For fairly obvious reasons, this cannot be done with commands that require Splunkd to be stopped.

The syntax is simple:

/opt/splunk/bin/splunk [] -uri https://my2ndSplunkBox:8089

The key here is the -uri parameter, which instructs the PCL to send all SOAP requests to the specified server. There are 3 pieces to the parameter: protocol, host, and port.

The protocol must be one of http or https, depending on whether or not SSL is enabled on the Splunkd port. Most users will want the latter, as recent versions of Splunk enable SSL on this port by default.

The second part is the hostname or IP address of the host that the remote Splunk server is running on. This should need no real explanation - in this case, the remote server has the hostname my2ndSplunkBox.

The last part of the argument is the Splunkd port (aka the management port). Note that this is not the port that’s used to reach the web interface, but the port that Splunkd listens on for incoming SOAP requests. If you’re unsure of what this port is, try the default, which is 8089. Alternatively, splunk show splunkd-port will display the Splunkd port that the current server is listening on.

As a practical example, one can add a tailed data input on the /var/log directory of host my2ndSplunkBox with the following command:

splunk add tail /var/log -uri https://my2ndSplunkBox:8089

The only caveat to this feature is that if you’re logged into your Splunk server via splunk login, you will have to re-authenticate when sending commands to the remote server (and once again when you resume targetting your local server by leaving off -uri). Workarounds include using the -auth parameter or the SPLUNK_USERNAME and SPLUNK_PASSWORD environment variables, but these are better left to a later post.

HI@WEB2.0

amrit — Tue, 03 Jul 2007 14:24:36 +0000

Well, I guess I had to start “blogging” eventually…

Hi, I’m Amrit, the main CLI (Command Line Interface) and PCL (Python Control Layer) guy here at Splunk. This means that I maintain our more common bash scripts (bin/splunk & friends), and our Python support scripts (site-packages/splunk/clilib/), which do the heavy lifting for a number of CLI & Web UI features.

These aren’t the only things I work on, but they are the parts of the Splunk codebase that have consumed most of my time since starting here in December 2005. I should also mention that Ivan Tam (no blog.. yet..?), who now works on the SplunkWeb UI, helped write the first implementation of the PCL during mid-2006.

Every now and then I’ll post some tips & tricks related to the things I’m working on, which you’ll hopefully find useful.

KTHXBAI