doveadm-cluster-user(1) - Utility actions for Palomar users

SYNOPSIS

doveadm [GLOBAL OPTIONS] cluster user access [-u user | -A | -f file | --no-userdb-lookup] [-i]

doveadm [GLOBAL OPTIONS] cluster user delete user

doveadm [GLOBAL OPTIONS] cluster user move backend [--direct] user dest-host

doveadm [GLOBAL OPTIONS] cluster user move site [--direct] [--keep-preferred] user dest-site

doveadm [GLOBAL OPTIONS] cluster user move status

doveadm [GLOBAL OPTIONS] cluster user batch move backend [--id id] [--min-last-moved age] [--reason reason] [--max-parallel-moves n] (--count users | --all [--status offline|standby]) dest-host [dest-host ...]

doveadm [GLOBAL OPTIONS] cluster user batch move site [--id id] [--min-last-moved age] [--preferred-site name] [--keep-preferred] [--reason reason] [--max-parallel-moves n] (--count users | --all [--status offline|standby]) dest-site [dest-site ...]

doveadm [GLOBAL OPTIONS] cluster user batch move stop

doveadm [GLOBAL OPTIONS] cluster user batch move status

doveadm [GLOBAL OPTIONS] cluster user status user

DESCRIPTION

doveadm cluster user can be used to run actions that interact with Palomar users.

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.

-A

If the -A option is present, the command will be performed for all users. Using this option in combination with system users from userdb { driver = passwd } is not recommended, because it contains also users with a lower UID than the one configured with the first_valid_uid setting.

When the SQL userdb module is used, make sure that the userdb_sql_iterate_query setting matches your database layout.

When using the LDAP userdb module, make sure that the userdb_fields and userdb_ldap_iterate_fields settings match your LDAP schema. Otherwise doveadm(1) will be unable to iterate over all users.

-F file

Execute the command for all the users in the file. This is similar to the -A option, but instead of getting the list of users from the userdb, they are read from the given file. The file contains one username per line.

--no-userdb-lookup

Do not perform userdb lookup. Use the USER environment variable to specify the username.

-u user/mask

Run the command only for the given user. It's also possible to use '*' and '?' wildcards (e.g. -u *@example.org).

COMMANDS

cluster user access

doveadm [GLOBAL OPTIONS] cluster user access [-u user | -A | -F file | --no-userdb-lookup] [-i]

Perform cluster lookup for the user (or users). Displays the host name or IP address of the backend which the user ended up. This command can be run from either a proxy or a backend. This command is also used internally to finish user moves.

You can use the -i parameter to display backend's IP rather than host name.

cluster user delete

doveadm [GLOBAL OPTIONS] cluster user delete user

Deletes a user record from GeoDB.

cluster user move backend

doveadm [GLOBAL OPTIONS] cluster user move backend [--direct] user dest-host

Initiates moving user to a different backend. The move is added to the queue of user moves, and it will finish on background. This command only moves the user from the backend where it is run from, i.e. the command should be run on the user's current backend.

--direct will update the user's new backend immediately to GeoDB without performing any user moving (kicking of existing sessions or flushing metacache). This is intended for testing and troubleshooting purposes only, and should not be normally used.

cluster user move site

doveadm [GLOBAL OPTIONS] cluster user move site [--direct] [--keep-preferred] user dest-site

Initiates moving user to a different site. The move is added to the queue of user moves, and it will finish on background. This command only moves the user from the backend where it is run from, i.e. the command should be run on the user's current backend.

--direct will update the user's new site immediately to GeoDB without performing any user moving (kicking of existing sessions or flushing metacache). This is intended for testing and troubleshooting purposes only, and should not be normally used.

--keep-preferred disables changing the user's preferred site. This is used to temporarily move users to different sites, e.g. for load-balancing purposes.

cluster user move status

Output the status of the current user move queue.

cluster user batch move backend

doveadm [GLOBAL OPTIONS] cluster user batch move backend [--id id] [--min-last-moved age] [--reason reason] [--max-parallel-moves n] (--count users | --all [--status offline|standby]) dest-host [dest-host ...]

Initiates moving a number of users to different backends which will finish in background. If the command is run again while a batch (backend or site) move is already in progress, the previous batch move is aborted.

The user moves are equally distributed to the list of given destination backends.

--id specifies a UUID for the move operation. By default a new ID is generated. The moving status is visible in GeoDB's move_* fields.

--min-last-moved specifies a time interval (e.g. "1 hour") for the minimum age of the user's last-moved timestamp. This is used to avoid moving the same users too often.

--reason specifies a human readable reason why the move is performed. This is visible in logs, cluster_user_batch_move_finished event and doveadm cluster user batch move status output.

--max-parallel-moves specifies the maximum number of user moves that can run in parallel for this batch move. By default there is no limit for the batch. Regardless of this parameter, the total number of parallel moves is limited by the `cluster-user-move` service's service_process_limit.

--count specifies the number of users to move. Alternatively, --all moves all the rest of the users in the backend.

--status can be used to change the backend status after all users have been moved out. This can be used only together with the --all parameter.

cluster user batch move site

doveadm [GLOBAL OPTIONS] cluster user batch move site [--id id] [--min-last-moved age] [--preferred-site name] [--keep-preferred] [--reason reason] [--max-parallel-moves n] (--count users | --all [--status offline|standby]) dest-site [dest-site ...]

Initiates moving a number of users to different sites which will finish in background. If the command is run again while a batch (backend or site) move is already in progress, the previous batch move is aborted.

The user moves are equally distributed to the list of given destination sites.

--id specifies a UUID for the move operation. By default a new ID is generated. The moving status is visible in GeoDB's move_* fields.

--min-last-moved specifies a time interval (e.g. "1 hour") for the minimum age of the user's last-moved timestamp. This is used to avoid moving the same users too often.

--preferred-site moves only users with a given preferred site. This is used by Controller to move users back to their preferred sites.

--keep-preferred disables changing the users' preferred sites. This is used to temporarily move users to different sites, e.g. for load-balancing purposes.

--reason specifies a human readable reason why the move is performed. This is visible in logs, cluster_user_batch_move_finished event and doveadm cluster user batch move status output.

--max-parallel-moves specifies the maximum number of user moves that can run in parallel for this batch move. By default there is no limit for the batch. Regardless of this parameter, the total number of parallel moves is limited by the `cluster-user-move` service's service_process_limit.

--count specifies the number of users to move. Alternatively, --all moves all the rest of the users in the backend.

--status can be used to change the backend status after all users have been moved out. This can be used only together with the --all parameter.

cluster user batch move stop

Stop the currently running user batch move.

cluster user batch move status

Output the status of the currently running user batch move.

cluster user status

doveadm [GLOBAL OPTIONS] cluster user status user

Displays status information of a user.

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)