Dovecot Pro
Search K

Appearance

Palomar: Administration ​

Site Operations ​

Adding a New Site ​

doveadm cluster site add adds a new site.

This will add a new site, in online status. You can specify site load balancer hostname, which is used when connections are routed from site to site. Tag is optional and will be used to match users and backends to a site shard. UUID should only be used when re-adding a site.

Initializing Groups in a New Site ​

Generally speaking, there is no need to initialize user groups. If a group does not exist yet, and a user of that groups logs in, the group is created automatically.

In case the need to manually create user groups arises, the doveadm cluster site init command can be used.

This command initializes a site by creating cluster_default_group_count user groups in GeoDB.

If --update is passed, this command removes existing groups and recreates them. It can thereby shrink or grow the number of groups depending on cluster_default_group_count. Users also get their groups unassigned when running with --update.

Note

Running with --update deletes existing groups and can take a while to run, so do NOT use this in a production environment.

Proxy Operations ​

Adding a New Proxy ​

Proxies within the same site have identical configuration. Adding a new proxy can be done by just launching a new proxy server and adding it into the load balancer's proxy pool.

Dovecot doesn't explicitly keep track of the proxies. However, they usually show up in the proxy_dest_stats table in GeoDB. It may be useful to manually remove those rows eventually.

Removing a Proxy ​

Remove the proxy server from the load balancer's proxy pool. Wait for a while so at least some of the connections finish on their own. Shutdown the server to forcibly disconnect the rest of the connections.

Backend Operations ​

Adding a New Backend ​

doveadm cluster backend add adds a new backend.

You can usually use just --self when adding the host you are on. Site (cluster_local_site) and hostname (cluster_backend_name) are inferred from config. The host will be added in standby mode. UUID should only be used when re-adding a backend.

Changing Backend Status ​

doveadm cluster backend update --status changes a backend status between offline/standby/online.

  • After controller determines that an offline backend is online again, it changes the status automatically to online.
  • standby backends are not automatically touched.
  • Neither offline nor standby backends receive any new connections. Existing connections are not kicked/moved, so normally backends shouldn't be set standby before the users are moved out.

Changing Load-Factor for Backend ​

doveadm cluster backend update --load-factor changes load-factor for a backend.

This can be used to (temporarily) reduce load from backend. Normally, load should always be set to 100. This is primarily used by the controller, which starts the group moves.

This setting is not accurate, so setting it to 99 or 78 will not have the expected effect.

Recommended values are 100, 50, and 0 for draining the host.

Evacuating Backend ​

doveadm cluster backend evacuate evacuates a backend with full speed:

  • Set backend load factor to 0
  • Set backend status to standby
  • Assign new random backends to groups currently using this backend, and start the moves immediately.

If you're not in a hurry to evacuate the backend immediately, it's better to only set the load factor to 0 and let the controller move the groups out of the backend slowly.

NOTE

This command exits without waiting for the moves to complete.

Removing a Backend ​

Backend Overloaded ​

Controller attempts to prevent backend from becoming overloaded by automatically moving groups out, but this may not always happen fast enough. To make it happen faster, you can change backend load-factor to a smaller number or even to 0 to remove all users from the backend. If this still isn't fast enough, use doveadm cluster backend evacuate command.

Disabling Automation ​

Disabling Controller Automation ​

⚠️ TODO

Provide non-k8s information here

Group Operations ​

Moving Group to Another Backend ​

doveadm cluster group move moves a group within a site.

The move is started by running the doveadm cluster group access command on the source backend.

NOTE

This command exits without waiting for the move to complete.

Listing All Groups ​

doveadm cluster group list lists all groups.

Checking Status of Group ​

doveadm cluster group status shows the current status of the group for a site.

User Operations ​

Checking User Status ​

doveadm cluster user status shows the current status for a user.

Accessing User ​

doveadm cluster user access accesses a backend as a given user and prints which backend it was.

This command can also cause a connection to the other site. This command is mainly used internally, but may be helpful also for debugging.

Moving User to Another Group ​

doveadm cluster user move moves the given user to the given group, and optionally to a different site.

The move is started by running the doveadm cluster user access command on the source backend.

NOTE

This command exits without waiting for the move to complete.

Autoscaler ​

Controller supports autoscaling. There are two autoscalers to choose from:

StaticAutoScaler ​

This is the default scaler, and returns number of backends in site.

LuaAutoScaler ​

This scaler calls method get_desired_number_of_backends(site) and expects it to return number of desired backends.

REST API Reference ​

Managing Controller Features ​

Controller offers feature control via the admin UI or HTTP API. The features that can be switched 'on', 'dryrun' or 'off' are:

  • "Backend Health Auto Handling": Automatically take backends down or bring them back up based on backend Z-score explained in Health Check
  • "Backend Load Balancing": Automatically move groups between backends to distribute load as explained in Load Balancing
  • "Metrics Export": Collect dovecot statistics and export them to Prometheus. If this feature is disabled, not metric is exported in response to Prometheus scraping of /metrics HTTP endpoint.

Feature settings are recorded in a table (cluster_settings) in GeoDB and are disabled by default. If the table is not present, all features are enabled for backward-compatibility.

To manage feature settings via the admin page, navigate to Site features page from the left pane. Note that you can only change feature settings of the local site via controller admin UI. To manage the features via the controller API, see OpenAPI documentation.

Monitoring ​

⚠️ TODO

Logging ​

⚠️ TODO

Doveadm Commands ​

Revision: 348734c

Last updated:

Copyright © Open-Xchange GmbH