Splunk® Enterprise

REST API Reference Manual

Acrobat logo Download manual as PDF


This documentation does not apply to the most recent version of Splunk® Enterprise. For documentation on the most recent version, go to the latest release.
Acrobat logo Download topic as PDF

Federated search endpoint descriptions

Use the federated search REST API endpoints to create, update, and delete definitions for federated providers and federated indexes.

See About federated search for more information.

Usage details

Review ACL information for an endpoint

To check Access Control List (ACL) properties for an endpoint, append /acl to the path. For more information see Access Control List in the REST API User Manual.

Authentication and Authorization

Username and password authentication are required for access to endpoints and REST operations.

Splunk users must have role and/or capability-based authorization to use REST endpoints, and must have the admin_all_objects and edit_indexes capabilities to use the federated search endpoints detailed in this topic.

Users with an administrative role, such as admin, can access authorization information in Splunk Web. To view the roles assigned to a user, select Settings > Access controls > Users. To determine the capabilities assigned to a role, select Settings > Access controls > Roles.

Splunk Cloud Platform URL for REST API access

Splunk Cloud Platform has a different host and management port syntax than Splunk Enterprise. Paid subscribers to the Splunk Cloud Platform service use the following URL to access REST API resources:

https://<deployment-name>.splunkcloud.com:8089

See Access requirements and limitations for the Splunk Cloud Platform REST API in the the REST API Tutorials manual for more information.


data/federated/settings/general

https://<host>:<mPort>/services/data/federated/settings/general

Use this endpoint to review the current general federated search settings for your Splunk platform deployment and change those settings as necessary. For an overview of federated search, see About federated search in the Search Manual.

Authentication and authorization
Use of the GET and POST operations for this endpoint is restricted to roles that have the admin_all_objects and indexes_edit capabilities.

GET

Provides the current general federated search settings for your Splunk platform deployment.

Request parameters
None specific to this method. This method can use pagination and filtering parameters.

Returned values

Name Description
disabled Specifies whether federated search functionality is turned on for your Splunk platform deployment.

If disabled = false, federated search functionality is turned on for your deployment. If disabled = true, federated search functionality is turned off for your deployment.

Defaults to false.

transparent_mode Specifies whether transparent mode federated search functionality is turned on for your Splunk platform deployment.

If set to true, transparent mode is turned on, which means federated search users on your deployment can run federated searches over transparent mode federated providers as well as standard mode federated providers. If set to false, transparent mode is turned off, which means federated search users on your deployment can run federated searches only over standard mode federated providers.
controlCommandsFeatureEnabled Specifies whether a federated search head can send a federated search action, such as a search pause or cancellation, to federated providers. Defaults to true.
controlCommandsMaxThreads The maximum number of threads that can run a federated search action, such as a search pause or cancellation, from a federated search head, on federated providers. Defaults to 5.
controlCommandsMaxTimeThreshold The maximum number of seconds that a federated search head waits for the completion of a federated search action such as a search pause or cancellation. Defaults to 5.
needs_consent When set to true, needs_consent causes a checkbox to appear in the UI for federated provider definitions and index assignment to roles. This checkbox requires that users acknowledge that federated providers and federated index permissions can be set up in a manner detrimental to regulatory compliance. When set to false, needs_consent hides this checkbox. Defaults to true

Example request and response
Return the general federated search settings for your Splunk platform deployment. The XML response shows an example of returned federated search settings.

XML Request

curl -k -u admin:changeme -X GET https://localhost:8107/services/data/federated/settings/general

XML response

...
  <entry>
    <title>general</title>
    <id>https://localhost:8107/servicesNS/nobody/system/data/federated/settings/general</id>
    <updated>1970-01-01T00:00:00+00:00</updated>
    <link href="/servicesNS/nobody/system/data/federated/settings/general" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/system/data/federated/settings/general" rel="list"/>
    <link href="/servicesNS/nobody/system/data/federated/settings/general/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/system/data/federated/settings/general" rel="edit"/>
    <link href="/servicesNS/nobody/system/data/federated/settings/general/disable" rel="disable"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="controlCommandsFeatureEnabled">1</s:key>
        <s:key name="controlCommandsMaxThreads">5</s:key>
        <s:key name="controlCommandsMaxTimeThreshold">5</s:key>
        <s:key name="disabled">0</s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app">system</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>*</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">0</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="eai:attributes">
          <s:dict>
            <s:key name="optionalFields">
              <s:list>
                <s:item>controlCommandsFeatureEnabled</s:item>
                <s:item>controlCommandsMaxThreads</s:item>
                <s:item>controlCommandsMaxTimeThreshold</s:item>
                <s:item>heartbeatEnabled</s:item>
                <s:item>needs_consent</s:item>
              </s:list>
            </s:key>
            <s:key name="requiredFields">
              <s:list/>
            </s:key>
            <s:key name="wildcardFields">
              <s:list>
                <s:item>.*</s:item>
              </s:list>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="needs_consent">1</s:key>
        <s:key name="transparent_mode">0</s:key>
      </s:dict>
    </content>
  </entry>

POST

Updates general federated search settings. Can be used to turn federated search functionality on or off for a Splunk platform deployment.

Request parameters

Name Type Description
disabled Boolean When set to false, disabled specifies that federated search functionality is turned on for your Splunk platform deployment. When set to false, disabled specifies that federated search functionality is turned off for your Splunk platform deployment.

Defaults to false.
transparent_mode Boolean When set to true, transparent_mode specifies that transparent mode federated search functionality is turned on for your Splunk platform deployment, which means that federated search users on your deployment can run federated searches over transparent mode federated providers as well as standard mode federated providers.

When set to false, transparent_mode specifies that transparent mode federated search functionality is turned off for your Splunk platform deployment, which means that federated search users on your deployment can run federated searches only over standard mode federated providers.

Defaults to true.
controlCommandsFeatureEnabled Boolean Specifies whether a federated search head can send a federated search action, such as a search pause or cancellation, to federated providers. Defaults to true.

Change this setting only when instructed to do so by Splunk Support.
controlCommandsMaxThreads Number The maximum number of threads that can run a federated search action, such as a search pause or cancellation, from a federated search head, on federated providers. Defaults to 5.

Change this setting only when instructed to do so by Splunk Support.
controlCommandsMaxTimeThreshold Number The maximum number of seconds that a federated search head waits for the completion of a federated search action such as a search pause or cancellation. Defaults to 5.

Change this setting only when instructed to do so by Splunk Support.
needs_consent Boolean When set to true, needs_consent causes a checkbox to appear in the UI for federated provider definitions and index assignment to roles. This checkbox requires that users acknowledge that federated providers and federated index permissions can be set up in a manner detrimental to regulatory compliance. When set to false, needs_consent hides this checkbox. Defaults to true.

Change this setting only when instructed to do so by Splunk Support.

Returned values

Name Description
disabled Specifies whether federated search functionality is turned on for the Splunk platform deployment.

If disabled = false, federated search functionality is turned on for the deployment. If disabled = true, federated search functionality is turned off for the deployment.

Defaults to false.

transparent_mode Specifies whether transparent mode federated search functionality is turned on for the Splunk platform deployment.

If set to true, transparent mode is turned on, which means users can run federated searches over transparent mode federated providers as well as standard mode federated providers. If set to false, transparent mode is turned off, which means users can run federated searches only over standard mode federated providers.
controlCommandsFeatureEnabled Specifies whether a federated search head can send a federated search action, such as a search pause or cancellation, to federated providers. Defaults to true.
controlCommandsMaxThreads The maximum number of threads that can run a federated search action, such as a search pause or cancellation, from a federated search head, on federated providers. Defaults to 5.
controlCommandsMaxTimeThreshold The maximum number of seconds that a federated search head waits for the completion of a federated search action such as a search pause or cancellation. Defaults to 5.
needs_consent A setting of true causes a checkbox to appear in the UI for federated provider definitions and index assignment to roles. This checkbox requires that users acknowledge that federated providers and federated index permissions can be set up in a manner detrimental to regulatory compliance. Defaults to true.

Example request and response
Turn off transparent mode federated search for this Splunk platform deployment.

XML Request

curl -k -u admin:changeme -X POST https://localhost:8107/services/data/federated/settings/general -d transparent_mode=false

XML response

...
  <entry>
    <title>general</title>
    <id>https://localhost:8107/servicesNS/nobody/system/data/federated/settings/general</id>
    <updated>1970-01-01T00:00:00+00:00</updated>
    <link href="/servicesNS/nobody/system/data/federated/settings/general" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/system/data/federated/settings/general" rel="list"/>
    <link href="/servicesNS/nobody/system/data/federated/settings/general/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/system/data/federated/settings/general" rel="edit"/>
    <link href="/servicesNS/nobody/system/data/federated/settings/general/disable" rel="disable"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="controlCommandsFeatureEnabled">1</s:key>
        <s:key name="controlCommandsMaxThreads">5</s:key>
        <s:key name="controlCommandsMaxTimeThreshold">5</s:key>
        <s:key name="disabled">0</s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app">system</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>*</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">0</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="needs_consent">1</s:key>
        <s:key name="transparent_mode">0</s:key>
      </s:dict>
    </content>
  </entry>

data/federated/provider

https://<host>:<mPort>/services/data/federated/provider

Use this endpoint to get a list of federated providers and post new federated provider definitions. See Define a federated provider.

Authentication and authorization
Use of the GET and POST operations for this endpoint are restricted to roles that have the admin_all_objects and indexes_edit capabilities.

GET

Returns a list of federated providers.

Request parameters
None specific to this method. This method can use pagination and filtering parameters.

Returned values

Name Description
name Specifies the name of the federated provider.
mode Specifies whether the federated provider runs federated searches in standard or transparent mode. For a detailed comparison of the standard and transparent modes of federated search, see About federated search in the Search Manual.

Defaults to standard.

appContext Specifies the Splunk application context for federated searches that are run over standard mode federated providers. The application context ensures that standard mode federated searches using this federated provider are limited to the knowledge objects that are associated with the named application.
  • If mode = standard for this federated provider, appContext specifies an the folder name of an app that is installed on the remote search head of the federated provider.
  • If mode = transparent for this federated provider, the federated provider ignores the appContext setting when you run federated searches over the provider. Transparent mode federated searches use the application context of the user running the search.

Defaults to search.

hostPort Specifies the protocols required to connect to a federated provider. Usually follows this format <Host_Name>:<Service_Port_Number>. In some cases, an IP address is used instead of a host name.
serviceAccount Specifies the user name for a service account that has been set up on the federated provider for the purpose of facilitating secure federated searches.
type Specifies the federated provider type. At this point, only Splunk deployments are supported. Defaults to splunk.
useFSHKnowledgeObjects Specifies whether the remote search head uses its own knowledge objects for federated searches, or if it uses knowledge objects that are bundle-replicated from the federated search head.

The federated provider mode determines the required setting for useFSHKnowledgeObjects.

  • When the federated provider has mode=standard, Splunk software always interprets useFSHKnowledgeObjects as being set to 0 or false, which means that the federated search can use a blend of local and remote knowledge objects.
  • When the federated provider has mode=transparent, Splunk software always interprets useFSHKnowledgeObjects as being set to 1 or true, because transparent mode federated searches can only use knowledge objects from the federated search head.
connectivityStatus Specifies whether the federated provider established a connection to your local deployment in its last attempt to do so.
  • When connectivityStatus=valid, this federated provider was able to connect to your local deployment.
  • When connectivityStatus=invalid, this federated provider was unable to connect to your local deployment.
  • When connectivityStatus=unknown, the ability of the federated provider to check this connection has been turned off.

This setting is for diagnostic purposes only and cannot be set or changed by users.

disabled Specifies whether the federated provider is turned on or off. When a federated provider is turned off, the provider cannot return results for federated searches.

Example request and response
Return a list of federated providers. (The XML response shows an example of a single returned federated provider record.)

XML request

curl -k -u admin:changeme  https://localhost:8126/services/data/federated/provider

XML response

...
  <entry>
    <title>provider-1</title>
    <id>https://localhost:8126/servicesNS/nobody/system/data/federated/provider/provider-1</id>
    <updated>1970-01-01T00:00:00+00:00</updated>
    <link href="/servicesNS/nobody/system/data/federated/provider/provider-1" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/system/data/federated/provider/provider-1" rel="list"/>
    <link href="/servicesNS/nobody/system/data/federated/provider/provider-1/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/system/data/federated/provider/provider-1" rel="edit"/>
    <link href="/servicesNS/nobody/system/data/federated/provider/provider-1" rel="remove"/>
    <link href="/servicesNS/nobody/system/data/federated/provider/provider-1/disable" rel="disable"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="appContext">search</s:key>
        <s:key name="connectivityStatus">invalid</s:key>
        <s:key name="disabled">0</s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app">system</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>*</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">1</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="hostPort">10.225.131.242:8089</s:key>
        <s:key name="mode">standard</s:key>
        <s:key name="serviceAccount">admin</s:key>
        <s:key name="type">splunk</s:key>
        <s:key name="useFSHKnowledgeObjects">0</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

POST

Creates a new federated provider definition.

Request parameters

Name Type Description
name String Required. Specify a unique name for the federated provider.
mode String Specify whether the federated provider runs federated searches in standard or transparent mode. For a detailed comparison of the standard and transparent modes of federated search, see About federated search in the Search Manual.

Transparent mode is recommended only if you are migrating to federated search from a Splunk Enterprise to Splunk Cloud Platform hybrid search setup.

Federated search does not support setting up a mix of transparent mode and standard mode federated providers for the same local deployment, as this practice can introduce unexpected complications. All of the federated providers for a specific local deployment must use the same provider mode.

Defaults to standard.
appContext String Specify an app folder name to apply an application context to federated searches over a standard mode federated provider. The application context determines which set of knowledge objects on the remote search head is applied to the federated searches you run over that provider.
  • If mode = standard, provide the short name of an app that is installed on the remote search head of the federated provider.
  • If mode = transparent, you do not need to set appContext. Transparent mode federated providers ignore the appContext setting and instead apply the application context of the user running the federated search.

Defaults to Search.

hostPort String Required. Provide the host name and port number for the federated provider, separated by a colon character. For example: buttercupgames.splunkcloud.com:8089.
password String Required. Provide the password for a service account that is already set up on the federated provider. This dedicated user account allows the federated search head on your local instance to securely search datasets on the federated provider.
serviceAccount String Required. Provide the username for a service account that is already set up on the federated provider. This dedicated user account allows the federated search head on your local instance to securely search datasets on the federated provider.
type String Set the type of federated provider. Currently only Splunk deployments are supported. Defaults to splunk. No other values are allowed.
useFSHKnowledgeObjects Boolean Specifies whether the remote search head uses its own knowledge objects for federated searches, or if it uses knowledge objects that are bundle-replicated from the federated search head.

The federated provider mode determines the required setting for useFSHKnowledgeObjects.

There is no need to set useFSHKnowledgeObjects for a new provider. When you create a new provider through this endpoint without specifying a useFSHKnowledgeObjects value, Splunk software sets useFSHKnowledgeObjects to the correct value based on the specified provider mode.

  • When the federated provider has mode=standard, Splunk software always interprets useFSHKnowledgeObjects as being set to 0 or false, which means that the federated search can use a blend of local and remote knowledge objects.
  • When the federated provider has mode=transparent, Splunk software always interprets useFSHKnowledgeObjects as being set to 1 or true, because transparent mode federated searches can only use knowledge objects from the federated search head.

Returned values

Name Description
name Specifies the name of the federated provider.
mode Specifies whether the federated provider runs federated searches in standard or transparent mode. For a detailed comparison of the standard and transparent modes of federated search, see About federated search in the Search Manual.

Defaults to standard.

appContext Specifies the Splunk application context for federated searches that are run over standard mode federated providers. The application context ensures that standard mode federated searches using this federated provider are limited to the knowledge objects that are associated with the named application.
  • If mode = standard for this federated provider, appContext specifies an the folder name of an app that is installed on the remote search head of the federated provider.
  • If mode = transparent for this federated provider, the federated provider ignores the appContext setting when you run federated searches over the provider. Transparent mode federated searches use the application context of the user running the search.

Defaults to search.

hostPort Specifies the protocols required to connect to a federated provider. Usually follows this format <Host_Name>:<Service_Port_Number>. In some cases, an IP address is used instead of a host name.
serviceAccount Specifies the user name for a service account that has been set up on the federated provider for the purpose of facilitating secure federated searches.
type Specifies the federated provider type. At this point, only Splunk deployments are supported. Defaults to splunk.
useFSHKnowledgeObjects Specifies whether the remote search head uses its own knowledge objects for federated searches, or if it uses knowledge objects that are bundle-replicated from the federated search head.

The federated provider mode determines the required setting for useFSHKnowledgeObjects.

  • When the federated provider has mode=standard, Splunk software always interprets useFSHKnowledgeObjects as being set to 0 or false, which means that the federated search can use a blend of local and remote knowledge objects.
  • When the federated provider has mode=transparent, Splunk software always interprets useFSHKnowledgeObjects as being set to 1 or true, because transparent mode federated searches can only use knowledge objects from the federated search head.
connectivityStatus Specifies whether the federated provider established a connection to your local deployment in its last attempt to do so.
  • When connectivityStatus=valid, this federated provider was able to connect to your local deployment.
  • When connectivityStatus=invalid, this federated provider was unable to connect to your local deployment.
  • When connectivityStatus=unknown, the ability of the federated provider to check this connection has been turned off.

This setting is for diagnostic purposes only and cannot be set or changed by users.

Example request and response
Create a new definition for a federated provider named provider-1.

XML request

curl -k -u admin:changeme  https://localhost:8126/services/data/federated/provider -d name=provider-1 -d type=splunk -d mode=standard -d hostPort=10.225.131.242:8089 -d serviceAccount=admin -d password=Chang3d!

XML response

...
  <entry>
    <title>provider-1</title>
    <id>https://localhost:8126/servicesNS/nobody/system/data/federated/provider/provider-1</id>
    <updated>1970-01-01T00:00:00+00:00</updated>
    <link href="/servicesNS/nobody/system/data/federated/provider/provider-1" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/system/data/federated/provider/provider-1" rel="list"/>
    <link href="/servicesNS/nobody/system/data/federated/provider/provider-1/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/system/data/federated/provider/provider-1" rel="edit"/>
    <link href="/servicesNS/nobody/system/data/federated/provider/provider-1" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="appContext">search</s:key>
        <s:key name="connectivityStatus">unknown</s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app">system</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>*</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">1</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="hostPort">10.225.131.242:8089</s:key>
        <s:key name="mode">standard</s:key>
        <s:key name="serviceAccount">admin</s:key>
        <s:key name="type">splunk</s:key>
        <s:key name="useFSHKnowledgeObjects">0</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

data/federated/provider/{federated_provider_name}

https://<host>:<mPort>/services/data/federated/provider/{federated_provider_name}

Use this endpoint to:

  • Retrieve a specific federated provider definition.
  • Update a specific federated provider definition.
  • Delete a specific federated provider definition.

See Define a federated provider.

Authentication and Authorization
Usage of the GET, POST, and DELETE operations for this endpoint require the admin_all_objects and indexes_edit capabilities.

GET

Returns a definition of a specific {federated_provider_name}.

Request parameters
None specific to this method.

Returned values

Name Description
name Specifies the name of the federated provider.
mode Specifies whether the federated provider runs federated searches in standard or transparent mode. For a detailed comparison of the standard and transparent modes of federated search, see About federated search in the Search Manual.

Defaults to standard.

appContext Specifies the Splunk application context for federated searches that are run over standard mode federated providers. The application context ensures that standard mode federated searches using this federated provider are limited to the knowledge objects that are associated with the named application.
  • If mode = standard for this federated provider, appContext specifies an the folder name of an app that is installed on the remote search head of the federated provider.
  • If mode = transparent for this federated provider, the federated provider ignores the appContext setting when you run federated searches over the provider. Transparent mode federated searches use the application context of the user running the search.

Defaults to search.

hostPort Specifies the protocols required to connect to a federated provider. Usually follows this format <Host_Name>:<Service_Port_Number>. In some cases, an IP address is used instead of a host name.
serviceAccount Specifies the user name for a service account that has been set up on the federated provider for the purpose of facilitating secure federated searches.
type Specifies the federated provider type. At this point, only Splunk deployments are supported. Defaults to splunk.
useFSHKnowledgeObjects Specifies whether the remote search head uses its own knowledge objects for federated searches, or if it uses knowledge objects that are bundle-replicated from the federated search head.

The federated provider mode determines the required setting for useFSHKnowledgeObjects.

  • When the federated provider has mode=standard, Splunk software always interprets useFSHKnowledgeObjects as being set to 0 or false, which means that the federated search can use a blend of local and remote knowledge objects.
  • When the federated provider has mode=transparent, Splunk software always interprets useFSHKnowledgeObjects as being set to 1 or true, because transparent mode federated searches can only use knowledge objects from the federated search head.
connectivityStatus Specifies whether the federated provider established a connection to your local deployment in its last attempt to do so.
  • When connectivityStatus=valid, this federated provider was able to connect to your local deployment.
  • When connectivityStatus=invalid, this federated provider was unable to connect to your local deployment.
  • When connectivityStatus=unknown, the ability of the federated provider to check this connection has been turned off.

This setting is for diagnostic purposes only and cannot be set or changed by users.

disabled Specifies whether the federated provider is turned on or off. When a federated provider is turned off, the provider cannot return results for federated searches.

Example request and response
Return the definition for the my_federated_provider federated provider.

XML Request

curl -k -u admin:changeme  https://localhost:8089/services/data/federated/provider/my_federated_provider

XML response

...
<entry>
  <title>my_federated_provider</title>
  <id>/servicesNS/nobody/system/data/federated/provider/my_federated_provider</id>
  <updated>1969-12-31T16:00:00-08:00</updated>
  <link href="/servicesNS/nobody/system/data/federated/provider/my_federated_provider" rel="alternate"/>
  <author>
    <name>nobody</name>
  </author>
  <link href="/servicesNS/nobody/system/data/federated/provider/my_federated_provider" rel="list"/>
  <link href="/servicesNS/nobody/system/data/federated/provider/my_federated_provider/_reload" rel="_reload"/>
  <link href="/servicesNS/nobody/system/data/federated/provider/my_federated_provider" rel="edit"/>
  <link href="/servicesNS/nobody/system/data/federated/provider/my_federated_provider" rel="remove"/>
  <link href="/servicesNS/nobody/system/data/federated/provider/my_federated_provider/disable" rel="disable"/>
  <content type="text/xml">
    <s:dict>
      <s:key name="appContext">search</s:key>
      <s:key name="disabled">0</s:key>
      <s:key name="eai:acl">
        <s:dict>
          <s:key name="app">system</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>*</s:item>
                </s:list>
              </s:key>
              <s:key name="write">
                <s:list>
                  <s:item>*</s:item>
                </s:list>
              </s:key>
            </s:dict>
          </s:key>
          <s:key name="removable">1</s:key>
          <s:key name="sharing">system</s:key>
        </s:dict>
      </s:key>
      <s:key name="eai:attributes">
        <s:dict>
          <s:key name="optionalFields">
            <s:list>
              <s:item>appContext</s:item>
              <s:item>hostPort</s:item>
              <s:item>password</s:item>
              <s:item>serviceAccount</s:item>
              <s:item>type</s:item>
              <s:item>useFSHKnowledgeObjects</s:item>
            </s:list>
          </s:key>
          <s:key name="requiredFields">
            <s:list/>
          </s:key>
          <s:key name="wildcardFields">
            <s:list>
              <s:item>.*</s:item>
            </s:list>
          </s:key>
        </s:dict>
      </s:key>
      <s:key name="hostPort">10.225.131.242:8089</s:key>
      <s:key name="mode">standard</s:key>
      <s:key name="serviceAccount">user1</s:key>
      <s:key name="type">splunk</s:key>
      <s:key name="useFSHKnowledgeObjects">1</s:key>
    </s:dict>
  </content>
</entry>

POST

Updates a definition for a specific {federated_provider_name}.

Request parameters

At least one argument is required.

Name Type Description
appContext String Specify an app folder name to apply an application context to federated searches over a standard mode federated provider. The application context determines which set of knowledge objects on the remote search head is applied to the federated searches you run over that provider.
  • If mode = standard, provide the short name of an app that is installed on the remote search head of the federated provider.
  • If mode = transparent, you do not need to set appContext. Transparent mode federated providers ignore the appContext setting and instead apply the application context of the user running the federated search.

Defaults to search.

hostPort String Provide the host name and port number for the federated provider, separated by a colon character. For example: buttercupgames.splunkcloud.com:8089.
password String Provide the password for a service account that is already set up on the federated provider. This dedicated user account allows the federated search head on your local instance to securely search datasets on the federated provider.
serviceAccount String Provide the username for a service account that is already set up on the federated provider. This dedicated user account allows the federated search head on your local instance to securely search datasets on the federated provider.

Returned values

Name Description
name Specifies the name of the federated provider.
mode Specifies whether the federated provider runs federated searches in standard or transparent mode. For a detailed comparison of the standard and transparent modes of federated search, see About federated search in the Search Manual.

Defaults to standard.

appContext Specifies the Splunk application context for federated searches that are run over standard mode federated providers. The application context ensures that standard mode federated searches using this federated provider are limited to the knowledge objects that are associated with the named application.
  • If mode = standard for this federated provider, appContext specifies an the folder name of an app that is installed on the remote search head of the federated provider.
  • If mode = transparent for this federated provider, the federated provider ignores the appContext setting when you run federated searches over the provider. Transparent mode federated searches use the application context of the user running the search.

Defaults to search.

hostPort Specifies the protocols required to connect to a federated provider. Usually follows this format <Host_Name>:<Service_Port_Number>. In some cases, an IP address is used instead of a host name.
serviceAccount Specifies the user name for a service account that has been set up on the federated provider for the purpose of facilitating secure federated searches.
type Specifies the federated provider type. At this point, only Splunk deployments are supported. Defaults to splunk.
useFSHKnowledgeObjects Specifies whether the remote search head uses its own knowledge objects for federated searches, or if it uses knowledge objects that are bundle-replicated from the federated search head.

The federated provider mode determines the required setting for useFSHKnowledgeObjects.

  • When the federated provider has mode=standard, Splunk software always interprets useFSHKnowledgeObjects as being set to 0 or false, which means that the federated search can use a blend of local and remote knowledge objects.
  • When the federated provider has mode=transparent, Splunk software always interprets useFSHKnowledgeObjects as being set to 1 or true, because transparent mode federated searches can only use knowledge objects from the federated search head.
connectivityStatus Specifies whether the federated provider established a connection to your local deployment in its last attempt to do so.
  • When connectivityStatus=valid, this federated provider was able to connect to your local deployment.
  • When connectivityStatus=invalid, this federated provider was unable to connect to your local deployment.
  • When connectivityStatus=unknown, the ability of the federated provider to check this connection has been turned off.

This setting is for diagnostic purposes only and cannot be set or changed by users.

disabled Specifies whether the federated provider is turned on or off. When a federated provider is turned off, the provider cannot return results for federated searches.

Example request and response

Change the serviceAccount setting to eagle01 to match an update to the service account user on the federated provider.

XML request

curl -k -u admin:changeme  https://localhost:8089/services/data/federated/provider/my_federated_provider -d serviceAccount=eagle01

XML response

  <entry>
    <title>my_federated_provider</title>
    <id>https://localhost:8089/servicesNS/nobody/system/data/federated/provider/my_federated_provider</id>
    <updated>1970-01-01T00:00:00+00:00</updated>
    <link href="/servicesNS/nobody/system/data/federated/provider/my_federated_provider" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/system/data/federated/provider/my_federated_provider" rel="list"/>
    <link href="/servicesNS/nobody/system/data/federated/provider/my_federated_provider/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/system/data/federated/provider/my_federated_provider" rel="edit"/>
    <link href="/servicesNS/nobody/system/data/federated/provider/my_federated_provider" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="appContext">search</s:key>
       <s:key name="connectivityStatus">valid</s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app">system</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>*</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">1</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="hostPort">10.224.150.77:58677</s:key>
        <s:key name="mode">standard</s:key>
        <s:key name="serviceAccount">eagle01</s:key>
        <s:key name="type">splunk</s:key>
        <s:key name="useFSHKnowledgeObjects">0</s:key>
      </s:dict>
    </content>
  </entry>

DELETE

Deletes a definition for a specific {federated_provider_name}.

Request parameters
None specific to this method.

Returned values
None specific to this method.

Example request and response
Remove the my_federated_provider stanza from federated.conf.

XML Request

curl -k -u admin:changeme -X DELETE https://localhost:8089/services/data/federated/provider/my_federated_provider

XML response

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>federated-provider</title>
  <id>/services/data/federated/provider</id>
  <updated>2021-04-27T12:47:36-07:00</updated>
  <generator build="aa7e77c0d232b8ec1a8c12ceeda95e0bfe3c3f1c" version="20210423"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/data/federated/provider/_new" rel="create"/>
  <link href="/services/data/federated/provider/_reload" rel="_reload"/>
  <link href="/services/data/federated/provider/_acl" rel="_acl"/>
  <opensearch:totalResults>0</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
</feed>

data/federated/provider/{federated_provider_name}/disable

https://<host>:<mPort>/services/data/federated/provider/{federated_provider_name}/disable

Use this endpoint to turn a specific federated provider off.

See Define a federated provider.

Authentication and Authorization
Usage of the POST operation for this endpoint requires the admin_all_objects and indexes_edit capabilities.

POST

Turn off a specific federated provider.

Request parameters
None specific to this method.

Returned values

Name Description
name Specifies the name of the federated provider.
mode Specifies whether the federated provider runs federated searches in standard or transparent mode. For a detailed comparison of the standard and transparent modes of federated search, see About federated search in the Search Manual.

Defaults to standard.

appContext Specifies the Splunk application context for federated searches that are run over standard mode federated providers. The application context ensures that standard mode federated searches using this federated provider are limited to the knowledge objects that are associated with the named application.
  • If mode = standard for this federated provider, appContext specifies an the folder name of an app that is installed on the remote search head of the federated provider.
  • If mode = transparent for this federated provider, the federated provider ignores the appContext setting when you run federated searches over the provider. Transparent mode federated searches use the application context of the user running the search.

Defaults to search.

hostPort Specifies the protocols required to connect to a federated provider. Usually follows this format <Host_Name>:<Service_Port_Number>. In some cases, an IP address is used instead of a host name.
serviceAccount Specifies the user name for a service account that has been set up on the federated provider for the purpose of facilitating secure federated searches.
type Specifies the federated provider type. At this point, only Splunk deployments are supported. Defaults to splunk.
useFSHKnowledgeObjects Specifies whether the remote search head uses its own knowledge objects for federated searches, or if it uses knowledge objects that are bundle-replicated from the federated search head.

The federated provider mode determines the required setting for useFSHKnowledgeObjects.

  • When the federated provider has mode=standard, Splunk software always interprets useFSHKnowledgeObjects as being set to 0 or false, which means that the federated search can use a blend of local and remote knowledge objects.
  • When the federated provider has mode=transparent, Splunk software always interprets useFSHKnowledgeObjects as being set to 1 or true, because transparent mode federated searches can only use knowledge objects from the federated search head.
connectivityStatus Specifies whether the federated provider established a connection to your local deployment in its last attempt to do so.
  • When connectivityStatus=valid, this federated provider was able to connect to your local deployment.
  • When connectivityStatus=invalid, this federated provider was unable to connect to your local deployment.
  • When connectivityStatus=unknown, the ability of the federated provider to check this connection has been turned off.

This setting is for diagnostic purposes only and cannot be set or changed by users.

disabled Specifies whether the federated provider is turned on or off. When a federated provider is turned off, the provider cannot return results for federated searches.

Example request and response
Turn off a federated provider named My Federated Provider.

XML request

curl -k -u admin:changeme -X POST  https://localhost:8089/services/data/federated/provider/my_federated_provider/disable

XML response

  <entry>
    <title>my_federated_provider</title>
    <id>https://localhost:8089/servicesNS/nobody/system/data/federated/provider/my_federated_provider</id>
    <updated>1970-01-01T00:00:00+00:00</updated>
    <link href="/servicesNS/nobody/system/data/federated/provider/my_federated_provider" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/system/data/federated/provider/my_federated_provider" rel="list"/>
    <link href="/servicesNS/nobody/system/data/federated/provider/my_federated_provider/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/system/data/federated/provider/my_federated_provider" rel="edit"/>
    <link href="/servicesNS/nobody/system/data/federated/provider/my_federated_provider" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="appContext">search</s:key>
       <s:key name="disabled">1</s:key>
       <s:key name="connectivityStatus">valid</s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app">system</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>*</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">1</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="hostPort">10.224.150.77:58677</s:key>
        <s:key name="mode">standard</s:key>
        <s:key name="serviceAccount">eagle01</s:key>
        <s:key name="type">splunk</s:key>
        <s:key name="useFSHKnowledgeObjects">0</s:key>
      </s:dict>
    </content>
  </entry>

data/federated/provider/{federated_provider_name}/enable

https://<host>:<mPort>/services/data/federated/provider/{federated_provider_name}/enable

Use this endpoint to turn a specific federated provider on.

See Define a federated provider.

Authentication and Authorization
Usage of the POST operation for this endpoint requires the admin_all_objects and indexes_edit capabilities.

POST

Turns a specific federated index on.

Request parameters
None specific to this method.

Returned values

Name Description
name Specifies the name of the federated provider.
mode Specifies whether the federated provider runs federated searches in standard or transparent mode. For a detailed comparison of the standard and transparent modes of federated search, see About federated search in the Search Manual.

Defaults to standard.

appContext Specifies the Splunk application context for federated searches that are run over standard mode federated providers. The application context ensures that standard mode federated searches using this federated provider are limited to the knowledge objects that are associated with the named application.
  • If mode = standard for this federated provider, appContext specifies an the folder name of an app that is installed on the remote search head of the federated provider.
  • If mode = transparent for this federated provider, the federated provider ignores the appContext setting when you run federated searches over the provider. Transparent mode federated searches use the application context of the user running the search.

Defaults to search.

hostPort Specifies the protocols required to connect to a federated provider. Usually follows this format <Host_Name>:<Service_Port_Number>. In some cases, an IP address is used instead of a host name.
serviceAccount Specifies the user name for a service account that has been set up on the federated provider for the purpose of facilitating secure federated searches.
type Specifies the federated provider type. At this point, only Splunk deployments are supported. Defaults to splunk.
useFSHKnowledgeObjects Specifies whether the remote search head uses its own knowledge objects for federated searches, or if it uses knowledge objects that are bundle-replicated from the federated search head.

The federated provider mode determines the required setting for useFSHKnowledgeObjects.

  • When the federated provider has mode=standard, Splunk software always interprets useFSHKnowledgeObjects as being set to 0 or false, which means that the federated search can use a blend of local and remote knowledge objects.
  • When the federated provider has mode=transparent, Splunk software always interprets useFSHKnowledgeObjects as being set to 1 or true, because transparent mode federated searches can only use knowledge objects from the federated search head.
connectivityStatus Specifies whether the federated provider established a connection to your local deployment in its last attempt to do so.
  • When connectivityStatus=valid, this federated provider was able to connect to your local deployment.
  • When connectivityStatus=invalid, this federated provider was unable to connect to your local deployment.
  • When connectivityStatus=unknown, the ability of the federated provider to check this connection has been turned off.

This setting is for diagnostic purposes only and cannot be set or changed by users.

disabled Specifies whether the federated provider is turned on or off. When a federated provider is turned off, the provider cannot return results for federated searches.

Example request and response
Turn on a federated provider named My Federated Provider.

XML request

curl -k -u admin:changeme -X POST  https://localhost:8089/services/data/federated/provider/my_federated_provider/enable

XML response

  <entry>
    <title>my_federated_provider</title>
    <id>https://localhost:8089/servicesNS/nobody/system/data/federated/provider/my_federated_provider</id>
    <updated>1970-01-01T00:00:00+00:00</updated>
    <link href="/servicesNS/nobody/system/data/federated/provider/my_federated_provider" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/system/data/federated/provider/my_federated_provider" rel="list"/>
    <link href="/servicesNS/nobody/system/data/federated/provider/my_federated_provider/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/system/data/federated/provider/my_federated_provider" rel="edit"/>
    <link href="/servicesNS/nobody/system/data/federated/provider/my_federated_provider" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="appContext">search</s:key>
       <s:key name="disabled">0</s:key>
       <s:key name="connectivityStatus">valid</s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app">system</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>*</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">1</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="hostPort">10.224.150.77:58677</s:key>
        <s:key name="mode">standard</s:key>
        <s:key name="serviceAccount">eagle01</s:key>
        <s:key name="type">splunk</s:key>
        <s:key name="useFSHKnowledgeObjects">0</s:key>
      </s:dict>
    </content>
  </entry>

data/federated/index

https://<host>:<mPort>/services/data/federated/index

Use this endpoint to get a list of federated indexes and post new federated index definitions. See Create a federated index.

Authentication and authorization
Use of the GET and POST operations for this endpoint are restricted to roles that have the admin_all_objects and indexes_edit capabilities.

GET

Returns a list of federated indexes.

Request parameters
None specific to this method. This method can use pagination and filtering parameters.

Returned values
This table is limited to settings specific to federated indexes. For descriptions of other index settings see the entry for data/indexes.

The data/indexes endpoint is available only to users of Splunk Enterprise.

Name Description
name Specifies the name of the federated index. Uses the syntax federated:<index_name>.
federated.provider Specifies the federated provider that contains the dataset to which this federated index maps.
federated.dataset Specifies the remote dataset on the federated.provider to which this federated index maps. Each federated index maps to one dataset on a federated provider. The dataset is identified by its type and name, using the following syntax: <type>:<dataset_name>.


Possible values for <type> are index, savedsearch, lastjob, and datamodel.

Remote dataset type Dataset name More information
index A name of an events or metrics index on the federated provider. Each remote index is a searchable dataset.
savedsearch A name of a saved search on the federated provider. The result set produced by an ad-hoc run of a saved search is a searchable dataset.
lastjob A name of a saved search on the federated provider that has been configured to run on a schedule. The result set for the last job run for a scheduled search is a searchable dataset.
datamodel A name of a data model on the federated provider. The set of events defined by a data model is a searchable dataset.


Example request and response
Get the complete list of federated indexes. (The XML response provides a sample of one returned index record.)

XML Request

curl -k -u admin:changeme  https://localhost:8126/services/data/federated/index

XML response

...
  <entry>
    <title>federated:remote_index_df_1</title>
    <id>https://localhost:8126/servicesNS/nobody/search/data/federated/index/federated%3Aremote_index_df_1</id>
    <updated>1970-01-01T00:00:00+00:00</updated>
    <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aremote_index_df_1" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aremote_index_df_1" rel="list"/>
    <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aremote_index_df_1/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aremote_index_df_1" rel="edit"/>
    <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aremote_index_df_1" rel="remove"/>
    <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aremote_index_df_1/move" rel="move"/>
    <content type="text/xml">
      <s:dict>
        <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>*</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">1</s:key>
            <s:key name="sharing">app</s:key>
          </s:dict>
        </s:key>
        <s:key name="federated.dataset">index:index_df_1</s:key>
        <s:key name="federated.provider">provider-1</s:key>
      </s:dict>
    </content>
  </entry>

POST

Creates a new federated index definition.

These tables are limited to settings specific to federated indexes. For descriptions of other index settings see the entry for data/indexes.

The data/indexes endpoint is available only to users of Splunk Enterprise.

Request parameters

Name Type Description
name String Required. Specify a unique name for the federated index, using the syntax federated:<index_name>. Each federated index maps to only one remote dataset on a federated provider, so the name should reference that dataset.

Index names have the following limitations:
  • They may contain only lowercase letters, numbers, underscores, and hyphens.
  • They must begin with a letter or number.
  • They cannot be more than 2048 characters in length.
  • They cannot contain the string "kvstore".
federated.provider String Required. Specify the federated provider that contains the dataset to which this federated index maps.
federated.dataset String Required. Specify the dataset on the federated.provider to which this federated index maps. The dataset is identified by its type and name, using the following syntax: <type>:<dataset_name>.

Possible values for <type> are index, savedsearch, lastjob, and datamodel.

Remote dataset type Dataset name More information
index A name of an events or metrics index on the federated provider. Each remote index is a searchable dataset.
savedsearch A name of a saved search on the federated provider. The result set produced by an ad-hoc run of a saved search is a searchable dataset.
lastjob A name of a saved search on the federated provider that has been configured to run on a schedule. The result set for the last job run for a scheduled search is a searchable dataset.
datamodel A name of a data model on the federated provider. The set of events defined by a data model is a searchable dataset.

Returned values

Name Description
name Specifies the name of the federated index. Uses the syntax federated:<index_name>.
federated.provider Specifies the federated provider that contains the dataset to which this federated index maps.
federated.dataset Specifies the dataset on the federated.provider to which this federated index maps. Each federated index maps to one dataset on a federated provider. The dataset is identified by its type and name, using the following syntax: <type>:<dataset_name>.

Possible values for <type> are index, savedsearch, lastjob, and datamodel.

Remote dataset type Dataset name More information
index A name of an events or metrics index on the federated provider. Each remote index is a searchable dataset.
savedsearch A name of a saved search on the federated provider. The result set produced by an ad-hoc run of a saved search is a searchable dataset.
lastjob A name of a saved search on the federated provider that has been configured to run on a schedule. The result set for the last job run for a scheduled search is a searchable dataset.
datamodel A name of a data model on the federated provider. The set of events defined by a data model is a searchable dataset.

Example request and response
Create a new definition for a federated index named airports-east.

XML Request

curl -k -u admin:changeme  https://localhost:8089/services/data/federated/index -d name=federated:airports-east -d federated.provider=FenrisAirNYC -d federated.dataset=index:airports-east

XML response

<entry>
  <title>federated:fs-airports-east</title>
  <id>/servicesNS/nobody/search/data/federated/index/federated%3Aairports-east</id>
  <updated>1969-12-31T16:00:00-08:00</updated>
  <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aairports-east" rel="alternate"/>
  <author>
    <name>nobody</name>
  </author>
  <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aairports-east" rel="list"/>
  <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aairports-east/_reload" rel="_reload"/>
  <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aairports-east" rel="edit"/>
  <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aairports-east" rel="remove"/>
  <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aairports-east/move" rel="move"/>
  <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aairports-east/disable" rel="disable"/>
  <content type="text/xml">
    <s:dict>
      <s:key name="assureUTF8">0</s:key>
      <s:key name="bucketMerge.maxMergeSizeMB">1000</s:key>
      <s:key name="bucketMerge.maxMergeTimeSpanSecs">7776000</s:key>
      <s:key name="bucketMerge.minMergeSizeMB">750</s:key>
      <s:key name="bucketMerging">0</s:key>
      <s:key name="coldPath.maxDataSizeMB">0</s:key>
      <s:key name="coldToFrozenDir"></s:key>
      <s:key name="coldToFrozenScript"></s:key>
      <s:key name="compressRawdata">1</s:key>
      <s:key name="datatype">event</s:key>
      <s:key name="defaultDatabase">main</s:key>
      <s:key name="disabled">0</s:key>
      <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>*</s:item>
                </s:list>
              </s:key>
              <s:key name="write">
                <s:list>
                  <s:item>*</s:item>
                </s:list>
              </s:key>
            </s:dict>
          </s:key>
          <s:key name="removable">1</s:key>
          <s:key name="sharing">app</s:key>
        </s:dict>
      </s:key>
      <s:key name="enableDataIntegrityControl">0</s:key>
      <s:key name="enableRealtimeSearch">1</s:key>
      <s:key name="enableTsidxReduction">0</s:key>
      <s:key name="federated.dataset">index:airports-east</s:key>
      <s:key name="federated.provider">FenrisAirNYC</s:key>
      <s:key name="frozenTimePeriodInSecs">188697600</s:key>
      <s:key name="homePath.maxDataSizeMB">0</s:key>
      <s:key name="hotBucketStreaming.deleteHotsAfterRestart">0</s:key>
      <s:key name="hotBucketStreaming.extraBucketBuildingCmdlineArgs"></s:key>
      <s:key name="hotBucketStreaming.removeRemoteSlicesOnRoll">0</s:key>
      <s:key name="hotBucketStreaming.reportStatus">0</s:key>
      <s:key name="hotBucketStreaming.sendSlices">0</s:key>
      <s:key name="hotBucketTimeRefreshInterval">60</s:key>
      <s:key name="indexThreads">auto</s:key>
      <s:key name="journalCompression">gzip</s:key>
      <s:key name="maxConcurrentOptimizes">3</s:key>
      <s:key name="maxDataSize">auto</s:key>
      <s:key name="maxHotBuckets">1</s:key>
      <s:key name="maxHotIdleSecs">0</s:key>
      <s:key name="maxHotSpanSecs">7776000</s:key>
      <s:key name="maxMemMB">5</s:key>
      <s:key name="maxTotalDataSizeMB">500000</s:key>
      <s:key name="maxWarmDBCount">300</s:key>
      <s:key name="memPoolMB">auto</s:key>
      <s:key name="metric.compressionBlockSize">1024</s:key>
      <s:key name="metric.enableFloatingPointCompression">1</s:key>
      <s:key name="metric.maxHotBuckets">1</s:key>
      <s:key name="metric.splitByIndexKeys"></s:key>
      <s:key name="metric.stubOutRawdataJournal">1</s:key>
      <s:key name="metric.timestampResolution">s</s:key>
      <s:key name="metric.tsidxTargetSizeMB">1500</s:key>
      <s:key name="minHotIdleSecsBeforeForceRoll">auto</s:key>
      <s:key name="minStreamGroupQueueSize">2000</s:key>
      <s:key name="quarantineFutureSecs">2592000</s:key>
      <s:key name="quarantinePastSecs">77760000</s:key>
      <s:key name="rawChunkSizeBytes">131072</s:key>
      <s:key name="rotatePeriodInSecs">60</s:key>
      <s:key name="serviceInactiveIndexesPeriod">60</s:key>
      <s:key name="serviceMetaPeriod">1</s:key>
      <s:key name="splitByIndexKeys"></s:key>
      <s:key name="streamingTargetTsidxSyncPeriodMsec">5000</s:key>
      <s:key name="suspendHotRollByDeleteQuery">0</s:key>
      <s:key name="sync">0</s:key>
      <s:key name="timePeriodInSecBeforeTsidxReduction">604800</s:key>
      <s:key name="tsidxDedupPostingsListMaxTermsLimit">8388608</s:key>
      <s:key name="tsidxReductionCheckPeriodInSec">600</s:key>
      <s:key name="tsidxTargetSizeMB">1500</s:key>
      <s:key name="tsidxWritingLevel">1</s:key>
      <s:key name="tstatsHomePath">volume:_splunk_summaries/$_index_name/datamodel_summary</s:key>
    </s:dict>
  </content>
</entry>

data/federated/index/federated:{federated_index_name}

https://<host>:<mPort>/services/data/federated/provider/federated:{federated_index_name}

Use this endpoint to:

  • Retrieve a specific federated index definition.
  • Update a specific federated index definition.
  • Delete a specific federated index definition.

See Create a federated index.

Authentication and Authorization
Usage of the GET, POST, and DELETE operations for this endpoint require the admin_all_objects and indexes_edit capabilities.

GET

Returns a definition of a specific {federated_index_name}.

Request parameters
None specific to this method.

Returned values
This table is limited to settings specific to federated indexes. For descriptions of other index settings see the entry for data/indexes.

The data/indexes endpoint is available only to users of Splunk Enterprise.

Name Description
name Specifies the name of the federated index. Uses the syntax federated:<index_name>.
federated.provider Specifies the federated provider that contains the dataset to which this federated index maps.
federated.dataset Specifies the dataset on the federated.provider to which this federated index maps. Each federated index maps to one dataset on a federated provider. The dataset is identified by its type and name, using the following syntax: <type>:<dataset_name>.


Possible values for <type> are index, savedsearch, lastjob, and datamodel.

Remote dataset type Dataset name More information
index A name of an events or metrics index on the federated provider. Each remote index is a searchable dataset.
savedsearch A name of a saved search on the federated provider. The result set produced by an ad-hoc run of a saved search is a searchable dataset.
lastjob A name of a saved search on the federated provider that has been configured to run on a schedule. The result set for the last job run for a scheduled search is a searchable dataset.
datamodel A name of a data model on the federated provider. The set of events defined by a data model is a searchable dataset.

Example request and response
Return the definition for the remote_index_df_1 federated index.

XML Request

curl -k -u admin:changeme  https://localhost:8126/services/data/federated/index/federated:remote_index_df_1

XML response

<entry>
    <title>federated:remote_index_df_1</title>
    <id>https://localhost:8126/servicesNS/nobody/search/data/federated/index/federated%3Aremote_index_df_1</id>
    <updated>1970-01-01T00:00:00+00:00</updated>
    <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aremote_index_df_1" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aremote_index_df_1" rel="list"/>
    <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aremote_index_df_1/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aremote_index_df_1" rel="edit"/>
    <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aremote_index_df_1" rel="remove"/>
    <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aremote_index_df_1/move" rel="move"/>
    <content type="text/xml">
      <s:dict>
        <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>*</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">1</s:key>
            <s:key name="sharing">app</s:key>
          </s:dict>
        </s:key>
        <s:key name="eai:attributes">
          <s:dict>
            <s:key name="optionalFields">
              <s:list>
            </s:key>
            <s:key name="requiredFields">
              <s:list/>
            </s:key>
            <s:key name="wildcardFields">
              <s:list/>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="federated.dataset">index:index_df_1</s:key>
        <s:key name="federated.provider">provider-1</s:key>
      </s:dict>
    </content>
  </entry>

POST

Updates a definition for a specific {federated_index_name}.

These tables are limited to settings specific to federated indexes. For descriptions of other index settings, see the entry for data/indexes.

The data/indexes endpoint is available only to users of Splunk Enterprise.

Request parameters

At least one argument is required.

Name Type Description
federated.provider String Specify the federated provider that contains the dataset to which this federated index maps.
federated.dataset String Specify the dataset on the federated.provider to which this federated index maps. The dataset is identified by its type and name, using the following syntax: <type>:<dataset_name>.


Possible values for <type> are index, savedsearch, lastjob, and datamodel.

Remote dataset type Dataset name More information
index A name of an events or metrics index on the federated provider. Each remote index is a searchable dataset.
savedsearch A name of a saved search on the federated provider. The result set produced by an ad-hoc run of a saved search is a searchable dataset.
lastjob A name of a saved search on the federated provider that has been configured to run on a schedule. The result set for the last job run for a scheduled search is a searchable dataset.
datamodel A name of a data model on the federated provider. The set of events defined by a data model is a searchable dataset.

Returned values

Name Description
name Specifies the name of the federated index. Uses the syntax federated:<index_name>.
federated.provider Specifies the federated provider that contains the dataset to which this federated index maps.
federated.dataset Specifies the dataset on the federated.provider to which this federated index maps. Each federated index maps to one dataset on a federated provider. The dataset is identified by its type and name, using the following syntax: <type>:<dataset_name>.


Possible values for <type> are index, savedsearch, lastjob, and datamodel.

Remote dataset type Dataset name More information
index A name of an events or metrics index on the federated provider. Each remote index is a searchable dataset.
savedsearch A name of a saved search on the federated provider. The result set produced by an ad-hoc run of a saved search is a searchable dataset.
lastjob A name of a saved search on the federated provider that has been configured to run on a schedule. The result set for the last job run for a scheduled search is a searchable dataset.
datamodel A name of a data model on the federated provider. The set of events defined by a data model is a searchable dataset.

Example request and response
Update the dataset mapping for the federated:remote_index_df_1 federated index.

XML Request

curl -k -u admin:changeme  https://localhost:8126/services/data/federated/index/federated:remote_index_df_1 -d federated.dataset=index:index_df_1_new

XML response

<entry>
    <title>federated:remote_index_df_1</title>
    <id>https://localhost:8126/servicesNS/nobody/search/data/federated/index/federated%3Aremote_index_df_1</id>
    <updated>1970-01-01T00:00:00+00:00</updated>
    <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aremote_index_df_1" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aremote_index_df_1" rel="list"/>
    <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aremote_index_df_1/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aremote_index_df_1" rel="edit"/>
    <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aremote_index_df_1" rel="remove"/>
    <link href="/servicesNS/nobody/search/data/federated/index/federated%3Aremote_index_df_1/move" rel="move"/>
    <content type="text/xml">
      <s:dict>
        <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>*</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">1</s:key>
            <s:key name="sharing">app</s:key>
          </s:dict>
        </s:key>
        <s:key name="federated.dataset">index:index_df_1_new</s:key>
        <s:key name="federated.provider">provider-1</s:key>
      </s:dict>
    </content>
  </entry>

DELETE

Deletes a definition for a specific {federated_index_name}.

Request parameters
None specific to this method.

Returned values
None specific to this method.

Example request and response

Remove the my_federated_index stanza from indexes.conf.

XML Request

curl -k -u admin:changeme -X DELETE https://localhost:8089/services/data/federated/index/federated:my_federated_index

XML response

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>federated-index</title>
  <id>/services/data/federated/index</id>
  <updated>2021-04-27T12:57:06-07:00</updated>
  <generator build="aa7e77c0d232b8ec1a8c12ceeda95e0bfe3c3f1c" version="20210423"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/data/federated/index/_new" rel="create"/>
  <link href="/services/data/federated/index/_reload" rel="_reload"/>
  <link href="/services/data/federated/index/_acl" rel="_acl"/>
  <opensearch:totalResults>0</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
</feed>
Last modified on 12 January, 2024
PREVIOUS
Deployment endpoint descriptions
  NEXT
Input endpoint descriptions

This documentation applies to the following versions of Splunk® Enterprise: 9.1.0, 9.1.1, 9.1.2, 9.1.3


Was this documentation topic helpful?


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