Splunk® Enterprise

Search Manual

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.

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.
  • 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, select Settings, then 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.
    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.

In addition, if your federated searches will involve custom knowledge objects that you have defined, such as lookups or calculated fields, you need to ensure those knowledge objects are duplicated on the federated providers you intend to search. See Custom knowledge object coordination for standard mode federated providers.

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.

Last modified on 26 July, 2023
Custom knowledge object coordination for standard mode federated providers   Create a federated index

This documentation applies to the following versions of Splunk® Enterprise: 9.1.0


Was this topic useful?







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