[Dovecot] dovecot's documentation dearth
Hello. The first thing for me to say is thanks! I've been using dovecot since test 61 and it has basically performed flawlessly for me from day number 1. Dovecot makes me look like a genius sysadmin, especially compared to my colleagues struggling with exchange. So thanks, gracias, obrigado!!
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 plugin service protocol userdb local_name (and I think there is another one of these for ips)
The service section itself would benefit from a single page detailing all of the possible types of service sections available.
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 and they look to me like they could support listening on a port if inet_interfaces is defined.
You can say, "Relax fella, trust me. These programs are all part of dovecot and are run only if they're needed." Then I'll say, "Yes but I'm the administrator. I need to know how the parts fit together to know if the system's broken." Then you say, "Well that makes sense, but the things you're talking about aren't really configured. They are mostly internal to dovecot, they just happen to be broken out into external programs. You may as well be asking for documentation on a specific function in a library. If that's what you want, you can read through the source code."
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 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? How do I control it? I think these are all good questions for an administrator to ask.
That's my feedback for what it's worth, but mostly, thanks again for dovecot!
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.
participants (2)
-
Postmaster
-
Timo Sirainen