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
Templates |
This documentation applies to the following versions of Splunk® Enterprise: 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.7, 7.3.8, 7.3.9
Feedback submitted, thanks!