restmap.conf

# This file contains possible attribute and value pairs for creating new rest endpoints.

# There is a restmap.conf in $SPLUNK_HOME/etc/bundles/default/.  To set custom configurations, 
# place a restmap.conf in your own custom bundle directory.
#
# For help creating a bundle directory, or to learn more about bundles (including bundle precedence)
# please see the documentation located at http://www.splunk.com/doc/latest/admin/bundleconfig.

# NOTE: Every rest endpoint in splunkd must be registered here or it will never become available.

###########################
# Global stanza

[global]
    * This stanza must preface any global options. 
      * Follow this stanza name with any number of the following attribute/value pairs.

allowGetAuth=<true | false>
    * Allow user/password to be passed as a get param to endpoint /auth/login.  
    * Posting get argumets might get logged, and setting this to true, while convenient, may 
    result in user/password getting logged as cleartext in splunk's logs *and* any proxy servers
    in between. 
    * Defaults to false.  

pythonHandlerPath=<path to 'main' python script handler>
    * Used by the script handler to determine where the actual 'main' script is located.  
    * Typically, you should not need to change this.

###########################
# Per-endpoint stanzas

  
# The handler is responsible for implementing any arbitrary namespace underneath this base REST 
# endpoint. 
# For example, if I register /foo, my handler may implement /foo/a, /foo/b, /foo/x/y/z, ...
# -- anything underneath the endpoint.

[Handler:uniqueName]
    # Stanza definitions are broken down into 2 parts - the handler and a unique name.    
    * There are 2 types of handlers available:
    [script:<name>] and [search:<name>]
        * See below for handler-specific attribute/value pairs.
    * Internal Splunk developers that wish to implement a REST handler in C++ must take NOT to
    name their service 'script', 'search', or 'map'.
    * 3rd party developers can ONLY use the handlers 'script' and 'search'.
    * NOTE: You can have as many endpoints per handler as you wish as long as the uniqueName is
    different for each one.
    * The following attribute/value pairs can be used in *any* stanza.
    
match=<regex>
    * This determines the URL endpoint that will call this handler. 
    * For instance if 'match=/foo', then https://machinename:portno/services/foo calls this handler.  
    * NOTE: All matches are anchored at the beginning of the line - eg a '^' character is 
    automatically appended to the beginning of the regex.

requireAuthentication={true | false} (optional - defaults to true)
    * This OPTIONAL tag determines if this endpoint requires authentication or not.  
    * It defaults to 'true'.

capability=<capabilityName>
capability.<post|delete|get|put>=<capabilityName>
    * Depending on the HTTP method, a capability check is done on the session user that 
    previously authenticated. 
    * If you use 'capability.post|delete|get|put,' then the associated capability is checked 
    against the authenticated users's role. 
    * If you just use 'capability,' then all calls get checked against this capability (regardless 
    of the HTTP method).

xsl=<path to XSL transform file>
    * THIS IS OPTIONAL.
    * Perform an optional XSL transform on data returned from the handler.
    * Only use this if the data is XML.

#
# The following attribute/value pairs are specific to handler type:
#

############################
#'script'
# The built-in script handler. 
# Call the speficied script when executing this endpoint.
#

[script:<uniqueName>]

scripttype=python | perl | ruby | php 
    * Tell the system what type of script to execute when using this endpoint.
    * NOTE: As of 11/27, only python is supported.
    
handler=ScriptFile.ClassName
    * The name and class name of the file to execute.  
    * The file *must* live in a bundle's subdirectory named 'rest'.  
    * For example $SPLUNK_HOME/etc/bundles/local/rest might contain a file called TestHandler.py 
    with a class called MyHandler (which, in the case of python must be derived from a base class 
    called 'splunk.rest.BaseRestHandler').  
    * The tag/value pair for this would look like: "handler=TestHandler.MyHandler".

script=<path to a script executable>
    * This is optional and rarely used.
    * Optionally you can execute a script which is *not* derived from 'splunk.rest.BaseRestHandler'.
    * Put the path to that script here.  
    * Do not use this unless you absolutely have to!

#############################
#'search'
# The built-in handler for executing an arbitrary search. 
# Execute the specified search when this endpoint is executed.
#

[search:<uniqueName>]

match=<regex with groups>
     * Even though 'match' is specified above as available in any stanza, it is specially used here.  
    * Any regex match group is applied to the 'searchstring' value.  
    * So, the first '(..)' gets substituted in \1 and the second '(...)' gets substituted in \2, etc.

searchstring=search string \1 \2 \3
    * Any arbitrary Splunk search.  
    * See 'match' just above for how substitution occurs.

# This file contains example REST endpoint configurations.
#
# To use one or more of these configurations, copy the configuration block into
# restmap.conf in your own custom bundle.
#
# For help creating a bundle directory, or to learn more about bundles (including bundle precedence)
# please see the documentation located at http://www.splunk.com/doc/latest/admin/bundleconfig.

# The following are default REST configurations.  To create your own endpoints, modify 
# the values by following the spec outlined in restmap.conf.spec.

# /////////////////////////////////////////////////////////////////////////////
#  global settings
# /////////////////////////////////////////////////////////////////////////////

[global]

# indicates if auths are allowed via GET params
allowGetAuth=false

#The default handler (assuming that we have PYTHONPATH set)
pythonHandlerPath=$SPLUNK_HOME/bin/rest_handler.py

# /////////////////////////////////////////////////////////////////////////////
#  internal C++ handlers
# NOTE: These are interal Splunk-created endpoints.  3rd party developers can only use script or
# search can be used as handlers.  (Please see restmap.conf.spec for help with configurations.)
# /////////////////////////////////////////////////////////////////////////////

[streams:livetail]
match=/streams
capability=allow_livetail

[SBA:sba]
match=/properties
capability=get_property_map

[asyncsearch:asyncsearch]
match=/search
capability=search