[Dovecot] dovecot's documentation dearth

[Timo Sirainen]

On Mon, 2011-08-15 at 17:13 -0400, Postmaster wrote:

> I'm working on a configuration for 2.0 and I'm finding the documentation 
> somewhat difficult.  I think it would be very helpful to me to have 
> encountered a single page that detailed all available configuration 
> sections.  I don't know how to find out what the sections are, when to 
> use them or what specifically they control.  So far I've encountered...
> 
>    passdb

This is same as always: http://wiki2.dovecot.org/PasswordDatabase

>    plugin

Also. Simply settings used by plugins: http://wiki2.dovecot.org/Plugins

>    service

This is a bit tricky one and unfortunately not documented clearly yet.
The included example-config/conf.d/10-master.conf has some comments
about them though.

>    protocol

A filter for settings inside it to affect only the specified protocol,
e.g. protocol imap {} or pop3 or smtp or .. Would have probably been
nice to name these filters in a more consistent form (like: filter
protocol imap {})

>    userdb

As before: http://wiki2.dovecot.org/UserDatabase

>    local_name (and I think there is another one of these for ips)

Another filter to apply settings inside it only for the specified
hostname/IP address. local_name is mainly about using it for multiple
SSL certificates when using TLS SNI. local {} is about any other
specific per-IP/network settings. remote {} is similar to local {}
except for remote IP/network.

I'm not sure where would be a good place to document these.. I suppose I
should create a new wiki page about some generic config file syntax
things.

> The service section itself would benefit from a single page detailing 
> all of the possible types of service sections available.

You can get a list of all default services with "doveconf service", but
you can also create your own services. Also e.g. once you install
Pigeonhole Sieve you'll get more services.

> The next problem I've had is discovering that several parts of dovecot 
> have no documentation at all even though they are standalone executables 
> run by root.  config, log, and ssl_params all run as root but there is 
> also anvil 

These are the services that are run internally by Dovecot. It's part of
the same "yeah, would be good to document all services and what they do
and what service parameters may and may not be changed for them" but I'm
kind of busy..

> and they look to me like they could support listening on a 
> port if inet_interfaces is defined.

Everything supports listening anywhere, but whether it's a good idea is
another thing.

> Well I guess that would be one solution.  The bottom line is that it 
> gives me an uncomfortableness to not be able to control or explain the 
> operation of the software I'm supposedly administering.  Take the 
> program named log (which should be named dovecot-log or something less 
> generic), 

It shows up as "dovecot/log" in the ps list and exists in
libexec/dovecot/log, so I don't think the name is a problem. I
considered naming everything dovecot-* but then thought dovecot/* is
prettier and doesn't require renaming so many existing binaries from
v1.x.

> it is launched even though I've specified syslog in the 
> configuration.  Logging is not interrupted when the process is killed. 
> So, why is it running?  What is it doing?  Why does it need root?  

Everything still gets logged through it even if you use syslog. It does
a few other small log simplifying things besides just writing to a log
file. If you kill it, it's restarted and that's why you don't see
logging interruption (some messages might get lost). If you send a
SIGSTOP to it the logging should stop and eventually all processes
should start blocking on log writes I think. It doesn't need to be root
as long as it can do the logging without.