Quick Configuration
===================

If you just want to get Dovecot running with typical configuration in a typical
environment, here's what you'll have to do:

 1. Quick Configuration
     1. Configuration file
     2. Authentication
     3. Mail Location
     4. Mbox
     5. Maildir
     6. Client Workarounds
     7. POP3 Server
     8. SSL and Plaintext Authentication
     9. NFS
     10. Running

Configuration file
------------------

If you compiled Dovecot from sources, Dovecot has installed a
'/usr/local/etc/dovecot-example.conf' file, which you'll have to rename to
'/usr/local/etc/dovecot.conf'. Prebuilt packages usually install
'/etc/dovecot.conf' directly. You'll find the path by running 'dovecot -n|head
-1'. It's a good idea to read through the whole file and see what settings you
might want to change.

Authentication
--------------

You'll probably be using <PAM> [PasswordDatabase.PAM.txt] authentication. See
the<PAM> [PasswordDatabase.PAM.txt] page for how to configure it. A typical
configuration with Linux would be to create '/etc/pam.d/dovecot' which
contains:

---%<-------------------------------------------------------------------------
auth    required        pam_unix.so
account required        pam_unix.so
---%<-------------------------------------------------------------------------

If you're using something else, see <password databases> [PasswordDatabase.txt]
and<user databases> [UserDatabase.txt].

Mail Location
-------------

You can let Dovecot do its automatic mail location detection, but if that
doesn't work, you can set the location manually in 'mail_location' setting. See
<MailLocation.txt> for more information.

Mbox
----

Make sure that all software accessing the mboxes are using the same locking
methods in the same order. The order is important to prevent deadlocking. From
Dovecot's side you can change these from 'mbox_read_locks' and
'mbox_write_locks' settings. See <MboxLocking.txt> for more information.

If you're using '/var/mail/' directory for INBOXes, you may need to set
'mail_privileged_group = mail' so Dovecot can create dotlocks there.

For better performance you may want to set 'mbox_very_dirty_syncs = yes'
option.

Maildir
-------

For better performance you may want to set 'maildir_copy_with_hardlinks = yes'
option (default in v1.1+).

Client Workarounds
------------------

Check 'imap_client_workarounds' and 'pop3_client_workarounds' and see if you
want to enable more of them than the defaults.

POP3 Server
-----------

If you're going to use Dovecot's POP3 server, you'll need to add 'pop3' (and
'pop3s' for SSL) to 'protocols' line in configuration file.

You'll also have to set 'pop3_uidl_format' setting. If you're migrating from
another POP3 server, see<migration page> [Migration.txt]. Otherwise set it to
Dovecot v1.1+'s default:

---%<-------------------------------------------------------------------------
pop3_uidl_format = %08Xu%08Xv
---%<-------------------------------------------------------------------------

SSL and Plaintext Authentication
--------------------------------

If you intend to use SSL, set 'ssl_cert_file' and 'ssl_key_file' settings.
Otherwise set 'ssl_disable = yes' ('ssl = no' with v1.2.beta1+). Easiest way to
get SSL certificates built is to use Dovecot's 'doc/mkcert.sh' script. See
<SSL.txt>.

By default Dovecot doesn't allow users to send passwords unencrypted to the
server. Usually if SSL is enabled, it's a good idea not to allow this. However,
if you don't offer SSL for some reason, you'll probably want to set
'disable_plaintext_auth = no'.

To enable imaps and pop3s, make sure they're listed in 'protocols' setting.

NFS
---

If you're using NFS or some other remote filesystem that's shared between
multiple computers, you really should be using Dovecot v1.1 or later.
See<NFS.txt> for more information about what settings you'll need to change and
what other issues you'll have to be aware of.

IIf you have only a single Dovecot server, or if the users almost always log
into same physical server, you may want to consider storing the indexes into
local disks instead. This is done by appending ':INDEX=path' to
'mail_location'. For example:

---%<-------------------------------------------------------------------------
mail_location = maildir:~/Maildir:INDEX=/var/indexes/%u
---%<-------------------------------------------------------------------------

Remember that if you're storing indexes locally you can keep 'mmap_disable =
no' and 'mail_nfs_index=no' (which gives better performance).

Running
-------

See <RunningDovecot.txt> and <Logging.txt>. 

(This file was created from the wiki on 2009-02-04 04:42)
