I’ve recently helped a customer integrate the SplunkJS stack into their own custom web application. I wanted to spread the knowledge so others could learn as well.

What is the SplunkJS stack you ask? The SplunkJS stack is a component of the Splunk Web Framework that allows web developers to create apps in their own development environment allowing them to access and manipulate Splunk data. This allows you greater flexibility over the look and feel of your app, including the use of third party visualization tools like D3 and Keylines.

This blog post will be a three part series. I will be covering the following topics in detail.

Before we get started, go download the SplunkJS stack so we’re all on the same page.

The fist hurdle in using the SplunkJS Stack is figuring out how to communicate with and authenticate against your Splunk search head. When using the SplunkJS stack you need to either use a proxy server or cross-origin resource sharing (CORS). Let’s start with the first method, using a local proxy server.

Authenticating Via Proxy

You’re free to use whatever proxy server you wish but I’m going to highlight using Nginx. Nginx (pronounced engine-x) is a free, open-source, high-performance HTTP server and reverse proxy. As of this blog post I’m using the 1.8.0 stable version. I’m going to show how to build Nginx from source and install on CentOS 6.6. If this doesn’t fit your environment you can still leverage the base config and follow the official Nginx install docs.

Install & Configure Nginx

You may need to install a few dependencies on your server in order to build Nginx. I was missing the PCRE and OpenSSL developer libraries.

yum install pcre-devel openssl-devel

Copy nginx-1.8.0.tar.gz to your server and uncompress it. I’m going to install into /opt/nginx but feel free to adjust. Also note that I’m running the Nginx worker processes as the http user.

cd nginx-1.8.0
./configure --user=http --prefix=/opt/nginx --with-http_ssl_module
make
sudo make install

If you want Nginx to start when the system starts then you’ll need to get an init script. You can download a start script for your OS here. If you’re using Redhat/CentOS you can get the init script directly here. I made a couple slight modifications since I installed in /opt/nginx.

nginx="/opt/nginx/sbin/nginx"
NGINX_CONF_FILE="/opt/nginx/conf/nginx.conf"

Make your init script executable.

chmod 755 /etc/init.d/nginx

Add the http user

# useradd http

Create a directory to host your web app

mkdir -p /var/www/html/static
chown -R http.http /var/www/html

We’ll now need to edit the default Nginx config at /opt/nginx/conf/nginx.conf. Modify the existing server and update the root directory to /var/www/html

location / {
            root   /var/www/html;
            index  index.html index.htm;
        }

We’re also going to add a section to proxy to our Splunk search head on the management port 8089. My search head is called splunk-dev and I have an entry in /etc/hosts but you could also use the server IP here. Add this block just below the location you modified above within the server block.

location /proxy/ {
            proxy_pass https://splunk-dev:8089/;
            proxy_ssl_session_reuse off;
        }

Lastly, we start Nginx.

# /etc/init.d/nginx start

There are a ton of different configuration parameters for Nginx. I am only using a very basic config to illustrate functionality. If you want to learn more, see the docs.

Install the SplunkJS Stack

Copy the SplunkJS stack to your server and place it in /var/www/html/static

Copy Examples

The SplunkJS stack comes with a directory named tests_and_samples. There are two files we’re going to use in this directory to test connecting to and authenticating with Splunk.

Copy both of these files to /var/www/html

Configure The SplunkJS Stack

The default config for the SplunkJS stack looks like this. In order to authenticate, at a very minimum you need to provide a dictionary of {username: username, password: password} along with the other parameters (proxyPath, scheme, host, port).

splunkjs.config({
    proxyPath: "/proxy",
    scheme: "https",
    host: "localhost",
    port: 8089,
    authenticate: function (done) {
        // TO DO: Custom function
    },
    onSessionExpired: function(authenticate, done) {
        // TO DO: Custom function
    },
    onDrilldown (drilldown) {
        // TO DO: Custom function
    }
});

There’s a great reference on the configuration here.

If you’d like to see a detailed example of using a custom authentication function and onSessionExpired fuction see this page in the docs.

Test The Examples

Now let’s test the examples that we copied to our server in an earlier section. Let’s start with test_login.html. Update the username and password to reflect the credentials you’re using to connect to Splunk. Please note that if you’re using a fresh install with the admin user you need to change the password from the default changeme. Splunk has a built-in security mechanism to block any external access to the REST API using the default password.

 splunkjs.config({
        proxyPath: '/proxy',
        scheme: 'https',
        host: 'mysplunkserver',
        port: 8089,
        authenticate: {username: 'admin', password: 'mychangedpassword'}
    });

Now you can hit this page at http://myserver/test_login.html. You should see a successful connection that looks like this.

You can also update the splunkjs.config in test_login_function.html and test that file if you like.

Use both of these test pages as boilerplate code to drop into your own custom app.

Authenticating Via CORS

What is CORS? Here is what Wikipedia says:

Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources (e.g. fonts) on a web page to be requested from another domain outside the domain from which the resource originated

Configure Splunk To Use CORS

To use CORS in Splunk you do to following.

Edit $SPLUNK_HOME/etc/system/local/server.conf

You can add multiple domains/ip’s as a list separated by spaces or commas. You can also use wildcards in your domain names.

[httpServer]
crossOriginSharingPolicy = *://my-domain.com, https://*.foobar.com

If you wanted to open it wide up you could literally put the following. I don’t suggest it, I’m merely illustrating if you want to simplify for testing purposes.

[httpServer]
crossOriginSharingPolicy = *

Copy Example

Copy test_cors.html from the SplunkJS Stack install folder tests_and_samples to /var/www/html on your server.

Configure The SplunkJS Stack

Edit /var/www/html/test_cors.html and update the following code block to reflect your envrionment.

require.config({baseUrl: "../static/"});
    splunkjs.config({
        scheme: 'https',
        host: 'mysplunkserver',
        port: 8089,
        authenticate: {username: 'admin', password: 'mychangedpassword' }  
    });

Test The Example

Visit http://myserver/test_cors.html to to validate CORS authentication is working. You may need to add a security exception to your browser in order to get it to work. If you run into issues, try accessing your Splunk server and adding a security exception by pasting the following URL in your browser.

https://mysplunkserver:8089/services/auth/login?output_mode=json

If all is working you should see the following.

That’s it for this post. I’ll update this blog post with links to parts 2 & 3 when they are finished.