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

SYNOPSIS

doveadm [GLOBAL OPTIONS] cluster site add [ --id id ] [ --tag tag ] [ --load-balancer host ] name

doveadm [GLOBAL OPTIONS] cluster site remove name

doveadm [GLOBAL OPTIONS] cluster site update [ --status online|offline|standby|evacuate ] [ --load-balancer host ] --self | name

doveadm [GLOBAL OPTIONS] cluster site status name

doveadm [GLOBAL OPTIONS] cluster site list

doveadm [GLOBAL OPTIONS] cluster site force-move start [--id id] name percentage dest-site [dest-site ...]

doveadm [GLOBAL OPTIONS] cluster site force-move update name percentage

doveadm [GLOBAL OPTIONS] cluster site force-move stop name

doveadm [GLOBAL OPTIONS] cluster site recover [--id id] name percentage

DESCRIPTION

doveadm cluster site can be used to run actions that interact with and modify Palomar sites.

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.

COMMANDS

cluster site add

doveadm [GLOBAL OPTIONS] cluster site add [--id id] [--tag tag] [--load-balancer host] name

Adds a new site to cluster. Load balancer is the host or IP address where another site's proxy connects to do site to site connections.

New sites are added in online state. UUID should not be used unless you are re-adding the same site.

cluster site remove

doveadm [GLOBAL OPTIONS] cluster site remove name

Remove a site. This currently has no safety checks, so be sure to remove first all of the site's backends and remove it from all users' preferred sites.

cluster site update

doveadm [GLOBAL OPTIONS] cluster site update [--status online|offline|standby|evacuate] [--load-balancer host] --self | name

Update site status and load balancer. The --self parameter can be used to target the local site. Changing the status also resets the site's force-move state.

cluster site list

doveadm [GLOBAL OPTIONS] cluster site list

List all sites.

cluster site reachability list

doveadm [GLOBAL OPTIONS] cluster site reachability list [src-site [dest-site]]

List reachability from src-site to dest-site. If no parameters are given all reachability is listed.

cluster site reachability update

doveadm [GLOBAL OPTIONS] cluster site reachability update src-site dest-site reachable

Update site reachability from src-site to dest-site. reachable can be set to yes or no.

doveadm cluster site force-move start

doveadm [GLOBAL OPTIONS] cluster site force-move start [--id id] name percentage dest-site [dest-site ...]

Forcibly start moving users out of the site 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-site during login. The picked dest-site is also based on the hash of the username. If the id is not given, a new unique UUID is generated.

Forcibly start moving users out of the site while they are logging in. This should be used only when a regular doveadm cluster user batch move site move doesn't work (e.g. site is down). Because force-move doesn't actively move all users in the site, the force-move never finishes by itself. The intent is that a force-move is started first with e.g. 1% as percentage and then (to prevent load spikes) slowly grown to 100% If the site is still not responding, the site should be marked offline. Normally the Controller does all this internally.

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

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

doveadm cluster site force-move update

doveadm [GLOBAL OPTIONS] cluster site force-move update name percentage

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

doveadm cluster site force-move stop

doveadm [GLOBAL OPTIONS] cluster site force-move stop name

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

doveadm cluster site recover

doveadm [GLOBAL OPTIONS] cluster site recover [--id id] name percentage

Start/stop recovering users to a site. When users with a preferred site name are logging in to a different site, the user is synchronously moved to the preferred site. Using percentage specifies the percentage of users are moved. The users are chosen based on id and percentage similarly as documented for doveadm cluster site force-move start.

SITE STATUS

Online

The site is reachable and accepts connections.

Offline

The site is unreachable.

Standby

The site is reachable, but does not accept connections.

Evacuate

The site is being evacuated of all users.

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)