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.

GLOBAL OPTIONS

Global doveadm(1) options:

-D

Enables verbosity and debug messages.

-O

Do not read any config file, just use defaults. The dovecot_storage_version defaults to the latest version, but can be overridden with -o.

-k

Preserve entire environment for doveadm, not just import_environment.

-v

Enables verbosity, including progress counter.

-i instance-name

If using multiple Dovecot instances, choose the config file based on this instance name.

See instance_name for more information.

-c config-file

Read configuration from the given config-file. By default it first reads config socket, and then falls back to /etc/dovecot/dovecot.conf. You can also point this to config socket of some instance running compatible version.

-o setting=value

Overrides the configuration setting from /etc/dovecot/dovecot.conf and from the userdb with the given value. In order to override multiple settings, the -o option may be specified multiple times.

-f formatter

Specifies the formatter for formatting the output. Supported formatters are:

flow

prints each line with key=value pairs.

json

prints a JSON array of JSON objects.

pager

prints each key: value pair on its own line and separates records with form feed character (^L).

tab

prints a table header followed by tab separated value lines.

table

prints a table header followed by adjusted value lines.

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:

• site: Site name
• id: UUID
• host: Host name
• status: See BACKEND STATUS
• load_factor: See the --load-factor parameter above
• user_count_approx: Approximate number of users in the backend. This is counted by listing users in metacache, which don't have redirect_host field. This may differ significantly from the number of users that are assigned to the backend in GeoDB users table.
• force_move: Force-moving status

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 should be used only when a regular doveadm cluster user batch move backend move doesn't work (e.g. backend is down, or excessively overloaded). Because force-move doesn't actively move all users in the backend, the force-move never finishes by itself. The intent is that a force-move is started first with e.g. 10% as percentage and then (to prevent load spikes) slowly grown to 100% If the backend is still not responding, the backend should be marked offline. Normally the Controller does all this internally.

The force-move 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. It also takes into account the destination backends' load factor. 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.

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.

REPORTING BUGS

Report bugs, including doveconf -n output, to the Dovecot Mailing List dovecot@dovecot.org. Information about reporting bugs is available at: https://dovecot.org/bugreport.html

SEE ALSO

doveadm-cluster(1)