App Server Utilities

Important notice: As part of Advanced XML deprecation, the Module System is officially deprecated beginning with Splunk Enterprise 6.3. For more information, see Advanced XML Deprecation.

check_restart_required()

The check_restart_required() function indicates if splunkd raised the restart flag as a result of configuration changes. Use this function to detect if changes made by a controller require a splunkd restart to be enabled.

Synopsis

restartF = check_restart_required()

Return Value

String

Restart flag status: True = Restart required flag is set. False = Restart required flag is reset.

Example

from splunk.appserver.mrsparkle.lib import util

template_args = {

   ... elided ...
   'requires_restart': util.check_restart_required()

}

return self.render_template('/licensing/self.html', template_args)

convert_to_bytes()

The convert_to_bytes() function converts byte string value notation, containing a size specification, to an integer or float value, using base-2 computation.

Synopsis

numericValue = convert_to_bytes(byteValue)

Parameters

byteValue

String

Byte string value with one of the following unit specifications: YB ZB EB PB TB GB MB KB YiB ZiB EiB PiB TiB GiB MiB KiB B Format specification examples: 10MB 1.4 GB 1000 YiB 1000YB Note that the value may not contain a thousands separator comma, and uses a period (.) to denote decimal. Examples: convert_to_bytes('10MB') returns 102400000 convert_to_bytes('40 GB') returns 42949672960 convert_to_bytes('300') returns 300

Return Value

Integer/Float

Integer or float representation of byteValue.

Exceptions

ValueError	'unrecognized units: %s' % units
ValueError	'cannot convert to bytes: %s' % byteValue

Example

from splunk.appserver.mrsparkle.lib import util

byteVal = '10000PB' try:

   bytes = util.convert_to_bytes(byteVal)

except:

   pass

current_url_path()

The current_url_path() convenience function returns the current URL path. Optionally, the query string can be included, specifying include_qs, and is encoded so it can be used safely in an HTML page.

Typical usage includes a controller using the current path in a redirection or similar operation.

Synopsis

urlPath = current_url_path( include_qs )

Parameters

include_qs

String

Include query string flag: True = Include query string. (Default) False = Do not include query string.

Return Value

String

Current URL path, including query string as specified by include_qs.

Example

import cherrypyfrom splunk.appserver.mrsparkle.lib import util

path = util.current_url_path(include_qs=False) raise cherrypy.HTTPRedirect(path, '303')

deep_update_dict()

The deep_update_dict() function recursively updates a dictionary with another dictionary. Dictionary key values in the original dictionary are recursively merged with an overlay dictionary, if it exists.

Note: The original dictionary is modified by this function.

Synopsis

newDict = deep_update_dict( original, overlay )

Parameters

original	Object	Original dictionary.
overlay	Object	Dictionary to overlay on the original dictionary.

Return Value

Object

The original dictionary overlayed with the overlay dictionary.

Example

from splunk.appserver.mrsparkle.lib import util

... elided ...

@route('/:namespace/*endpoint_base/:element=_element/:element_name', methods=['POST','GET']) @expose_page(must_login=True) def fetch_element(self, namespace, endpoint_base, element, element_name,

                   form_defaults=None, element_overlay=None, entity_name=None, eai_attributes=None):
   ... elided ...
   element = copy.deepcopy(uiHelper_flatten[element_name])
   util.deep_update_dict(element, element_overlay)
   ... elided ...

get_active_controller()

The get_active_controller() convenience function returns the controller class of the current request handler. This wraps a CherryPy request handler object and can be used to identify the active controller, for logging or debugging.

Synopsis

name = get_active_controller()

Return Value

String

Current request handler controller class name.

Example

from splunk.appserver.mrsparkle.lib import util

logger = logging.getLogger('splunk.appserver.mrsparkle.controller_test') controller = util.get_active_controller()

logger.debug('controller=%s' % controller)

get_apps_dir()

The get_apps_dir() function gets the current root applications directory path name.

Synopsis

path = get_apps_dir()

Return Value

String

Current root applications directory path name.

Example

import osfrom splunk.appserver.mrsparkle.lib import util

apps_list = os.listdir(util.get_apps_dir())

get_time()

The get_time() function returns a time structure. Given specified time units and values for hours, minutes, seconds, and microseconds,

Note: This function permits you to provide a number beyond the bounds of a typical Python Time object and returns values that can then be used to instantiate a Python Time object.

Synopsis

results = get_time( hours, minutes, seconds, microseconds)

Parameters

hours	Float	Number of hours (default = 0 ).
minutes	Float	Number of minutes (default = 0 ).
seconds	Float	Number of seconds (default = 0 ).
microseconds	Float	Number of microseconds (default = 0 ).

Return Value

Struct{Float}

Formatted time in the form {year, days, hours, minutes, seconds}. Example: Calling get_time(seconds=600) returns { 0.0, 0.0, 0.0, 10.0, 0.0 }.

Example

from splunk.appserver.mrsparkle.lib import util

my_time = util.get_time(seconds=86400)

in_sso_mode()

The in_sso_mode() function indicates if Splunk is operating in trusted authority, Single Sign-on (SSO), mode.

Synopsis

ssoMode = in_sso_mode()

Return Value

Boolean

Indicates if Splunk is operating in trusted authority mode: True = In trusted authority mode. False = Not in trusted authority mode.

Example

from splunk.appserver.mrsparkle.lib import util

   ... elided ...

def validate_ip(fn, self, *a, **kw):

   if util.in_sso_mode():
       ... elided ...

is_api()

The is_api() function indicates if the current request was made to the /api endpoint.

Synopsis

results = is_api()

Return Value

Boolean

Current request made to /api endpoint flag: True = Current request was made to the /api endpoint. False = Current request was not made to the /api endpoint.

Example

from splunk.appserver.mrsparkle.lib import util

   ... elided ...

def check(fn, self, *a, **kw):

   is_api = util.is_api()
   if (is_api):
       ... elided ...
   else
       ... elided ...

is_ie()

The is_ie() function indicates whether or not the Internet Explorer browser was detected in the requesting user agent.

Synopsis

results = is_ie()

Return Value

Boolean

Internet Explorer browser detected indication: True = Browser is Internet Explorer. False = Browser is not Internet Explorer.

Example

from splunk.appserver.mrsparkle.lib import util

if util.is_ie():

   ... elided ...

else

   ... elided ...

is_valid_cherrypy_session_id()

The is_valid_cherrypy_session_id() function indicates whether or not the specified token is equivalent to the Splunk session token stored in the CherryPy session.

The @expose_page decorator, uses this function as part of CSRF protection on POST requests.

Synopsis

tokenIdF = is_valid_cherrypy_session_id( token )

Parameters

token

String

Token to compare to the Splunk session token.

Return Value

Boolean

Token matches Splunk session token indication: True = The token is equivalent to the Splunk session token. False = The token is not equivalent to the Splunk session token.

Example

def expose_page(must_login=True, handle_api=False, methods=None, verify_session=True, verify_sso=True, trim_spaces=False):

   @decorator
   def check(fn, self, *a, **kw):
       is_api = util.is_api()
       request = cherrypy.request

           ... elided ...

       if verify_session and request.method == 'POST' and not cherrypy.config.get('environment') == 'test_suite':
       is_xhr = util.is_xhr()
       session_id =  request.headers.get('X-Splunk-Session') if is_xhr else request.params.get('splunk_session_id')

       if not util.is_valid_cherrypy_session_id(session_id):
           if is_xhr:
               logger.warn('CSRF: validation failed because client XHR did not include proper header')
           else:
               logger.warn('CSRF: validation failed because HTTP POST did not include expected parameter')

       ... elided ...

is_xhr()

The is_xhr() function indicates if the current request is an XMLHttpRequest request. A request is an XMLHttpRequest request if the X-Requested-With request Header is set to XMLHttpRequest. The @expose_page decorator, uses this function for CSRF protection on XMLHttpRequest POST requests.

Synopsis

results = is_xhr()

Return Value

Boolean

Current request is XMLHttpRequest indication: True = Current request is an XMLHttpRequest request. False = Current request is not an XMLHttpRequest request.

Example

def expose_page(must_login=True, handle_api=False, methods=None, verify_session=True, verify_sso=True, trim_spaces=False):

   @decorator
   def check(fn, self, *a, **kw):
       is_api = util.is_api()
       request = cherrypy.request

       ... elided ...

       if verify_session and request.method == 'POST' and not cherrypy.config.get('environment') == 'test_suite':
           is_xhr = util.is_xhr()
           session_id = request.headers.get('X-Splunk-Session') if is_xhr else request.params.get('splunk_session_id')
       if not util.is_valid_cherrypy_session_id(session_id):
       if is_xhr:
           logger.warn('CSRF: validation failed because client XHR did not include proper header')
       else:
           logger.warn('CSRF: validation failed because HTTP POST did not include expected parameter')

       ... elided ...

isEpochTimeArg()

The isEpochTimeArg() function indicates if the specified time can be converted to a float datatype.

Synopsis

results = isEpochTimeArg( time )

Parameters

time

String

Time value.

Return Value

Boolean

Indication if time can be converted to a float datatype: True = time can be converted to float. False = time cannot be converted to float.

Raises

ValueError,TypeError

Value cannot be converted to float datatype.

Example

from splunk.appserver.mrsparkle.lib import util

   ... elided ...

def setTime(earliest, latest):

   if (earliest) :
       if (isEpochTimeArg(earliest)):
           ... elided ...
       else
           ... elided ...

layPiping()

The layPiping() convenience function returns the specified search string, beginning with a pipe ( ) symbol if it does not already begin with the term search.

Synopsis

searchString = layPiping( q )

Parameters

q

String

Qualified search string to be piped.

Return Value

String

Search string, q , piped as required.

Example

from splunk.appserver.mrsparkle.lib import util

   q = 'search index=_internal
   r = util.layPiping(q)

make_absolute()

The make_absolute() function converts the specified partial or relative path to an absolute path within the Splunk path hierarchy.

Synopsis

fullpath = make_absolute(fn, postfix, basedir)

Parameters

fn	String	Partial or relative path to be converted.
postfix	String	[Optional] String to be inserted between the path route and fn.
basedir	String	[Optional] Base directory to use instead of SPLUNK_HOME (Default = SPLUNK_HOME ).

Return Value

String

The specified fn path expressed as an absolute path.

Exceptions

TBD

Example

import osfrom splunk.appserver.mrsparkle.lib import util

SPLUNK_HOME = os.environ['SPLUNK_HOME'] path = '/etc/apps/search' fullpath = util.make_absolute(path)

make_url

The make_url() function returns a URL for the specified path.

The method builds a URL from a relative or absolute URL with optional query string. A relative URL is returned, if relative is set to True, otherwise, an absolute URL is returned. The string /splunk or the configuration root_path is prefixed to the URL unless translate is set to False.

Static paths are constructed with an embedded cache defeater segment :

/static/@<build_number>[.<push_number>]/

This results in static paths like the following example:

/static/@12345/js/foo/static/@12345.1/js/foo

Static assets for apps have an additional cache defeater number correlating to the application build number as defined in the app.conf file:

/static/@12345.1:2/app/unix/static/foo.png

The URL handler in root.py strips out any requests having this schema.

Synopsis

targURL = make_url(target, _qs=None, translate=True, relative=False, __app_cache={})

Parameters

target	String
_qs	Object	Query string as a list of tuples or a dictionary. Example: _qs=[('q', 'search val to quote')] (Default = None )
translate	Boolean	Prefix the application server root path flag: True = Prefix root path (Default). False = Do not prefix root path.
relative	Boolean	Relative returned path indication: True = Returned targetURL is relative. False = Returned targetURL is absolute (Default)

Return Value

String

The specified target as a full URL.

Raises

InvalidURLException	"Illegal characters in URL"
ValueError	'Illegal escape from parent directory "%s": %s' %(basepath, fullpath)

Example

from splunk.appserver.mrsparkle.lib import util

targetURL = '/en-US/api/search/jobs?job=1234&action=delete' example1URL = util.make_url('/api/search/jobs', job=1234, action=delete) example2URL = util.make_url('/api/search/jobs, _qs=dict(job=1234,action=delete))

See Also

strip_url()
url_has_valid_charset()

normalize_value()

The normalize_value () function converts a string to either an integer or boolean value. If value cannot be cast to an integer the function tries to convert the string to boolean.

Synopsis

normValue = normalize_value( value )

Parameters

value

String

Value to be converted to integer or boolean.

Return Value

Integer or Boolean

Converted value.

Raises

ValueError

The specified value could not be converted to an integer or boolean value.

Example

from splunk.appserver.mrsparkle.lib import util

intVal = util.normalize_value('42') boolVal = util.normalize_value('false')

push_version()

The push_version() method gets the current application push_version value.

The push_version variable is a local-to-installed-instance version number, which is combined with the build number to revise static resources in  %SPLUNK_HOME/etc/apps/<appName>/appserver/static. This number is incremented by a POST to /_bump, forcing the client to fetch the new version of any modified resource, regardless of the Expires headers that were sent with it.

Synopsis

push_version = push_version()

Return Value

String

Current push_version value.

Example

from splunk.appserver.mrsparkle.lib import util

def incr_push_version(self):

   new_version = cherrypy.config['_push_version'] = util.push_version() + 1 
   f = open(util.make_absolute('var/run/splunk/push-version.txt'), 'w')
   f.write(str(new_version))
   f.close()
   return new_version

restart_splunk()

The restart_splunk() function restarts the Splunk splunkd and splunkweb processes.

Synopsis

results = restart_splunk()

Return Value

Undefined

Raises

SplunkRestartException

Error encountered restarting Splunk.

Example

from splunk.appserver.mrsparkle.lib import util

util.restart_splunk()

set_cache_level()

The set_cache_level() function sets the HTTP caching headers to a preset configuration.

Synopsis

results = set_cache_level( cache_level, response)

Parameters

cache_level	String	Cache level literal: never = Explicitly defeat client-side caching. etag = Apply an ETag header by MD5 hashing the body. always = Set max caching.
response	String	Deprecated

Return Value

Undefined

Raises

ValueError

'Unrecognized cache level: %s' % cache_level

Example

from splunk.appserver.mrsparkle.lib import util

def renderExample():

   try:
       pageContent = '<p>Sample Content</p>'
   except Exception, e:
       pageContent = '<p class="moduleException"></p>'
   if cherrypy.response.headers.get('Cache-Control') == None:
       return util.set_cache_level('etag', pageContent)
   return pageContent

strip_url()

The strip_url() function returns a URL, stripping the path root endpoint and i18n prefixes. Call this function when intending to pass a pathname fragment to methods, such as make_url(), that can safely handle the root endpoint and i18n prefixes.

Synopsis

stripPath = strip_url( path )

Parameters

path

String

Pathname to be stripped.

Return Value

String

Pathname with the root endpoint and i18n prefixes stripped.

Example

from splunk.appserver.mrsparkle.lib import util

util.strip_url('/en-US/app/search/foo') util.strip_url('http://localhost:8000/en-GB/app/launcher/home')

See Also

make_url()
url_has_valid_charset()

url_has_valid_charset()

The url_has_valid_charset() function validates the URL character set against RFC 3986.

Synopsis

results = url_has_valid_charset(url)

Parameters

url

String

URL to be validated.

Return Value

Boolean

Valid URL indication: True = The url is valid. False = The url is invalid.

Example

from splunk.appserver.mrsparkle.lib import util

if (util.url_has_valid_charset('http://localhost:8000/en-US/account/login'))

   ... valid URL ...

else

   ... invalid URL ...

See Also

make_url()
strip_url()