Accessing Splunk resources
Splunk's layering of resources
Splunk takes a layering approach for access to resources. This layering approach is necessary to account for permissions to view apps, system files, and other resources by users throughout a Splunk installation.
Splunk implements this layering approach through configuration files and an order of precedence that determines access to the resources defined therein.
Splunk REST API endpoints, as described later in this section, provide access to resources based on this layering approach. This is important when viewing, creating, updating, or deleting resources to make sure you are accessing the correct resources for a user's namespace.
For details on Splunk configuration, refer to the Splunk Admin manual, specifically the sections:
Search-time resources (Splunk objects)
Generally speaking, resources that affect search activities have an app/user context. The app/user context defines a namespace that is accessible from the servicesNS endpoints, as described in servicesNS endpoints. Search-time resources are considered objects within a Splunk system.
The order or precedence in the app/user context is:
- Settings specific to a user
- Settings specific to the current app
- Settings globally-visible from other apps
- System-wide settings
This layering enables users access to not only resources specific to them but also to apps and system-wide settings.
The order of precedence also accounts for different resources with the same name. For example, a user can have a saved search with the same name as a saved search at the system level.
Examples of search-time resources include:
- /saved/searches (saved searches)
- /data/props/extractions (field extractions)
Index-time resources (Splunk configurations)
For some resources there is no user/app context. These are resources that affect data input, indexing, or deployment activities. Index-time resources are considered configurations in a Splunk system. These resources are available from namespace endpoints as described in servicesNS endpoints.
For index-time resources, the order of precedence is:
- Local system settings
- Settings for all apps
- Default system settings
Because there is no user/app context, user-specific settings are ignored. Access to resources is based on the capabilities defined in the Splunk-defined role for a user. For example, /data/inputs/monitor looks the same to all users who have access to the resource. Access is based on a user's Splunk role.
Examples of these resources include:
- /data/indexes (indexes)
- /data/inputs/monitors (monitor inputs)
When using the Splunk REST API, use the namespace (
/servicesNS/* endpoints) to ensure that you specify the correct user/app context for the resource:
https://<Splunk server>:<management port>/servicesNS/<user>/<app>/*
<nobody> - For shared application resources, specify nobody for <user>.
wildcards - To specify all users or all apps, use the wildcard, '-'. For example:
.../servicesNS/-/-/saved/searches. When using a wildcard for all users, this includes shared application resources accessible by all users.
For example, from the Splunk default management port, the following GET operation returns saved searches accessible by the admin user from within the search app context. It does not, however, list saved searches private to the admin user in another app, such as the launcher app.
curl -k -u admin:pass https://localhost:8089/servicesNS/admin/search/saved/searches
For index-time resources, access through the Splunk REST API is also through a user/app context. For example, the following POST operation creates an index within the context of the search app:
curl -k -u admin:pass https://localhost:8089/servicesNS/nobody/search/data/indexes \ -d name=Shadow
Here, Splunk uses the user "nobody" to indicate that there is no specific user for this context. The search app is accessible by all users.
Access is through the Splunk admin user credentials. A user must be a member of the admin role, which has the capabiities to create and edit indexes, to perform this operation.
admin (services) endpoints
Splunk resources can also be accessed through the services endpoints:
https://<Splunk server>:<management port>/services/*
When processing a request to a
services/* endpoint, Splunk processes the request using the user/app context of the current user. So the following GET operations are equivalent:
curl -k -u <user>:<pw> https://localhost:8089/services/saved/searches curl -k -u <user>:<pw> https://localhost:8089/servicesNS/<user>/<default app>/saved/searches
Note: Splunk recommends that you use the servicesNS endpoints, especially for create, update, and delete operations. Using the servicesNS endpoints ensures that you are accessing resources using the correct user/app context.
Thus the following GET operations for returning saved searches are equivalent:
curl -k -u admin:pass https://localhost:8089/services/saved/searches curl -k -u admin:pass https://localhost:8089/servicesNS/admin/search/saved/searches
Access control lists for Splunk objects
As discussed in Splunk's layering of resources, Splunk uses a user/app/ context to define namespaces for resources. There is an access control list associated with this context that enforces ownership and permissions for access to the resources. The following table lists the acl properties for Splunk resources.
Note: The acl properties listed here are typically used when developing Splunk applications. Some acl properties, such as can_share_app and modifiable, are reserved for internal use.
|app|| The app context for the resource. Allowed values are:
|can_list||For internal use only for the Splunk Web manager UI.|
|can_share_*|| Indicates whether the current user can change the entity's sharing state. The sharing state can be app, global, or private.
|can_write||Indicates if the current user can edit this item.|
|owner|| The user that owns the resource.
"nobody" means that all users have access to the resource. However, write access to the resource might be restricted.
|modifiable|| Indicates if the access control list (ACL) is modifiable.
modifiable is set to false for items not controlled by ACLs, such as items under /server/logger.
|perms.read||Properties that indicate read permissions of the resource.|
|perms.write||Properties that indicate write permissions of the resource.|
|removable||Indicates if an admin or user with necessary permissions can remove the entity.|
|sharing|| Indicates how the resource is shared. Allowed values are:
Splunk REST API actions for managing acl properties
Many of the Splunk REST API endpoints can invoke actions that allow you to access and modify access control list (acl) properties of objects. The following actions are available:
/aclto an endpoint to access acl properties. Provide parameters to this action to make modifications.
/moveto an endpoint to change the app context of a resource.
List the acl properties of a saved search:
curl -k -u admin:pass https://localhost:8089/servicesNS/admin/search/saved/searches/Indexing%20workload/acl
<s:key name="eai:acl"> <s:dict> <s:key name="app">search</s:key> <s:key name="can_change_perms">1</s:key> <s:key name="can_list">1</s:key> <s:key name="can_share_app">1</s:key> <s:key name="can_share_global">1</s:key> <s:key name="can_share_user">0</s:key> <s:key name="can_write">1</s:key> <s:key name="modifiable">1</s:key> <s:key name="owner">nobody</s:key> <s:key name="perms"> <s:dict> <s:key name="read"> <s:list> <s:item>admin</s:item> </s:list> </s:key> <s:key name="write"> <s:list> <s:item>admin</s:item> </s:list> </s:key> </s:dict> </s:key> <s:key name="removable">0</s:key> <s:key name="sharing">app</s:key> </s:dict> </s:key>
Share an object to an app and modify its permissions:
The admin user specifies Alice as the owner of the saved search, grants all users read permissions to the saved search, and makes the saved search accessible through the app, myapp.
curl -k -u admin:pass https://localhost:8089/servicesNS/alice/myapp/saved/searches/mysearch/acl \ -d owner=alice \ -d perms.read=* \ -d sharing=app
Change the app/user context of an object:
Make the saved search accessible to all users and change the context to a different app.
curl -k -u admin:pass https://localhost:8089/servicesNS/nobody/myapp/saved/searches/mysearch/move \ -d user=nobody \ -d app=otherapp
Other actions for Splunk REST API endpoints
The following actions are also available for Splunk REST API endpoints:
Enable or disable endpoints
/disable to an endpoint, and invoke the endpoint as a POST operation.
Note: Many endpoints also provide a
disabled parameter that allows you to enable or disable the endpoint.
For example, to disable a search job:
curl -k -u admin:pass https://localhost:8089/servicesNS/admin/search/saved/searches/TestSearch/ \ disable -X POST
Reload an endpoint
_reload to an endpoint to force the Splunk server to reload data for the endpoint.
You cannot specify this action for a specific object, such as a specific saved search. Rather, you specify this action for all saved searches.
curl -k -u admin:pass https://localhost:8089/servicesNS/admin/search/saved/searches/_reload
Splunk responses to REST operations
Accessing and updating Splunk configurations
This documentation applies to the following versions of Splunk® Enterprise: 5.0, 5.0.1, 5.0.2, 5.0.3, 5.0.4, 5.0.5, 5.0.6, 5.0.7, 5.0.8, 5.0.9, 5.0.10, 5.0.11, 5.0.12, 5.0.13, 5.0.14, 5.0.15, 5.0.16, 5.0.17, 5.0.18