Distributed Search

Transfer captaincy

You can transfer captaincy from one member to another.

Use cases

This can be useful in a number of situations:

• 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 do 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 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 invoke captaincy transfer to relocate the captain after the election.

Although captaincy transfer cannot guarantee that you always maintain complete control over the location of your captain, it does limit the likelihood that the captain will reside on a member that is not optimal for your needs. And it offers the ability to transfer the captain to a new member as needed.

Change the captain

To transfer captaincy to a different member, run this CLI 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 intended captain instance. You must use the fully qualified domain name. This parameter is required.
• 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 use the command to transfer captaincy to another node 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. Due to this, 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."