Define a federated provider

To set up federated search on your local Splunk platform deployment, you must define one or more federated providers for that deployment. A federated provider definition enables your local deployment to establish a connection with a remote Splunk platform deployment. The federated provider definition is also where you select the provider mode, which determines how you will run your federated searches over that provider.

Prerequisites

• Read About federated search to familiarize yourself with federated search concepts and terminology.
• You must have a role with the admin_all_objects and indexes_edit capabilities to create a federated provider.
  • If you use Splunk Cloud Platform, the sc_admin role has these capabilities by default. See Define roles on the Splunk platform with capabilities in the Securing Splunk Cloud Platform manual.
  • If you use Splunk Enterprise, the admin role has these capabilities by default. See Define roles on the Splunk platform with capabilities in the Securing Splunk Enterprise manual.
• Gather the unique host name of the remote deployment that you want to set up as a federated provider. The format of the host name depends on whether your local deployment uses search head clustering. See the following table for the right host name format for your deployment type.

Deployment type	Uses search head clustering?	Host name format	Host name example
Splunk Cloud Platform	No	<stack name>.splunkcloud.com	buttercupgames.splunkcloud.com
Splunk Cloud Platform	Yes	shc1.<stack name>.splunkcloud.com	shc1.buttercupgames.splunkcloud.com
Splunk Enterprise	No	<deployment name>.splunk.com	buttercupgames.splunk.com
Splunk Enterprise	Yes	<deployment name>-shc.splunk.com or shc-<deployment name>.splunk.com	shc-buttercupgames.splunk.com or buttercupgames-shc.splunk.com

You can find the <stack name> or <deployment name> in the URL for the main stack of a Splunk platform deployment.

When you connect to a Splunk Cloud Platform federated provider that uses search head clustering, in most cases you will connect to the load balancer for the cluster when you use the URLs described above. The load balancer can handle the distribution of federated search data to and from the search head cluster members. The load balancer can also manage disruptions if individual search heads within the cluster go offline.

• Create a service account user on each remote deployment that you want to set up as a federated provider. You need the service account user name and password for the federated provider definition. See Service accounts and federated search security.

To run federated searches, Splunk Cloud Platform deployments require additional configuration from Splunk Support. This is true whether the Splunk Cloud Platform deployment is on the local or remote side of the federated search. If you are setting up federated search between two Splunk Cloud Platform deployments, you must contact Splunk Support for both deployments.

If you have a support contract, file a new case using the Splunk Support Portal at Support and Services. Otherwise, contact Customer Support.

Steps

1. On your local deployment, in Splunk Web, go to Settings > Federated Search.
2. On the Federated Providers tab, select Add Federated Provider.
3. Using the following table, specify the settings for your federated provider.
   

   Setting	Description	Default value
   Provider Type	Determines the federated provider type. Currently, this setting is fixed. You can define only federated providers that are remote deployments.	Splunk
   Provider Mode	Select the mode of the federated provider. For a comparison of the standard and transparent modes, see About federated search. 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. A remote deployment can be a transparent mode federated provider for one local deployment and a standard mode federated provider for a different local deployment.	Standard
   Provider Name	Select a unique name for the federated provider. The provider name can contain only alphanumeric characters and underscores. The provider name cannot be the string splunk by itself. You can use this string with other alphanumeric characters. For example, abcsplunk is a valid provider name. When you run federated searches, this Provider Name is added to your search results as the value of a field named splunk_federated_provider, enabling you to group or filter results by the federated providers that produced them. The splunk_federated_provider field appears in the Interesting Fields list in the Fields sidebar. See Federated provider names added to search results.	No default
   Remote Host	Provide the host name and port number for the federated provider, separated by a colon character. For example: buttercupgames.splunkcloud.com:8089. You can provide an IP address instead of a host name. You can provide any legitimate port number. 8089, the standard management port number, works for any federated provider. If you can't connect to port 8089 on a remote Splunk Cloud Platform deployment, contact your Splunk representative to check that the management port is open on the federated provider. For the purposes of federated search, communication between local and remote Splunk platform search heads is facilitated by an internal REST API endpoint.	No default
   Service Account Username and Service Account Password	If you do not already have a service account on the federated provider, create one. A service account is a dedicated user account that allows the federated search head on your local Splunk instance to search datasets on the federated provider. See Service accounts and federated search security. If you save a transparent mode federated provider definition with incorrect Service Account Username or Service Account Password values, you risk being locked out of the service account, which can prevent you from running searches. Be sure to use Test Connection to verify that you have provided accurate credentials. Fix connection issues before you save the definition.	No default
   Application Short Name	Applies only to standard mode federated providers. Specify the short name of an app to apply an app context to searches on the federated provider. When you run a federated search with this federated provider, the federated search applies the app context set by Application Short Name to the portion of the search that takes place on the federated provider. It ignores the app context of the local search head that the search originates from. If you leave this setting blank, Splunk software applies search, the short name of the Search & Reporting app, to this setting. See Set the app context for standard mode federated providers.	search

4. Select Test Connection to test the connection to the remote deployment that this federated provider definition is meant to set up.
   
   You should see a "Connection successful" message at the top of the dialog if the values that you have provided for the Provider Name, Remote Host, Service Account Username, and Service Account Password fields are correct. If you get an error message instead, it means one or more of those fields has been set incorrectly. Update the fields and repeat this step until you get the Connection successful message. If you are having trouble making a connection, see Troubleshoot a federated provider connection.
5. Select Save to save the federated provider configuration.

Troubleshoot a federated provider connection

If you are not able to get the Test Connection button to verify a connection between the federated provider and your local Splunk instance, try these troubleshooting methods.

• Make sure you have provided correct values for the Remote Host, Service Account User Name, and Service Account Password fields. Verify that you have created a service account user for the federated provider.
• There may be setup issues that require assistance from Splunk Customer Support, especially if you are trying to set up federated search from or to a Splunk Cloud Platform deployment. If you have a support contract, log in and file a new case using the Splunk Support Portal. Otherwise, contact Splunk Customer Support.

Avoid transparent mode lockouts

If you save a transparent mode federated provider definition with incorrect Remote Host, Service Account Username or Service Account Password information, you run the risk of being locked out of the service account by the Splunk Cloud Platform, which might remove your capability to run searches.

When the system locks your account, you have two options for unlocking it:

• If you have administrator permissions, you can unlock the account through Splunk Web. See Unlock a user account in Splunk Web in Securing the Splunk Platform.
• You can wait for the lockout timeout threshold to pass. When the lockout timeout threshold is reached, the system unlocks the account. The default lockout timeout threshold for the Splunk platform is 30 minutes. Your Splunk administrator may have defined a different threshold for your deployment.

Even after you unlock your account, you run the risk of being locked out again if you do not resolve the federated provider credential issue that caused the system to lock you out.

About creating multiple federated provider definitions for the same host name and port

The manner in which the Splunk software handles multiple federated provider definitions sharing the same host name and port differs depending on whether the federated provider definitions use standard mode or transparent mode.

Standard mode

You can create multiple standard mode federated provider definitions that share the same host name and port as long as they all have different Provider name values. You might do this if you want to create separate provider definitions for different app contexts on the same remote deployment. For more information, see Set the app context for standard mode federated providers.

Transparent mode

There is no use case for having multiple transparent mode federated providers share a host name and port. If you configure multiple transparent mode federated provider definitions for the same remote deployment, each time you run a search the Splunk software delivers an error message about this misconfiguration and randomly chooses which transparent mode federated provider to run the search over.

If the remote deployments you search over use Splunk Enterprise, this functionality is extended to detect when two or more transparent mode federated providers share the same search head cluster ID. For this extension to work, the service accounts for the transparent mode federated providers must have roles with the list_search_head_clustering capability.

Next step for a standard mode federated provider

After you define a standard mode federated provider, create one or more federated indexes and associate remote datasets from the federated provider to those federated indexes. For more information, see Create a federated index.

Next step for a transparent mode federated provider

After you define a transparent mode federated provider, you are ready to run federated searches. See Run federated searches.