Splunk® Enterprise

REST API Reference Manual

Download manual as PDF

Splunk Enterprise version 5.0 reached its End of Life on December 1, 2017. Please see the migration information.
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

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)

servicesNS endpoints

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.

Search-time resources

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

Index-time resources

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.

acl Property Description
app The app context for the resource. Allowed values are:
The name of an app
system
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.

Applies to:

can_share_app
can_share_global
can_share_user
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:
app: Shared through an app.
global: Shared to all apps.
user: Private to a specific user.



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:

  • Append /acl to an endpoint to access acl properties. Provide parameters to this action to make modifications.
  • Append /move to 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

The response:

<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

Append /enable or /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

Append _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
PREVIOUS
Splunk responses to REST operations
  NEXT
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


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters