# HG changeset patch # User Timo Sirainen # Date 1034642746 -10800 # Node ID 58899a4135699672cd3f1bb98bfa11744aa93c34 # Parent 4c7d08ae3f6e6d5b0a6f1440b252eec935ad008a Documentation updates. diff -r 4c7d08ae3f6e -r 58899a413569 .cvsignore --- a/.cvsignore Tue Oct 15 00:21:48 2002 +0300 +++ b/.cvsignore Tue Oct 15 03:45:46 2002 +0300 @@ -22,7 +22,6 @@ install-sh missing mkinstalldirs -INSTALL intl ABOUT-NLS COPYING diff -r 4c7d08ae3f6e -r 58899a413569 INSTALL --- a/INSTALL Tue Oct 15 00:21:48 2002 +0300 +++ b/INSTALL Tue Oct 15 03:45:46 2002 +0300 @@ -13,6 +13,8 @@ mv /usr/local/etc/dovecot-example.conf /usr/local/etc/dovecot.conf Read through it, make needed modifications and start imap-master. +doc/configuration.txt tells you more about configuring Dovecot. + SSL/TLS ------- @@ -20,6 +22,7 @@ GNUTLS v0.5.5 or later is required to enable SSL and TLS support. OpenSSL isn't supported. You can get GNUTLS from http://www.gnutls.org/ + Optional configure options -------------------------- diff -r 4c7d08ae3f6e -r 58899a413569 README --- a/README Tue Oct 15 00:21:48 2002 +0300 +++ b/README Tue Oct 15 03:45:46 2002 +0300 @@ -1,56 +1,17 @@ - - * Alpha release - -This release has not been extensively tested, I don't recommend putting it -into production usage yet. All the IMAP4rev1 features are fully supported, -except custom message flags still need to be implemented. There's several -minor problems left, see TODO file. - - * Mail storages +Installation +------------ -Maildir is the preferred storage with most robust implementation. mbox -support is available but currently it relies a little bit on good luck, I -made it mostly for personal use and I strongly recommend using maildir if -at all possible. +See INSTALL file. -Maildir folders are done like with courier. INBOX is the ~/Maildir -directory, all the other folders named as "..." -under it, any directories not starting with a dot are simply ignored. -Deleting folders is made atomic by renaming them as ".." and -deleting the directory after that. So, all directories beginning with ".." -are deleted whenever they're noticed. Indexes are stored into each folder's -root directory. -mbox storage currently requires that all mail is in user-writable -directory, eg. ~/mail. Especially using /var/mail/user is NOT supported. -You may however create a ~/mail/inbox hardlink (or symlink if not chrooted) -to pointing to /var/mail/user. All files in the mail directory are -considered as mailboxes. Directories specify subfolders in IMAP. "inbox" -file specifies the INBOX folder and can not be named otherwise. Indexes are -stored into ".imap//" directories. - -imap process detects the storage from MAIL-environment which is preferred -to be in format ":", for example "maildir:~/Maildir". It's -anyway allowed to be in pretty much any format as long as some of the -storages recognizes it as a valid data, so for example "MAIL=~/mail" is -first checked by maildir storage to see if it's valid maildir and -mbox storage after that. +Configuration +------------- -If the MAIL environment isn't given at all, all the storages are gone -through which try to find a valid directory for themselves to use. Also as -a special case, if MAILDIR environment exists, maildir storage is used with -the directory specified in it. +See doc/configuration.txt file. + -Maildir storage is autodetected by checking if /cur/ exists and -we have rwx access to it. If directory isn't known, / and ~/Maildir are -checked. / is checked because we could be chrooted. - -mbox storage is autodetected by checking if .imap/ (+rwx), inbox (+rw) or -mbox (+rw) exists in directory. If directory isn't known, / is tried first. -After that, ~/mail and ~/Mail directories are used if they're found without -checking if they even contain any files. - - * Code +Code +---- The code is split into a several libraries and binaries: @@ -67,20 +28,22 @@ imap binary uses only the interface so it's possible to add support for any kind of mail storage (eg. SQL). - * RFCs conformed + +RFCs conformed +-------------- -822 - Standard for ARPA Internet Text Messages -2822 - Internet Message Format (updated rfc822) -2045..2049 - Multipurpose Internet Mail Extensions (MIME) + 822 - Standard for ARPA Internet Text Messages + 2822 - Internet Message Format (updated rfc822) + 2045..2049 - Multipurpose Internet Mail Extensions (MIME) -2060 - IMAP4rev1 -2180 - IMAP4 Multi-Accessed Mailbox Practice + 2060 - IMAP4rev1 + 2180 - IMAP4 Multi-Accessed Mailbox Practice -2595 - Using TLS with IMAP, POP3 and ACAP -2831 - Using Digest Authentication as a SASL Mechanism (DIGEST-MD5) + 2595 - Using TLS with IMAP, POP3 and ACAP + 2831 - Using Digest Authentication as a SASL Mechanism (DIGEST-MD5) -rfc2831 - * Contact info +Contact info +------------ Timo Sirainen , http://dovecot.procontrol.fi/ diff -r 4c7d08ae3f6e -r 58899a413569 doc/auth.txt --- a/doc/auth.txt Tue Oct 15 00:21:48 2002 +0300 +++ b/doc/auth.txt Tue Oct 15 03:45:46 2002 +0300 @@ -1,12 +1,11 @@ -Authentication is split into two separate parts: the authentication method, -and the password/user information backend (FIXME: is there a good name for -that? I can't think of any). +Authentication is split into two separate parts: the authentication +mechanism, and the authentication backend. -Currently supported methods: +Currently supported mechanisms: - plaintext: By itself it's very insecure, but through secured SSL/TLS connection it should be fine. - - Digest-MD5: Should be quite secure by itself, and it also supports + - Digest-MD5: Should be quite secure by itself. It also supports integrity protection and crypting the rest of the communication, but we don't support those yet. @@ -16,11 +15,10 @@ - shadow: /etc/shadow or similiar, using getspnam() - pam: PAM authentication - passwd-file: /etc/passwd-like file + - vpopmail: External software used to handle virtual domains -passwd, shadow and pam backends work only with plaintext authentication. -passwd-file can be used with both plaintext and Digest-MD5. More backends -can be easily added later. - +Digest-MD5 works only with passwd-file. More mechanisms and backends can be +easily added later. passwd-file ----------- @@ -37,10 +35,10 @@ Either home or mail is required to exist. Home specifies the home directory of user under which mail is located. The actual mail format and location is -automatically detected, just as if you run the imap-binary directly. Other +automatically detected, just as if you run the imap binary directly. Other way is to specify the mail storage parameters directly using the -mail-field, see README file for more information about it (the MAIL -environment). +mail-field, see "Detecting what to use" chapter in mail-storage.txt file +for more information about it (the MAIL environment). Flags is a comma-separated list of flags, currently only recognized value is "chroot", which makes the imap process chroot into home directory, if diff -r 4c7d08ae3f6e -r 58899a413569 doc/configuration.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/configuration.txt Tue Oct 15 03:45:46 2002 +0300 @@ -0,0 +1,133 @@ +Authentication +-------------- + +See auth.txt. + + +Maildir or mbox? +---------------- + +Maildir stores each message into a separate file, message flags are stored +into file name. These make maildir very unlikely to get corrupted in any +way. + +Reading lots of mails from maildir is somewhat slower than from mbox, since +each mail file needs to be separately opened. Updating the mailbox however +is much faster than with mbox. + +With larger mailboxes it's a good idea to use a filesystem which uses +b-tree or hash indexes for directories, for example ReiserFS, XFS or JFS. +ext2 and ext3 have some patches to implement this but they're not in Linux +2.4.19 yet. I'm not sure about *BSD's filesystems, FreeBSD's ufs had some +support for hashes. + +mbox is just a single file where new mails are appeneded, flags are stored +in each message's headers. Deleting mails is slow as the rest of the file +needs to be moved over the deleted mail. Changing message flags is usually +quite fast since we use some tricks to avoid copying too much data, but it +may result as well in large data copying. + +Besides the copying being slow, it's also a bit dangerous. If the copying +is aborted (crashed, killed, power lost) the mail file may be left in +somewhat corrupted stated. + +Bottom line: mbox is good for read-only mailboxes, maildir for everything +else. + + +Creating new users +------------------ + +Dovecot is interested in only one thing - being able to find the user's +mail directory. With maildir you need to do mkdir ~user/Maildir, with mbox +mkdir ~user/mail. + + +System with local users +----------------------- + +First of all, don't make imap process chroot to users' mail directory, +UNLESS that filesystem is mounted with nosuid-flag. Otherwise there's a +small possibility for the user to gain root privileges. + +Then you need to decide if you want users to have the same IMAP password +than the system password. If yes, disable_plaintext_auth = yes is a very +good idea. + + +System without local users +-------------------------- + +First you'll need to decide if you want to use one or multiple system uids. +For example one for everything, one per each virtual domain or one per each +user. In any case the uids should be different than the uids used for other +parts of Dovecot (login or auth processes). + +Having one uid per user would mean that in case of a security hole in +Dovecot, the user still couldn't read other peoples mails. Use this if +possible. + +chrooting imap processes would be good idea, but you should still think +about having the filesystem nosuid-mounted. + + +Performance +----------- + +Usually the bottleneck with IMAP server is disk I/O, so get fast disks and +lots of memory to act as operating system's file cache. + +One performance tweak is to save mails with CR+LFs instead of just LFs. +This can result in faster indexing of mails and smaller CPU usage when +sending mails. With Linux and FreeBSD Dovecot can use sendfile() syscall to +send such mails. However extra CRs do increase the mail size, meaning more +I/O and potentially losing the gained performance. You can enable this for +mails saved by Dovecot by setting mail_save_crs = yes. For mails saved by +your mailer you'll need to do something else, not yet covered by this +documentation. + +COPY command can be made much faster with maildir by setting +maildir_copy_with_hardlinks = yes. This is problematic only if something +modifies the mail in one folder but doesn't want it modified in the others. +I don't know any MUA which would modify any mail files directly. + +Logins can be handled either fast, or securely. Doing it securely means +creating a new login process for each connection instead of having only +few processes handling multiple connections. The problem with sharing +connections is that if a security hole is found, the attacker could hijack +other peoples connections or steal their passwords if plaintext +authentication was used (even with SSL/TLS). + +Dovecot's memory usage is very small. Almost all memory usage you see with +ps/top is from mmap()ed files, meaning that operating system can drop any +of those memory pages at any time without needing to swap them, unless +they're just being modified. With Linux/x86 Dovecot usually takes about +48kB of non-mmaped memory plus ~4kB per cached mail (max. 16 by default). + + +Rootless Dovecot +---------------- + +It's possible to make Dovecot run under one uid, not requiring root +privileges at any point. This shouldn't be thought of as any security +feature, but instead just as a way for non-admins to run imap server from +their favourite mail computer. + +If you do think of this as a good way to achieve security, ask yourself +which is worse: + +a) near-zero possibility to get root privileges, small possibility to get +into system as imapd user chrooted into empty directory without logging in, +small possibility to get logged user's privileges but no possiblity to read +others mails since they're saved with different uid (plus you might be +chrooted to your own mailbox). + +b) zero possibility to get root privileges through Dovecot, small +possibility to get into system as mail user, possibly even without logging +in, and being able to read everyone's mail (and finally getting roots by +exploiting some local just released vulnerability, unless you bothered to +set up special chroot environment). + +Anyway, doing it is easy. configure --prefix=$HOME, make install, change +login_user and auth_user in dovecot.conf to your user id and use +passwd-file authentication. diff -r 4c7d08ae3f6e -r 58899a413569 doc/mail-storages.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/mail-storages.txt Tue Oct 15 03:45:46 2002 +0300 @@ -0,0 +1,85 @@ + * Maildir + +We support Courier-compatible Maildir++. INBOX is the ~/Maildir directory, +all the other folders named as "..." under it, any +directories not starting with a dot are simply ignored. Deleting folders is +made atomic by renaming them as ".." and deleting the +directory after that. So, all directories beginning with ".." are deleted +whenever they're noticed. Indexes are stored into each folder's root +directory. + +Custom flags saved using a..z letters as Maildir file flags. .customflags +file is then used to map the letters to names (a=0, b=1, etc). + + * mbox + +mbox storage currently requires that all mail is in user-writable +directory, eg. ~/mail. Especially using /var/mail/user is NOT supported. +You may however create a ~/mail/inbox hardlink (or symlink if not chrooted) +to pointing to /var/mail/user. All files in the mail directory are +considered as mailboxes. Directories specify subfolders in IMAP. "inbox" +file specifies the INBOX folder and can not be named otherwise. Indexes are +stored into ".imap//" directories. + + * Detecting what to use + +imap process detects the storage from MAIL-environment. It's preferred +format is ":", for example "maildir:~/Maildir". It's anyway +allowed to be in pretty much any format as long as some of the storages +recognizes it as a valid data, so for example "MAIL=~/mail" is first +checked by maildir storage to see if it's valid maildir and mbox storage +after that. + +If the MAIL environment isn't given at all, all storages are gone through +and asked if they can find a usable mail folder. Also as a special case, if +MAILDIR environment exists, maildir storage is used with the directory +specified in it. + +Maildir storage is autodetected by checking if /cur/ exists and +we have rwx access to it. If directory isn't known, / and ~/Maildir are +checked. / is checked because we could be chrooted. + +mbox storage is autodetected by checking if .imap/ (+rwx), inbox (+rw) or +mbox (+rw) exists in directory. If directory isn't known, / is tried first. +After that, ~/mail and ~/Mail directories are used. + + * Files created by Dovecot + +.subscriptions: One folder per line listing subscribed IMAP folders. +There's only one of these files in the root mail directory (~/Maildir/ or +~/mail/.imap/). + +Then there's the per-folder files: + +.imap.index: Fixed width mail index records. + +.imap.index.data: Variable width data, for example mail file name and +cached body, envelope, etc. + +.imap.index.log: Log file describing made changes. This file is used to +mark external changes (expunges and flag changes) temporarily until they're +synced into IMAP clients. If multiple Dovecots have the same folder open, +this can be a big speedup. + +.imap.index.tree: Binary tree used for looking up messages from .imap.index +file. This is used for both UID lookups and message sequence lookups. +Sequences can be looked up directly from the index as long as no messages +have been expunged, but after that it gets slow unless it's compressed. +Using this file however can keep the sequence lookups and expunges fast in +all situations without requiring compression. + +.customflags: Lists custom message flags. First line is header which +Dovecots check to see if the file has changed. Other lines list the flags +in format " ". Currently there can be 26 different +flags (0..25). + +.imap.index.log and .imap.index.tree files can be deleted without any data +loss, they're simply recreated/rebuilt when they're noticed missing. + +Deleting .imap.index and .imap.index.data files results in loss of message +UIDs. That may be a bad thing with some IMAP clients which store some data +about message locally and identifies the message by it's UID. + +Deleting .customflags results in loss of custom flag names for Maildir. +With mbox the .customflags is simply recreated based on the flags listed +in the mbox file itself (ie. no data loss).