diff options
Diffstat (limited to 'doc/wiki/Director.txt')
| -rw-r--r-- | doc/wiki/Director.txt | 366 |
1 files changed, 366 insertions, 0 deletions
diff --git a/doc/wiki/Director.txt b/doc/wiki/Director.txt new file mode 100644 index 0000000..1ffa364 --- /dev/null +++ b/doc/wiki/Director.txt @@ -0,0 +1,366 @@ +Director +======== + +Director can be used by <Dovecot's IMAP/POP3/LMTP proxy> +[PasswordDatabase.ExtraFields.Proxy.txt] to keep a temporary user -> mail +server mapping. As long as user has simultaneous connections, the user is +always redirected to the same server. Each proxy server is running its own +director process, and the directors are communicating the state to each others. +Directors are mainly useful for setups where all of the mail storage is seen by +all servers, such as with NFS or a cluster filesystem. + +First test non-director proxying +-------------------------------- + +The director is simply a small add-on for Dovecot proxy. Before configuring +director, you should test that a simple proxying setup with static destination +server works. See the <Proxy> [PasswordDatabase.ExtraFields.Proxy.txt] page for +more information about how to configure it. If you have a simple setup, you can +test this easily using a static passdb: + +---%<------------------------------------------------------------------------- +passdb { + driver = static + args = proxy=y host=10.2.0.20 nopassword=y +} +---%<------------------------------------------------------------------------- + +Once finished testing, remember to remove the "host" field. + +Servers +------- + +You need one or more servers assigned for Dovecot proxies. The same servers +could also act as backends handling the mails, but you need to run <two +separate Dovecot configurations> [RunningDovecot.txt] in different ports. This +may get a bit confusing, so it's not recommended (although v2.1 makes it easier +with 'instance_name' setting). + +The directors are going to connect to each others in a ring. For example if you +have servers called A, B and C, director will create connections A->B, B->C and +C->A. + +Director configuration +---------------------- + +In example configuration you can configure director from +'conf.d/10-director.conf'. + +Listeners +--------- + +Configure the listeners that director requires: + +---%<------------------------------------------------------------------------- +service director { + unix_listener login/director { + mode = 0666 + } + fifo_listener login/proxy-notify { + mode = 0600 + user = $default_login_user + } + # NOTE: director-userdb socket is actually used only for passdb lookups, not +userdb lookups + unix_listener director-userdb { + mode = 0600 + } + inet_listener { + port = 9090 + } + ## uncomment this if you want to use + ## doveadm director status -a ip:9091 + #inet_listener director-doveadm { + # port = 9091 + #} +} +---%<------------------------------------------------------------------------- + +The port 9090 will be used for listening and connecting to other directors. +You're free to use any port number you want. + +Configuring list of director servers +------------------------------------ + +List all of your directors in 'director_servers' setting separated by spaces. +You can use: + + * IP addresses + * hostnames + * hostnames that expand to multiple IPs (e.g. you could have a "directors-all" + DNS entry that expands to all directors' IPs) + +You can also add :port after the IP/host. The default port is the same as what +director service's inet_listener is using (the port 9090 above). + +Note that the same director must not be listed multiple times with different +IPs. This especially means that a hostname can't expand to both IPv4 and IPv6 +address. Otherwise Dovecot becomes confused about what directors actually +exist. This also means that a single director ring must use either IPv4 or IPv6 +addresses, but not both at the same time. + +For example if you have 3 directors, you could set: + +---%<------------------------------------------------------------------------- +director_servers = 10.1.0.2 10.1.0.3 10.1.0.4 +---%<------------------------------------------------------------------------- + +Configuring list of mail servers +-------------------------------- + +List all of your backend mail servers in 'director_mail_servers' setting +separated by spaces. You can use: + + * IP addresses + * IP ranges (e.g. 10.2.0.10-10.2.0.30) + * hostnames + * hostnames that expand to multiple IPs + +For example if you had 20 mail servers with consecutive IPs: + +---%<------------------------------------------------------------------------- +director_mail_servers = 10.2.0.11-10.2.0.30 +---%<------------------------------------------------------------------------- + +Enabling director +----------------- + +Enable director for the wanted login services by telling them to connect to +director socket instead of the default login socket: + +---%<------------------------------------------------------------------------- +service imap-login { + executable = imap-login director +} +service pop3-login { + executable = pop3-login director +} +---%<------------------------------------------------------------------------- + +Consistent hashing should be enabled for new director clusters. It's not +possible to change this setting without a complete director cluster shutdown. +Using it reduces users being moved around when doing backend changes. + +---%<------------------------------------------------------------------------- +director_consistent_hashing = yes # Supported by v2.2.16+ +---%<------------------------------------------------------------------------- + +If you want to enable director for LMTP, also set: + +---%<------------------------------------------------------------------------- +# LMTP first does a passdb lookup to to see if there's a proxy field returned. +# If not, it fallbacks to doing userdb lookup. +lmtp_proxy = yes + +protocol lmtp { + # NOTE: director-userdb socket is actually used only for passdb lookups, not +userdb lookups + auth_socket_path = director-userdb +} + +# If you want lmtp-proxy listening on the network, uncomment the following: +#service lmtp { +# inet_listener lmtp { +# port = 24 +# } +#} +---%<------------------------------------------------------------------------- + +By default LMTP proxy connects to the same port in backend as what was used for +the incoming connection. + +Other settings +-------------- + +Directors redirect a user to the same server always the user has active +connections. The redirection is also done for a while after the last connection +already disconnected. This is mainly to avoid trouble with NFS caches that +haven't yet expired. You can configure this setting from: + +---%<------------------------------------------------------------------------- +director_user_expire = 15 min +---%<------------------------------------------------------------------------- + +'doveadm director kick' and 'doveadm director move' need to be able to connect +to the 'ipc' socket. Make sure the director process can do it: + +---%<------------------------------------------------------------------------- +service ipc { + unix_listener ipc { + user = dovecot # This is already the default in v2.3.1+ + } +} +---%<------------------------------------------------------------------------- + +Passdb configuration +-------------------- + +Your passdb must return "proxy" <extra field> +[PasswordDatabase.ExtraFields.txt], otherwise director doesn't do anything. + +Director works by adding a "host" extra field to the auth reply, which contains +the temporary destination mail server. This "host" field isn't added if the +passdb lookup already returns "host". This allows configuring some users to be +always proxied to a specific server. + +If the backend servers verify password, you can use static passdb for director: + +---%<------------------------------------------------------------------------- +passdb { + driver = static + args = proxy=y nopassword=y +} +---%<------------------------------------------------------------------------- + +Note that while this is the simplest director configuration, users will be +assigned to a backend before they have been authenticated. A director +configured this way can be attacked by sending it a large number of unknown +users. To prevent this, the director should be configured to authenticate the +user and might make use of a master password to log into the backend servers. + +Doveadm server +-------------- + +Use these settings for both director and backends: + +---%<------------------------------------------------------------------------- +service doveadm { + inet_listener { + # any port you want to use for this: + port = 24245 + } +} + +local 10.10.10.0/24 { + # password to use for client authentication + doveadm_password = secret + # allow client to only use specified list of commands (default is all): + #doveadm_allowed_commands = +} +---%<------------------------------------------------------------------------- + +The director also needs the following configuration: + +---%<------------------------------------------------------------------------- +# same port as doveadm's inet_listener +doveadm_proxy_port = 24245 + +protocol doveadm { + # NOTE: director-userdb socket is actually used only for passdb lookups, not +userdb lookups + auth_socket_path = director-userdb +} +---%<------------------------------------------------------------------------- + +Now you can run doveadm commands on the director, and it'll run them +automatically on the correct backend server. + +Health monitoring of backend servers +------------------------------------ + +Brad Davidson has written a small daemon for monitoring backend servers, and +disable/enable them on demand. +Ref:https://dovecot.org/list/dovecot/2010-August/051946.html + +Forcefully moving users to a different backend +---------------------------------------------- + +This is useful if you need to do maintenance on one of the backend servers and +want (active) clients to move to a different backend: + + 1. Disable any watchdog system that will undo changes you make to backend + server weights, such as poolmon. + * Not needed if the watchdog is new enough to use HOST-UP/HOST-DOWN + commands rather than change weights. + 2. Set the weight of the backend server to be worked on to 0: 'doveadm + director add <backend server ip> 0' + 3. Flush current assignments to disable new connections to this backend: + 'doveadm director flush <backend server ip>' + * This will also kick the existing connections to the backend in v2.2.19+. + +Most IMAP clients will silently just reconnect to the (new backend) server +after being kicked (at least Apple Mail 6.0 and Thunderbird 14.0). + +For moving specific users to other servers (e.g. because there are too many +"heavy users" assigned to the same backend), you can use 'doveadm director +move' command in v2.0.14+. This requires the ipc permissions to be configured +correctly (see above). + +Tags +---- + +(Requires v2.2.16+) + +*WARNING*: This feature isn't working perfectly in v2.2.26.1 and older. If two +users with different tags have the same 32bit hash, they may end up going to +the wrong tag's backend. + +With tags you can use a single director ring to serve multiple backend +clusters. Each backend cluster is assigned a tag name, which can be anything +you want. By default everything has an empty tag. A passdb lookup can return +"director_tag" field containing the wanted tag name. If there aren't any +backend servers with the wanted tag, it's treated the same as if there aren't +any backend servers available (= wait for 30 secs for a backend and then return +temporary failure). + +Tags can be added to configuration by adding @tag suffix to IPs/hosts. For +example: + +---%<------------------------------------------------------------------------- +director_mail_servers = 10.0.0.100-10.0.0.110@name1 10.0.0.120@name2 +---%<------------------------------------------------------------------------- + +"doveadm director add" can also add tags either with @tag suffix or with -t +parameter. "doveadm director status user@domain" requires giving the user's +correct tag with -t parameter or the results won't be correct (empty tag's +results are shown). Tags can't currently be changed for an existing host +without removing it first. + +Director and Backend in same server (broken) +-------------------------------------------- + +NOTE: This feature never actually worked. It would require further development +to fix (director would need to add "proxy" field to extra fields and notify +auth that the auth_request can be freed). + +Have the passdb lookup return 'director_proxy_maybe=y'. LMTP however doesn't +currently support mixing recipients to both being proxied and store locally. + +Flush socket +------------ + +(Requires v2.2.26+) + +This allows calling a script for each user (hash) that is moved between +backends. This is triggered by "doveadm director move" and "doveadm director +flush" commands. What happens is: + + * User's connections are kicked from the director cluster + * Flush socket is called and waited on. + * User logins are delayed until the flush socket is finished, or the user move + times out after 30 seconds (hardcoded). + * Only the director that initiated the doveadm command will call the flush + socket. + * director_user_kick_delay is ignored by the initiating director, but used + by the other directors. + +Configuration: + +---%<------------------------------------------------------------------------- +director_flush_script = user-flush +service user-flush { + executable = script /usr/local/bin/user-flush.sh + unix_listener user-flush { + user = dovecot + } +} +---%<------------------------------------------------------------------------- + +The user-flush.sh will receive as parameters: + + * "FLUSH" + * username hash + * old host's IP + * new host's IP + +(This file was created from the wiki on 2019-06-19 12:42) |