drbd-reactorctl(1)

DRBD-REACTORCTL(1)

General Commands Manual

DRBD-REACTORCTL(1)

NAME

drbd-reactorctl — Control the drbd-reactor daemon and its plugins

SYNOPSIS

drbd-reactorctl [--config CONFIG] subcommand

edit [--disabled] [--force] [--type TYPE] file

enable [file ...]

disable [--now] [file ...]

status [--resource] [--verbose] [--json] [file ...]

evict [--delay] [--force] [--keep-masked] [--unmask] [file ...]

cat [file ...]

restart [--with-targets] [file ...]

`rm`	[`--force`] [`--disabled`] [`file ...`]

`ls`	[`--disabled`] [`file ...`]

start-until until file

generate-completion SHELL

DESCRIPTION

The drbd-reactorctl utility is used to control the local drbd-reactor(1) daemon or a cluster of daemons (see CLUSTER for details).

It is important to note that this utility only operates on plugin snippets (configured via snippets in the main configuration file). Existing plugin configurations in the main configuration file should be moved to snippets by the user.

The file arguments shown in SYNOPSIS can be specified as absolute path, or as the basename. The suffixes ".disabled" and ".toml" are optional. These get stripped and readded by the utility accordingly, see EXAMPLES for details.

Global arguments are:

-c, --config CONFIG: Main configuration file, defaults to /etc/drbd-reactor.toml
--context CONTEXT: Select a cluster context. Commands are then usually executed on all nodes in the given context. Subcommands might implement a behavior that is different from simple parallel execution (check the subsections of the subcommands for more details). The contexts none and local are reserved and can be used to temporarily disable the default context.
--nodes NODES: Only use the selected nodes from the given cluster context. Nodes are separated by commas.

The subcommands and their arguments are as follows:

edit

edit an existing plugin configuration or create a new one from a template.

--disabled: Edit a disabled file
-f, --force: Override sanity checks (e.g., topmost unit not a mount unit).
-t, --type promoter | prometheus | debugger | umh | agentx: Type of the plugin to create from template. The default is promoter.

Currently this command is not context/cluster aware, so --context and --nodes are ignored.

enable

enable a currently disabled plugin.

disable

disable a currently enabled plugin.

--now: In case of a promoter plugin also disable the target unit. You might want to use evict instead.

status

print the status of a plugin. In case of the promoter plugin the symbols and colors follow the ones from systemctl(1) status.

-r, --resource resource...: In case of a promoter plugin limit to these DRBD resources.
--verbose: verbose output depending on the plugin type.
--json: output machine parsable json output.

evict

Evicts a promoter resource from the currently active node.

-d, --delay: Positive number of seconds to wait for peer takeover.
-f, --force: Override sanity checks (multiple plugins per snippet/multiple resources per promoter).
-k, --keep-masked: Usually evict tries to evict the resource from the node but does not take further actions to avoid that the resource becomes active on that node again (e.g., fail-back). With this option the target unit is temporarily masked via systemd This makes it impossible to start the unit on the local node, which might be beneficial for maintenance. Masking is cleared after reboot, or after evict --unmask.
-u, --unmask: Unmasks all target units and tries to start them. It does not run any evictions on its own, it is used to clear previous evict --keep-masked operations.

Currently this command is not context/cluster aware, so --context and --nodes are ignored.

cat

cat the toml configuration of a plugin. Tries to use a pretty printer (e.g., bat) if available.

restart

restarts the given plugins or the daemon itself if no files are given.

--with-targets: also stop the drbd-service@.target for promoter plugins, might get started on different node.

rm

removes the given plugins and reloads the daemon.

-f, --force: Do not ask for confirmation
--disabled: Remove a disabled plugin.

ls

lists activated plugins.

--disabled: Also list disabled plugins.

start-until

starts a promoter generated target unit until (including) the given entry name in the start list or a given index. Using an index number is especially useful if one wants to stop at a OCF unit. An example use for a highly-available LINSTOR controller might look like this:

# drbd-reactorctl cat linstor_db | grep ^start
Displaying /etc/drbd-reactor.d/linstor_db.toml...
start = ["var-lib-linstor.mount", "linstor-controller.service"]
# drbd-reactorclt disable --now linstor_db # on all nodes

After the service is disabled on all nodes one can now start parts of the target on one node. In our example let's assume the admin wants to manually alter the database of the LINSTOR controller. For that she wants the DRBD device to be promoted and mounted, but the LINSTOR controller itself should be kept stopped.

# drbd-reactorclt start-until var-lib-linstor.mount linstor_db
INFO: To resume normal operation, execute:
- systemctl start drbd-services@linstor_db.target # on this node
- drbd-reactorctl enable /etc/drbd-reactor.d/linstor_db.toml.disabled # on all cluster nodes

The command will generate all the usual overrides and then start the implicit service responsible for DRBD device promotion and all the services (with their overrides) in the start list until and including the one given on the command line. After you are done, follow the instructions that start-until printed on the standard output.

generate-completion

Generate tab completion script for SHELL and write it to stdout. Supported shells are zsh | bash | fish | powershell | elvish

CLUSTER

Users can define cluster contexts via toml files in the locations specified in the FILES section. Such toml files consist of nodes entries that themselves have fields for hostname and user. Usually one does not need to set the specific fields as they have sane defaults: The name of the node entry is used as hostname if not otherwise specified, and root is the default user. If a cluster context is given or default.toml exists commands are executed on all nodes defined for that context. Execution is carried out in parallel via ssh.

A simple configuration can look like this:

cat ~/.config/drbd-reactorctl/production.toml
[nodes."alpha.mynet"]
[nodes."beta.mynet"]
[nodes."gamma.mynet"]

Node names should follow the output of uname -n and also please make sure to quote node names containing dots.

It is also possible to define a command that is executed to generate the nodes list via nodes-script. These commands, usually simple shell scripts, are expected to be stored in the same directory as the toml files. The scripts are expected to generate a valid nodes list as documented above on stdout. Such a configuration would then look like this:

cat ~/.config/drbd-reactorctl/linstor.toml
nodes-script="linstor.sh"

FILES

$XDG_CONFIG_HOME/drbd-reactorctl/: Default directory for context files in toml format.
$XDG_CONFIG_HOME/drbd-reactorctl/default.toml: If this file exists (usually a symlink to another toml file), it will be used by default.

If $XDG_CONFIG_HOME is not set or empty, config files get looked up in $HOME/.config/drbd-reactorctl/

EXAMPLES

drbd-reactorctl edit -t prometheus myprometheus
drbd-reactorctl restart myprometheus.toml
drbd-reactorctl restart myprometheus
drbd-reactorctl status /etc/drbd-reactor.d/myprometheus.toml
drbd-reactorctl disable --now mylinstorpromoter
drbd-reactorctl evict --keep-masked
drbd-reactorctl evict --unmask mylinstorpromoter
drbd-reactorctl --context production --nodes alpha,gamma status --verbose

AUTHORS

The drbd-reactorctl(1) program was written by the following authors:
Roland Kammerer <rck@linbit.com>

July 22, 2026

Linux 6.12.85-6.12-alt1