doveadm-cluster-backend(1) - Utility actions for Palomar backend

SYNOPSIS

doveadm [GLOBAL OPTIONS] cluster backend add [--id id] [--site host] --self | name

doveadm [GLOBAL OPTIONS] cluster backend remove --self | host

doveadm [GLOBAL OPTIONS] cluster backend update [--status online|offline|standby] [--load-factor <0..100>] --self | host

doveadm [GLOBAL OPTIONS] cluster backend status --self | host

doveadm [GLOBAL OPTIONS] cluster backend list

doveadm [GLOBAL OPTIONS] cluster backend force-move start [--id id] host percentage dest-host [dest-host ...]

doveadm [GLOBAL OPTIONS] cluster backend force-move update host percentage

doveadm [GLOBAL OPTIONS] cluster backend force-move stop host

DESCRIPTION

doveadm cluster backend can be used to run actions that interact with and modify Palomar backends.

Command specific options

--self

Target the same host where the command is ran from. Uses cluster_backend_name setting as the host name.

COMMANDS

cluster backend add

doveadm [GLOBAL OPTIONS] cluster backend add [--id id] [--site host] --self | name

Adds a new backend to cluster. New backends are added in standby state. UUID should not be used unless you are re-adding the same backend.

name

Must be a resolvable DNS name. Unresolvable DNS names and IPv4/v6 literal addresses will be rejected.

cluster backend remove

doveadm [GLOBAL OPTIONS] cluster backend remove --self | host

Remove a backend from cluster.

cluster backend update

doveadm [GLOBAL OPTIONS] cluster backend update [--status online|offline|standby] [--load-factor <0..100>] --self | host

Updates a backend's information.

--status

See BACKEND STATUS. Changing the status also resets the backend's force-move state.

--load-factor

Load factor is the approximate amount of site load in percentage that this backend gets allocated. This value is not exact, and requires Palomar Cluster Controller to work correctly.

Recommended values are 100, 75, 50, 25 and 0. Setting it to 0 will indicate that backend should be drained in Cluster Controller.

cluster backend status

doveadm [GLOBAL OPTIONS] cluster backend status --self | host

Shows the current status of the backend.

cluster backend list

doveadm [GLOBAL OPTIONS] cluster backend list [ --site host ]

Lists all backends in this cluster, including other sites. You can use optional --site parameter to specify site to list.

doveadm cluster backend force-move start

doveadm [GLOBAL OPTIONS] cluster backend force-move start [--id id] host percentage dest-host [dest-host ...]

Forcibly start moving users out of the backend while they are logging in. This works by getting a hash of the given id and username in the range 0..99, and comparing that to the given percentage. If the hash is below the percentage, the user will be moved to one of the dest-host during login. The picked dest-host is also based on the hash of the username. If the id is not given, a new unique UUID is generated.

The force-moving is tracked entirely in GeoDB, so this command can be used on any of the proxies or backends. The source backend does not need to be running for the force-moving to work.

The force-move state is cleared also when updating the backend's status with doveadm cluster backend update --status.

Normally this command is used internally by the controller.

doveadm cluster backend force-move update

doveadm [GLOBAL OPTIONS] cluster backend force-move update host percentage

Update a new percentage to an already started force-move.

doveadm cluster backend force-move stop

doveadm [GLOBAL OPTIONS] cluster backend force-move stop host

Stop an already started force-move. This is similar to updating the percentage to 0, but it also clears out the ID and dest-host fields in GeoDB.

BACKEND STATUS

online

The backend is reachable and accepts connections.

offline

The backend is unreachable.

standby

The backend is reachable, but does not accept connections.

SEE ALSO

doveadm-cluster(1)