NuoDB Agent Tool

In the unusual situation that broker quorum is lost, the NuoDB Agent Tool helps you re-establish it. See About Broker Quorum.

Description

NuoDB Agent Tool (agent-tool) is a command line utility that lets you

The number of brokers recorded in the durable domain configuration is the number that NuoDB uses to determine whether there is a broker quorum. A broker quorum exists when a majority of the brokers in the domain are available to the other running brokers.

If the loss of a broker, perhaps due to a power outage, causes loss of a broker quorum then it is not possible to perform domain tasks such as starting a database process or adding a host to the domain. To re-establish broker quorum, you must remove the lost broker from the durable domain configuration. To do this, you shut down all surviving brokers and then invoke agent-tool on one of the surviving brokers. You use the agent-tool utility to ban the lost broker from continuing to be a member of the domain. When you restart any one of the surviving brokers then any banned brokers are removed from the durable domain configuration and no longer counted in the number used to determine whether there is a broker quorum.

For more information about re-establishing broker quorum, see Handling Failure.

In addition, there are tools for detecting failure, see Setting Up Failure Detection.

Syntax

agent-tool command [option]

Commands

membership

Specify the membership command to list the brokers in the domain or to ban a broker from continuing to be a member of the domain. If you specify no options then the membership command lists the brokers in the domain. This list does not include any brokers that have been banned. For example:

$ agent-tool membership
Server[0] [id = -8979880997462046783] [stableId = uuid:1bd3e439-7c48-4e69-8361-0dcf6cfe87c1] 
     [address = jdoe-mylinux.local/172.18.31.171:48004] (local)
$ 

For each broker in the domain, the tool lists the following information:

You can follow the membership command with one of the following options:

--ban stableId Ban a broker from continuing to be a member of the domain. Identify the broker to be banned by specifying the broker host's stable ID. You must shut down all brokers before you can ban a broker.
--ban-server id Ban a broker from continuing to be a member of the domain. Identify the broker to be banned by specifying its unique ID. You must shut down all brokers before you can ban a broker.
--list-banned Display a list of any banned brokers.
--list

Display a list of the brokers that are recorded in the durable domain configuration and not banned.

This is equivalent to invoking agent-tool membership without specifying an option. For example:

$ agent-tool membership --list 
Server[0] [id = -6778430328504974377] [stableId = uuid:03432284-0b57-48d4-a1ee-2d87a6ba03d7] [address = ip-172-31-34-74/54.88.137.63:48004] (local) 
Server[1] [id = -7693392600059268289] [stableId = uuid:4695f055-76a9-4e2e-953b=94310b93334f] [address = 127.0.0.1:48114] 
$

--help Display help.

state

Specify the state command to display or reset the local broker's state. You can follow the state command with one of the following options:

--show Displays the stable ID of the local broker's host.
--verbose Displays the stable ID of the local broker's host, the location of the Raft directory and the location of the file that contains the stable ID of the local host.
--reset

Deletes the durable domain configuration from the local broker. The broker must be shut down to reset its state.

Caution: Be cautious about using this option. You should reset broker state only in the following situations:
  • You are starting over by deleting all configuration data and all databases (but possibly keeping the archive directories). For example, this might be a single-user developer laptop with one broker running in the domain. If your archive directories are backed up then you can then reset broker state and then execute the NuoDB Manager command restore database.
  • You want to re-provision the entire domain.
  • You have a standalone host with its own broker running its own domain and you want to add the host to another domain. As part of the peering process, this broker will receive a copy of the new domain's durable domain configuration.

Execution of agent-tool state --reset is equivalent to specifying the --reset-broker-state option when you restart a broker.

--help Displays help.

Exit Code

Upon success, agent-tool with exit with exit code 0. Any usage error will set the exit code to 1. If the server ID is not found, membership ban will set exit code to 2.

Command Exit code Message
state --reset 1 Unable to move raft directory
state --reset 1 Unable to move stable ID file
membership --ban 2 Server [id = .. ] not found (NuoDB 2.3.2 and later)