Splunk® Enterprise

Distributed Search

Acrobat logo Download manual as PDF

Splunk Enterprise version 6.x is no longer supported as of October 23, 2019. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Acrobat logo Download topic as PDF

Control captaincy

You have considerable control over which members become captain, through these methods:

  • You can designate members as either "preferred captains" or "not preferred captains." When the cluster assigns captaincy, it attempts to assign it to a member with a preferred captain designation.
  • You can transfer captaincy from one member to another.

Use cases

It can be useful to control captaincy to handle a number of situations. For example:

  • You have one member that you want to always use as captain. Or conversely, you have one member that you never want to be captain.
  • You do not want the captain to perform any user-initiated ad hoc jobs. You can achieve this by designating one specific member as captain and keeping your third-party load balancer ignorant of that member.
  • You want to repair the state of the cluster. A quick way to do this is to switch to a new captain, because members join a new captain in a clean state.

The twin tools of preferred captaincy and captaincy transfer give you flexibility when you need to control captaincy. Although neither one can guarantee that you always maintain complete control over the location of your captain, they do limit the likelihood that the captain will reside on a member that is not optimal for your needs. And captaincy transfer offers the ability to transfer the captain to a new member as needed.

Specify captaincy preference

You can designate some members as preferred captains and others as non-preferred captains. When the cluster assigns captaincy, it attempts to assign it to a member with a preferred captain designation.

Designate captaincy preference

To specify a member's preference for captaincy, set the preferred_captain attribute in that member's server.conf file:

preferred_captain = true|false

This attribute defaults to true, which means that, by default, all members are preferred captains.

To limit the likelihood that the cluster will assign captaincy to a particular member, set that member's preferred_captain attribute to false:

preferred_captain = false

The cluster attempts to respect the captaincy preference.

Limitations of captaincy preference

The cluster tries to assign captaincy to a member with preferred_captain=true. However, it might not always be possible to assign captaincy to a preferred-captain member. For example, if none of the preferred-captain members are reachable over the network, then captaincy might be assigned to a member with preferred_captain=false.

During an election for a new captain, a non-preferred-captain member can briefly become the captain before captaincy transfers to a preferred-captain member. If no preferred-captain members are available, the non-preferred-captain member remains captain until a preferred-captain member becomes available.

Transfer captaincy

You can transfer captaincy from one member to another.

The use of captaincy transfer does not interfere with the normal captain election process, which always proceeds in response to the circumstances described in Captain election. If an election occurs and results in the captain moving to a member other than the one you want it to reside on, you can then invoke captaincy transfer to relocate the captain.

Change the captain

To transfer captaincy to a different member, run this command from the current captain:

splunk transfer shcluster-captain -mgmt_uri <URI>:<management_port> -auth <username>:<password>

Note the following:

  • The -mgmt_uri parameter specifies the URI and management port for the member that you want to transfer captaincy to. You must use the fully qualified domain name.
  • You must run this command on the current captain. If you run this command on any other member, such as the intended captain, you get an error message.
  • You do not need to restart any member after running the command.

To confirm that the captaincy transfer was successful, run the splunk show shcluster-status command from any member:

splunk show shcluster-status -auth <username>:<password>

Among other information returned, this command identifies the current captain.

Some ways to employ captaincy transfer in scripts

The splunk transfer shcluster-captain command can be useful for scripting certain cluster behavior. For example:

  • To ensure that captaincy stays with a particular member, you can implement a cron job that monitors the captain on a periodic basis. If the check detects a change in captain, it can automatically run the splunk transfer shcluster-captain command to return captaincy to the preferred member.
  • To implement rolling-restart-style functionality (for example, if deploying cluster updates through some third-party tool), you can transfer captaincy to another member prior to restarting the current captain.

Captaincy transfer and rolling-restarts

As of 6.3, the rolling-restart process automatically invokes captaincy transfer to prevent captaincy from changing during the restart process. Because of this action, the member that was captain prior to the restart ordinarily continues as captain after the restart. See Restart the search head cluster.

Captaincy transfer and static captain

Captaincy transfer is available only with a dynamic captain. For information on the use of a static captain for disaster recovery, see Use static captain to recover from loss of majority.

Last modified on 04 January, 2017
Configure a cluster member to run ad hoc searches only
Handle failure of a search head cluster member

This documentation applies to the following versions of Splunk® Enterprise: 6.5.0, 6.5.1, 6.5.2, 6.5.3, 6.5.4, 6.5.5, 6.5.6, 6.5.7, 6.5.8, 6.5.9, 6.5.10

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