• Overview
  • Introduction and overview
    • Components
    • Appearance
    • REST API
    • Applications
    • Help
• Architecture
  • Components
    • Processes
    • Configuration files
• Splunk Web appearance
  • How Splunk Uses Skins
    • Skins css Files
    • Images/skins directory
  • Add or remove themes
    • Create a new skin
    • Example
  • Dashboard customization
    • Configuration
    • List modules
    • Add search modules
    • Add html modules
    • Link dashboard to user
• REST API
  • Splunk's REST API
    • Using REST Methods
    • Splunk REST endpoint mappings
    • HTTP ports Splunk uses
    • Examples
  • Get started
    • Send a request
    • Get a response
  • Output formats via XML
    • Example Generic Response
    • Example Generic Response with Messaging
    • Generic Response with Messaging (via error codes)
    • Example Atom Feed Response
    • Example Atom Feed with Messaging
    • Example Atom Entry Response
  • SDKs
    • Python SDK
  • Create a custom endpoint
    • Make a custom application directory
    • Write a handler script
    • Configure restmap.conf
    • Restrict endpoint access
    • Add supporting configuration files
• Auth
  • Authentication Endpoint
    • Login
  • Authentication examples
    • Command Line
    • Python SDK
    • Other Python example
• Properties
  • Properties Endpoint
    • Properties
    • $FILE_NAME
    • $STANZA_NAME
    • $KEY_NAME
    • PropertiesNS
  • Configuration file access with Python
    • Configuration
    • Example
• Search
  • Search Overview
    • Handling Search Results
    • Result Formats
  • Search Endpoint
    • Jobs
    • Search ID
    • Events
    • Results
    • Timeline
    • Summary
    • Control
  • Search with the Python SDK
    • Create a search
    • Work with search results
    • Examples
  • Custom search scripts
    • Configuration files
    • Working with results
    • Authenticate
    • Example
• Saved
  • Saved Endpoint
    • Searches
    • $SAVED_SEARCH_NAME
• Streams
  • Streams Endpoint
    • Search
    • Livetail
• Applications
  • Developer applications overview
  • Applications Endpoint
    • Local
    • $APP_NAME
    • Remote Entries
    • Remote $APP_NAME
    • Category Path
    • Remote Login
• SplunkBase
  • SplunkBase API
    • Apps
    • Types
    • Category Path
    • Entries
    • App Name
• Legacy
  • Legacy methods
    • $LEGACY_METHOD_NAME

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/.