Dovecot Pro
Search K

Appearance

Palomar: Administration ​

REST API Reference ​

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.

⚠️ TODO

Site name is required. Only provide Site ID in special cases, it is autogenerated by default. Site load balancer is needed if the site has an external load balancer.

Modifying a Site ​

⚠️ TODO

You can edit site name, site load balancer and site tag.

DANGER

The site name must match Dovecot configuration for the respective site, see cluster_local_site. Changing the site name to non-matching value will cause your cluster site to stop operating.

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.

INFO

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

Site Rebalance ​

⚠️ TODO

Cluster controller performs load balancing automatically. If necessary, you can also trigger extra load balancing.

Redistribute Users ​

⚠️ TODO

Cluster has users in multiple smaller groups. This is determined during cluster installation and bootstrap. You can change the number of groups using cluster controller.

Setting site features ​

⚠️ TODO

Cluster controller allows configuring site features, these are disabled by default.

Backend Health Auto Handling ​

⚠️ TODO

Controls error mitigation features of controller. If disabled, cluster controller will not offline broken hosts, or try to move users from degraded hosts.

Backend Load Balancing ​

⚠️ TODO

Controls automatic load balancing. If disabled, cluster controller will not attempt to move users between shards and user groups between hosts to balance load.

Metrics Export ​

⚠️ TODO

Controls providing Prometheus metrics. If disabled, the metrics endpoint in cluster controller will not work.

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.

⚠️ TODO

Host name is required, and must be resolvable by the controller. You cannot add a host by IP address, it must have valid host name. Only provide Backend ID in special cases, it is autogenerated by default.

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.

WARNING

This command exits without waiting for the moves to complete.

⚠️ TODO

If you need to drain a backend, the recommended way is to set load factor to 0, which will cause controller to drain the host from users. If you are in a hurry, you can use the evacuate button. This will trigger immediate move of all users to other backends

DANGER

Using the evacuate button can cause severe load on a site.

:::

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.

WARNING

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.

WARNING

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.

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: 321e940

Last updated:

Copyright © Open-Xchange GmbH