Adding upstream version 1:2.3.19.1+dfsg1.upstream/1%2.3.19.1+dfsg1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 126 insertions, 0 deletions

diff --git a/doc/wiki/LoginProcess.txt b/doc/wiki/LoginProcess.txt
new file mode 100644
index 0000000..0918e1b
--- /dev/null
+++ b/doc/wiki/LoginProcess.txt
@@ -0,0 +1,126 @@
+Login processes
+===============
+
+The main purpose of login processes is to handle the IMAP, POP3,
+<Submission.txt> (v2.3), and <ManageSieve> [Pigeonhole.ManageSieve.txt]
+connections before the user has logged in. The login processes don't need to be
+able to do anything else than let the user log in, so they can run in highly
+restricted environment. By default they are run as a non-privileged "dovenull"
+user chrooted into a non-writable directory containing only authentication UNIX
+sockets.
+
+Login processes also handle proxying the SSL and TLS connections even after the
+user has logged in. This way all the SSL code runs in the same restricted
+environment, which means that a security hole in the SSL library gives the
+attacker access only to the restricted chroot, rather than possibly all the
+users' mails.
+
+The default login settings should be good enough for small sites. There are two
+ways to run the login processes: the high-security mode and the
+high-performance mode. Both are discussed separately below.
+
+For explanation on the various settings for services, see <Services.txt>
+
+High-security mode
+------------------
+
+You can enable high-security mode with:
+
+---%<-------------------------------------------------------------------------
+service imap-login {
+  service_count = 1
+  #process_min_avail = 0
+  #process_limit = $default_process_limit
+  #vsz_limit = 64M
+}
+service pop3-login {
+  service_count = 1
+}
+---%<-------------------------------------------------------------------------
+
+This is the default. It works by using a new imap-login or pop3-login process
+for each incoming connection. Since the processes run in a highly restricted
+chroot, running each connection in a separate process means that in case there
+is a security hole in Dovecot's pre-authentication code or in the SSL library,
+the attacker can't see other users' connections and can't really do anything
+destructive. The only way out of it is to find and exploit a kernel security
+hole.
+
+Since one login process can handle only one connection, the service's
+'process_limit' setting limits the number of users that can be logging in at
+the same time (defaults to 'default_process_limit=100'). SSL/TLS proxying
+processes are also counted here, so if you're using SSL/TLS you'll need to make
+sure this count is higher than the maximum number of users that can be logged
+in simultaneously. With TLS/SSL connections, the login process will not
+terminate, and remains to perform proxying between imap backend process and the
+client.
+
+ * If the maximum login process count is reached, the oldest process in
+   logging-in state (ie. non-proxying) is destroyed.
+ * To avoid startup latency for new client connections, set 'process_min_avail'
+   to higher than zero. That many idling processes are always kept around
+   waiting for new connections.
+ * 'vsz_limit' should be fine at its default 64MB value.
+
+High-performance mode
+---------------------
+
+You can enable high-performance mode with:
+
+---%<-------------------------------------------------------------------------
+service imap-login {
+  service_count = 0
+  #client_limit = $default_client_limit
+  process_min_avail = 4 # number of CPU cores
+  vsz_limit = 1G
+}
+service pop3-login {
+  service_count = 0
+}
+---%<-------------------------------------------------------------------------
+
+It works by using a number of long running login processes, each handling a
+number of connections. This loses much of the security benefits of the login
+process design, because in case of a security hole (in Dovecot or SSL library)
+the attacker is now able to see other users logging in and steal their
+passwords, read their mails, etc.
+
+ * 'process_min_avail' should be set to be at least the number of CPU cores in
+   the system, so that all of them will be used.
+ * Otherwise new processes are created only once an existing one's connection
+   count reaches client_limit
+ * Default client_limit * process_limit = 1000*100 = 100k connections
+ * vsz_limit should be increased to avoid out of memory errors, especially if
+   you're using SSL/TLS.
+
+Login access check sockets
+--------------------------
+
+Dovecot login processes can check via UNIX socket if the incoming connection
+should be allowed to log in. This is most importantly implemented to enable TCP
+wrappers support for Dovecot.
+
+TCP wrappers support
+--------------------
+
+You must have built Dovecot with support for TCP wrappers. You can do this by
+giving '--with-libwrap' parameter to 'configure'.
+
+Add to dovecot.conf:
+
+---%<-------------------------------------------------------------------------
+login_access_sockets = tcpwrap
+
+service tcpwrap {
+  unix_listener login/tcpwrap {
+    group = $default_login_user
+    mode = 0600
+    user = $default_login_user
+  }
+}
+---%<-------------------------------------------------------------------------
+
+Remember to configure your rules! The format is described in hosts.allow(5) and
+hosts.deny(5). Files used are usually /etc/hosts.allow and /etc/hosts.deny.
+
+(This file was created from the wiki on 2019-06-19 12:42)