diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 17:36:47 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 17:36:47 +0000 |
commit | 0441d265f2bb9da249c7abf333f0f771fadb4ab5 (patch) | |
tree | 3f3789daa2f6db22da6e55e92bee0062a7d613fe /doc/wiki/PasswordDatabase.ExtraFields.Proxy.txt | |
parent | Initial commit. (diff) | |
download | dovecot-0441d265f2bb9da249c7abf333f0f771fadb4ab5.tar.xz dovecot-0441d265f2bb9da249c7abf333f0f771fadb4ab5.zip |
Adding upstream version 1:2.3.21+dfsg1.upstream/1%2.3.21+dfsg1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/wiki/PasswordDatabase.ExtraFields.Proxy.txt')
-rw-r--r-- | doc/wiki/PasswordDatabase.ExtraFields.Proxy.txt | 307 |
1 files changed, 307 insertions, 0 deletions
diff --git a/doc/wiki/PasswordDatabase.ExtraFields.Proxy.txt b/doc/wiki/PasswordDatabase.ExtraFields.Proxy.txt new file mode 100644 index 0000000..e86d27d --- /dev/null +++ b/doc/wiki/PasswordDatabase.ExtraFields.Proxy.txt @@ -0,0 +1,307 @@ +Proxying +======== + +Dovecot supports proxying IMAP, POP3, <Submission.txt> (v2.3+), <LMTP.txt>, and +<ManageSieve> [Pigeonhole.ManageSieve.txt] connections to other hosts. The +proxying can be done for all users, or only for some specific users. There are +two ways to do the authentication: + + 1. Forward the password to the remote server. The proxy may or may not perform + authentication itself. This requires that the client uses only plaintext + authentication, or alternatively the proxy has access to users' passwords + in plaintext. + 2. Let Dovecot proxy perform the authentication and login to remote server + using the proxy's <master password> [MasterPassword.txt]. This allows + client to use also non-plaintext authentication. + +The proxy is configured pretty much the same way as <login referrals> +[PasswordDatabase.ExtraFields.Host.txt], with the addition of 'proxy' field. +The common fields to use for both proxying ways are: + + * 'proxy' and 'proxy_maybe': Enables the proxying. Either one of these fields + is required. + * 'proxy_maybe' can be used to implement "automatic proxying". If the proxy + destination matches the current connection, the user gets logged in + normally instead of being proxied. If the same happens with 'proxy', the + login fails with "Proxying loops" error. + * 'proxy_maybe' with LMTP requires v2.1.0+ + * 'proxy_maybe' with 'host=<dns name>' requires v2.1.2+. + * 'auth_proxy_self' setting in dovecot.conf can be used to specify extra + IPs that are also considered to be the proxy's own IPs. (v2.1.2+) + * 'proxy_always' can be used with 'proxy_maybe' to conditionally do + proxying to specified remote host (host isn't self) or to let director + assign a backend host (host is self). So basically this setting just + always sends the 'proxy' extra field to login process, but not + necessarily the 'host'. Useful when dividing users across multiple + director clusters. + * 'host=s': The destination server's *IP address*. This field is required. + * 'source_ip=s': The source IP address to use for outgoing connections. + (v2.2.14+) + * 'port=s': The destination server's port. The default is 143 with IMAP and + 110 with POP3. + * 'protocol=s': The protocol to use for the connection to the destination + server. This field is currently only relevant for LMTP: it can be used to + select either "lmtp" or "smtp". + * 'destuser=s': Tell client to use a different username when logging in. + * 'proxy_mech=s': Tell client to use this SASL authentication mechanism when + logging in. + * 'proxy_timeout': Abort connection after this many seconds. + * 'proxy_nopipelining': Don't pipeline IMAP commands. This is a workaround for + broken IMAP servers that hang otherwise. (v2.2.11+) + * 'proxy_not_trusted': IMAP/POP3 proxying never sends the ID/XCLIENT command + to remote. (v2.2.27+) + +You can use SSL/TLS connection to destination server by returning: + + * 'ssl=yes': Use SSL and require a valid verified remote certificate. + *WARNING: Unless used carefully, this is an insecure setting!* Before + v2.0.16/v2.1.beta1 the host name isn't checked in any way against the + certificate's CN. The only way to use this securely is to only use and allow + your own private CA's certs, anything else is exploitable by a + man-in-the-middle attack. + * Note that 'ssl_client_ca_dir' or 'ssl_client_ca_file' aren't currently + used for verifying the remote certificate, although ideally they will be + in a future Dovecot version. For now you need to add the trusted remote + certificates to 'ssl_ca'. + * *NOTE:* LMTP proxying supports SSL/TLS only since v2.3.1 - for older + versions any ssl/starttls extra field is ignored. + * *NOTE:* doveadm proxying doesn't support SSL/TLS currently - any + ssl/starttls extra field is ignored. + * 'ssl=any-cert': Use SSL, but don't require a valid remote certificate. + * 'starttls=yes': Use STARTTLS command instead of doing SSL handshake + immediately after connected. + * 'starttls=any-cert': Combine starttls and ssl=any-cert. + * Additionally you can also tell Dovecot to send SSL client certificate to the + remote server using 'ssl_client_cert' and 'ssl_client_key' settings in + 'dovecot.conf' (v2.0.17+). + +Set 'login_trusted_networks' to point to the proxies in the backends. This way +you'll get the clients' actual IP addresses logged instead of the proxy's. + +The destination servers don't need to be running Dovecot, but you should make +sure that the Dovecot proxy doesn't advertise more capabilities than the +destination server can handle. For IMAP you can do this by changing +'imap_capability' setting. For POP3 you'll have to modify Dovecot's sources for +now ('src/pop3/capability.h'). Dovecot also automatically sends updated +untagged CAPABILITY reply if it detects that the remote server has different +capabilities than what it already advertised to the client, but some clients +simply ignore the updated CAPABILITY reply. + +v2.2.14+: If your proxy handles a lot of connections (~64k) to the same +destination IP you may run out of TCP ports. The only way to work around this +is to use either multiple destination IPs or ports, or multiple source IPs. +Multiple source IPs can be easily used by adding them to the 'login_source_ips' +setting in 'dovecot.conf'. You can also use hostnames which expand to multiple +IPs. By prefixing the setting with "?" (e.g.'login_source_ips = +?proxy-sources.example.com') Dovecot will use only those IPs that actually +exist in the server, allowing you to share the same config file with multiple +servers. It's probably better not to include the server's default outgoing IP +address in the setting, as explained here +[https://idea.popcount.org/2014-04-03-bind-before-connect/]. + +v2.2.19+: To avoid reconnection load spikes when a backend server dies, you can +tell proxy to spread the client disconnections over a longer time period (after +the server side of the connection is already +disconnected).'login_proxy_max_disconnect_delay' setting in 'dovecot.conf' +controls this (disabled by default). + +v2.2.29+: You can forward arbitratry variables by returning them prefixed with +'forward_'. Dovecot will use protocol dependant way to forward these variables +forward and they will appear on the other side as 'forward_variable' Currently +IMAP/POP3 only feature. This feature requires that the sending host is in +login_trusted_networks. For IMAP the feature works by providing the variables +as part of ID command, such as 'i ID ( ... "x-forward-var" "value")'. For POP3 +the forwarding mecahism uses 'XCLIENT' with 'FORWARD=<base64 encoded blob of +forwarded variables>' + +See <Design.ParameterForwarding.txt> for more details on forwarding. + +Moving users between backends/clusters (v2.2.25+) +------------------------------------------------- + +A safe way to move users from one cluster to another is to do it like: + + * Set delay_until=<timestamp> <passdb extra field> + [PasswordDatabase.ExtraFields.txt] where <timestamp> is the current + timestamp plus some seconds into future (e.g. 31s). You may also want to + append e.g. "+5" for some load balancing if a lot of users are moved at + once. + * Set host=<new host> passdb extra field. This update should be atomic + together with the delay_until field. + * Use "doveadm proxy kick" or "doveadm director kick" to kick the user's + existing connections. + * The processes may still continue running in the backend for a longer + time. If you want to be absolutely sure, you could also run a script to + kill -9 all processes for the user in the backend. This of course has its + own problems. + +The idea here is that while the user's connections are being kicked and the +backend processes are finishing up and shutting down, new connections are being +delayed in the proxy. This delay should be long enough that the user's existing +processes are expected to die, but not so large that clients get connection +timeouts. A bit over 30 seconds is likely a good value. Once the delay_until +timestamp is reached, the connections continue to the new host. + +If you have a lot of users, it helps to group some of them together and do the +host/delay_until updates on a per-group basis rather than per-user basis. + +ID command forwarding (v2.2.29+) +-------------------------------- + +If you want to forward, for some reason, the IMAP ID command provided by the +client, set + +---%<------------------------------------------------------------------------- +imap_id_retain=yes +---%<------------------------------------------------------------------------- + +This will also enable client_id variable in variable expansions for auth +requests, which will contain the ID command as IMAP arglist. + +Password forwarding +------------------- + +If you don't want proxy itself to do authentication, you can configure it to +succeed with any given password. You can do this by returning an empty password +and 'nopassword' field. + +Master password +--------------- + +This way of forwarding requires the destination server to support master user +feature. The users will be normally authenticated in the proxy and the common +proxy fields are returned, but you'll need to return two fields specially: + + * 'master=s': This contains the master username (e.g. "proxy"). It's used as + SASL auhentication ID. + * Alternatively you could return 'destuser=user*master' and set + 'auth_master_user_separator = *'. + * 'pass=s': This field contains the master user's password. + +See <Authentication.MasterUsers.txt> for more information how to configure +this. + +OAuth2 forwarding +----------------- + +If you want to forward <OAuth2> [PasswordDatabase.oauth2.txt] tokens, return +field proxy_mech=%m as extra field. + +Example password forwarding static DB configuration +--------------------------------------------------- + +See <PasswordDatabase.Static.txt> + +Example password forwarding SQL configuration +--------------------------------------------- + +Create the SQL table: + +---%<------------------------------------------------------------------------- +CREATE TABLE proxy ( + user varchar(255) NOT NULL, + host varchar(16) default NULL, + destuser varchar(255) NOT NULL default '', + PRIMARY KEY (user) +); +---%<------------------------------------------------------------------------- + +Insert data to SQL corresponding your users. + +Working data could look like this: ++------+-------------+-----------------+ +| user | host | destuser | ++------+-------------+-----------------+ +| john | 192.168.0.1 | | ++------+-------------+-----------------+ +| joe | 192.168.0.2 | joe@example.com | ++------+-------------+-----------------+ + +The important parts of 'dovecot.conf': + +---%<------------------------------------------------------------------------- +# If you want to trade a bit of security for higher performance, change these +settings: +service imap-login { + service_count = 0 +} +service pop3-login { + service_count = 0 +} + +# If you are not moving mailboxes between hosts on a daily basis you can +# use authentication cache pretty safely. +auth_cache_size = 4096 + +auth_mechanisms = plain +passdb { + driver = sql + args = /usr/local/etc/dovecot/dovecot-sql.conf.ext +} +---%<------------------------------------------------------------------------- + +The important parts of 'dovecot-sql.conf.ext': + +---%<------------------------------------------------------------------------- +driver = mysql +connect = host=sqlhost1 host=sqlhost2 dbname=mail user=dovecot password=secret +password_query = SELECT NULL AS password, 'Y' as nopassword, host, destuser, +'Y' AS proxy FROM proxy WHERE user = '%u' +---%<------------------------------------------------------------------------- + +Example proxy_maybe SQL configuration +------------------------------------- + +Create the SQL table: + +---%<------------------------------------------------------------------------- +CREATE TABLE users ( + user varchar(255) NOT NULL, + domain varchar(255) NOT NULL, + password varchar(100) NOT NULL, + host varchar(16) NOT NULL, + home varchar(100) NOT NULL, + PRIMARY KEY (user) +); +---%<------------------------------------------------------------------------- + +The important parts of 'dovecot.conf': + +---%<------------------------------------------------------------------------- +# user/group who owns the message files: +mail_uid = vmail +mail_gid = vmail + +auth_mechanisms = plain + +passdb { + driver = sql + args = /usr/local/etc/dovecot/dovecot-sql.conf.ext +} +userdb sql { + driver = sql + args = /usr/local/etc/dovecot/dovecot-sql.conf.ext +} +---%<------------------------------------------------------------------------- + +The important parts of 'dovecot-sql.conf.ext': + +---%<------------------------------------------------------------------------- +driver = mysql + +password_query = \ + SELECT concat(user, '@', domain) AS user, password, host, 'Y' AS proxy_maybe +\ + FROM users WHERE user = '%n' AND domain = '%d' + +user_query = SELECT user AS username, domain, home \ + FROM users WHERE user = '%n' AND domain = '%d' +---%<------------------------------------------------------------------------- + +Example proxy LDAP configuration +-------------------------------- + +see: <PasswordDatabase.ExtraFields.txt> for more information, and a worked out +example + +(This file was created from the wiki on 2019-06-19 12:42) |