Create a custom endpoint

Create a custom endpoint

If there is some functionality Splunk's REST API doesn't provide you with, you may want to add your own endpoint. Use the endpoint to expose Splunk's functionality via the REST API. Your endpoint can support GET, POST, DELETE, VIEW and/or PUT.

There are examples in $SPLUNK_HOME/etc/apps/samples/. Also, see the WebSkunk example on the Splunk Dev Wiki.

To create your own endpoint, follow these steps:

1. Make a custom application directory.

2. Write a handler script.

3. Configure restmap.conf.

4. Optionally restrict endpoint access.

5. Optionally add any supporting configuration files.

Make a custom application directory

1. Make a directory in $SPLUNK_HOME/etc/apps/ for your application.

• For example, $SPLUNK_HOME/etc/apps/<APPNAME>/.

2. Add the following subdirectories:

• bin/
  • Use this for scripts.
  • You can add a web/ directory in bin/ for any html files you want your endpoint to serve up.
• default/
  • Add any configuration files, such as restmap.conf.
  • Add any supporting configuration files (see below).
• local/
  • Optionally add this directory if you are distributing this application.
  • You, or other people configuring your application, can use this directory to overwrite configurations from default/.

Write a handler script

The handler script handles any http request to your endpoint.

1. Write a handler script using Python.

• Note: Currently, Python is the only supported language for writing a handler script.

2. Put your handler script in $SPLUNK_HOME/etc/apps/<APPNAME>/bin/.

Example

The following example lives in $SPLUNK_HOME/etc/apps/samples/bin/samplehandlers.py:

# this is a required import
import splunk.rest
# use the default splunk logger -> splunk/var/log/splunk/python.log
import logging as logger
# contains the services for read/write to bundle system
import splunk.bundle as bundle
class HelloWorld(splunk.rest.BaseRestHandler):
        def handle_GET(self):
                self.response.write('Hello World!')

Configure restmap.conf

You must also add a stanza for your endpoint in restmap.conf.

1. Add restmap.conf to $SPLUNK_HOME/etc/apps/<APPNAME>/default/.

2. Add a script stanza to restmap.conf.

[script:<uniquename>]
match = <path>
handler = <SCRIPT>.<CLASSNAME>

• [script:<unique name>]
  • The unique name must be different for each handler.
• match=<path>
  • Specify the URI that calls the handler.
  • For instance if match=/foo, then https://$SERVER:$PORT/services/foo calls this handler.
  • You must start your path with a /.
• handler = <SCRIPT>.<CLASSNAME>
  • The name and class name of the handler script to execute.
  • The file *must* live in an application's subdirectory named 'rest/'.
  • For example, $SPLUNK_HOME/etc/apps/<APPNAME>default/rest/TestHandler.py has a class called MyHandler.
  • The attribute/value pair for this is: handler=TestHandler.MyHandler

This creates an endpoint at https://localhost:8089/services/<match> (or whatever your Splunk server and port are).

Example

The handler registers in Splunk via $SPLUNK_HOME/etc/apps/samples/default/restmap.conf:

[script:samples.HelloWorld]
match = /samples/helloworld
handler = samplehandlers.HelloWorld 

You can navigate to this endpoint at https://$YOUR_SERVER:$PORT/services/samples/helloworld or use the following curl command:

curl -k -H "$SPLUNK_AUTH_HEADER" "$SPLUNK_URL/samples/helloworld/"

Restrict endpoint access

You can disallow/allow admins to use your newly created endpoint by adding to your stanza in restmap.conf.

1. Add the capability and requireAuthentication attributes to restmap.conf:

[script:samples.HelloWorld]
match = /samples/helloworld
handler = samplehandlers.HelloWorld 
requireAuthentication = true
capability = helloworld

2. Create authorize.conf under your application's default folder $SPLUNK_HOME/etc/apps/<APPNAME>/default/.

3. Enable your endpoint for admin role in authorize.conf:

[role_Admin]
helloworld = enabled

4. Restart splunk to apply changes.

The now secure endpoint is located at https://$YOUR_SERVER:$PORT/services/samples/HelloWorld.

Add supporting configuration files

After you've configure your endpoint, you may also need to add additional configuration files to support your configuration. For example, if you've configured an endpoint that inputs data, you may need to add inputs.conf. To secure your endpoint, you need to add authorize.conf.

Add all supporting configuration files to $SPLUNK_HOME/etc/apps/<APPNAME>/default/. Application end users can make changes to configuration files in $SPLUNK_HOME/etc/apps/<APPNAME>/local/.