1 files changed, 166 insertions, 0 deletions
diff --git a/doc/wiki/POP3Server.txt b/doc/wiki/POP3Server.txt
new file mode 100644
index 0000000..1c389a7
--- /dev/null
+++ b/doc/wiki/POP3Server.txt
@@ -0,0 +1,166 @@
+Dovecot as a POP3 server
+========================
+
+Dovecot was primarily designed to be an IMAP server, so although it works fine
+as a POP3 server, it's not really optimized for that.
+
+Maildir Performance
+-------------------
+
+The main problem with Dovecot's POP3 implementation with Maildir is how to get
+messages' size fast enough. The POP3 specification requires that the sizes are
+reported exactly, not just approximately. This means that linefeeds must be
+counted as CR+LF characters. Normally with Maildir the linefeeds are stored as
+plain LF characters, which means that simply getting the file size would
+produce the wrong POP3 message size. Some Maildir POP3 servers do this anyway
+and violate the POP3 specification.
+
+Dovecot returns correct message sizes by reading the entire message and
+counting the linefeeds correctly. After this is done, the "virtual size" is
+stored into dovecot-uidlist file and future calculations can be avoided by
+simply looking up the cached value.
+
+You can also avoid the initial message size calculation by storing the size
+directly into the filename. You can do this by appending ,W=<size> at the end
+of the base filename. For example '1199932653.M583975P6568.host,W=2211:2,' is a
+file whose virtual size is 2211 bytes (and real size somewhat smaller). Note
+that this must not be done for existing files, only to newly delivered mails.
+
+If Dovecot's LDA is used, dovecot-uidlist and the index files are updated upon
+message arrival, therefore there will be no message-size performance issues.
+
+'pop3_fast_size_lookups=yes' setting in v2.0.5+ uses the virtual message sizes
+when they're already available, but fallbacks to using the physical message
+sizes (violating POP3 specifications, but then again a lot of POP3 servers do
+that).
+
+mbox Performance
+----------------
+
+Index files are quite useless if your users don't keep mails in the server.
+They get first updated when the POP3 session starts to include all the
+messages, and after the user has deleted all the mails, they again get updated
+to contain zero mails. With this kind of a session the index reads and writes
+could have been avoided if the index files had just been completely disabled.
+
+You may want to try how performance changes if you disable indexes for POP3
+users. You can also try preserving indexes but try different values for
+'mbox_min_index_size' setting.
+
+Do not disable indexing if there are users that do not delete messages after
+downloading them.  Also, if you use Dovecot LDA, indexes may be helpful to have
+fast access to the message sizes.
+
+Session locking
+---------------
+
+By default Dovecot allows multiple POP3 connections to the same mailbox. This
+is (was?) especially useful for dialup connections which die in the middle of
+the download, because the half-dead connections won't keep the mailbox locked.
+
+Setting 'pop3_lock_session=yes' makes Dovecot lock the mailbox for the whole
+session. This is also what the POP3 RFC [http://www.ietf.org/rfc/rfc1939.txt]
+specifies that should be done. If another connection comes while the mailbox is
+locked, Dovecot waits until the locking times out (2 minutes with
+Maildir,'mbox_lock_timeout' with mbox). In future there will be a separate
+'pop3_lock_timeout' setting which allows timing out sooner.
+
+Flag changes
+------------
+
+By default when a message is RETRed, \Seen flag is added to it. POP3 itself
+doesn't support flags, but if the mailbox is opened with IMAP (eg. from
+webmail) it's shown as seen. You can disable this (to get better performance)
+with 'pop3_no_flag_updates=yes'.
+
+POP3 client workarounds
+-----------------------
+
+'pop3_client_workarounds' setting allows you to set some workarounds to avoid
+POP3 clients breaking with some broken mails.
+
+Following are supported
+
+ * outlook-no-nuls - Converts 0x0 in data to 0x80
+ * oe-ns-eoh - Add missing end of header line
+
+UIDL format
+-----------
+
+UIDLs are used by POP3 clients to keep track of what messages they've
+downloaded, typically only if you've enabled "keep messages in server" option.
+If the UIDL changes, the existing messages are re-downloaded as new messages,
+which the users don't really appreciate.
+
+Dovecot supports multiple different ways to set the UIDL format, mostly to make
+migrations from other POP3 servers transparent by preserving the old UIDL
+values. See <Migration.txt> for how to set the UIDLs to be compatible with your
+previous POP3 server.
+
+For new POP3 servers, the easiest way to set up UIDLs is to use IMAP's
+UIDVALIDITY and UID values. The default in Dovecot v1.1+ is:
+
+---%<-------------------------------------------------------------------------
+pop3_uidl_format = %08Xu%08Xv
+---%<-------------------------------------------------------------------------
+
+Another good default is to use the message's global UID:
+
+---%<-------------------------------------------------------------------------
+pop3_uidl_format = %g
+---%<-------------------------------------------------------------------------
+
+However, note that GUIDs may not be unique, as the GUID does not change when a
+message is copied.  (While copying is not possible using only POP3, it can be
+done using IMAP, Sieve, or doveadm.)
+
+Some formats, such as the previous default '%v.%u', seem to have problems with
+Outlook 2003.
+
+MD5 UIDL format (mbox-only)
+---------------------------
+
+---%<-------------------------------------------------------------------------
+pop3_uidl_format = %m
+---%<-------------------------------------------------------------------------
+
+This works by getting the MD5 sum of a couple of message headers that uniquely
+identify the message. The one good thing about MD5 format is that it doesn't
+rely on the IMAP UID or UIDVALIDITY value. This allows you to modify the mbox
+files in ways that Dovecot doesn't like, without causing the UIDLs to change.
+For example:
+
+ * Inserting messages in the middle of mbox files (eg. restoring mbox files
+   from backups can cause "Expunged message reappeared" errors)
+ * Reordering messages inside mbox
+ * <Other random problems> [MboxProblems.txt] causing UID renumbering (although
+   you should figure out why they're happening)
+
+The MD5 summing method however doesn't work well if you receive two identical
+messages. Usually the MD5 sum is taken from these headers:
+
+ * The first Received: header
+ * Delivered-To: header
+
+Normally there won't be a problem, because the MTA adds a unique identifier to
+the first Received: header. If the same message is sent to multiple users in
+one delivery, the Delivered-To: header is still different, making the MD5 sum
+different.
+
+Except the MTA can be configured to support aliases, so for example sending the
+mail to both root@ and webmail@ aliases causes the message to be delivered to
+the same user, with identical Received: and Delivered-To: headers. The messages
+really are identical, so their MD5 sums are also identical, and that can cause
+some POP3 clients to keep downloading the messages over and over again, never
+deleting them.
+
+To avoid this, there's also a 3rd header that is included in the MD5 sum
+calculation:
+
+ * X-Delivery-ID: header
+
+If you use <Dovecot's deliver> [LDA.txt] or IMAP APPEND and 'pop3_uidl_format =
+%m', it always appends the X-Delivery-ID: header to saved mailbox. Any existing
+X-Delivery-ID: headers in the saved mails are dropped.
+
+(This file was created from the wiki on 2019-06-19 12:42)