The material on auth_pop has been updated since the last post and I cleaned up some typos.
This is going to be a long message that maybe should be placed on the Life with Binc IMAP wiki.
Table of Contents =================
1. Introduction 2. qmail-pop3d & checkpassword 3. bincimapd & checkpassword 4. qmail-pop3d & checkvpw 5. qmail-pop3d & auth_pop 6. bincimapd & checkvpw 7. bincimapd & auth_pop 8. Conclusion
1. Introduction ===============
An unintended side effect of the command line argument parser being cleaned up in Binc IMAP v1.2.7 is that it cause failures at those sites using checkvpw (from vmailmgr) and auth_pop (from qmail-ldap). The resulting investigation revealed minor differences between checkpassword (from qmail), checkvpw and auth_pop. It also revealed minor differences in the authentication interface between Binc IMAP and qmail-pop3d.
This document has two purposes:
1. To give administrators a better understanding about how all these tools interact with each other so that they can diagnose problems more quickly.
2. To provide background to the authors of the different tools to encourage them to make there tools more consistent with each other to try to eliminate the problems that arise from these inconsistencies (and to eliminate the need for this document).
<WARNING>
I am just summarizing information that I have learned over the past week about checkvpw and auth_pop, mostly from this mailing list and from other web sources. I personally have not run anything other than checkpassword.
</WARNING>
2. qmail-pop3d & checkpassword ==============================
Since the authentication model used by Binc IMAP is the one from Qmail, it is worthwhile starting our discussion with qmail-pop3d. It is invoked in a command line that looks something like:
....\
checkpassword \
qmail-pop3d Maildir
In this scenario, checkpassword does the following:
1. It reads the user name, password, and other information
from file descriptor 3.
2. It exits if the authentication against /etc/password
fails.
3. It suid's to the user.
4. It chdir's to the user's home directory.
5. It runs qmail-pop3d which expects the name of
a maildir as its only (unqualified) argument.
3. bincimapd & checkpassword ============================
Binc IMAP works very similarly to qmail-pop3d, but it is invoked in a command line that looks something like this:
....\
checkpassword \
bincimapd
Note that there are some small differences:
1. bincimapd normally gets the maildir name from the
config file instead of from the command line.
2. Unpatched bincimapd-1.2.7final exists 111 if it sees
an unqualified command argument.
That is, there is a slight difference in the authentication interface between qmail-pop3d and bincimapd, which is of no consequence when using checkpassword.
4. qmail-pop3d & checkvpw ==========================
checkvpw is a replacement for checkpassword for use with virturual mail users; that is, mail users without a unix login. It is invoked in a command line that looks something like:
....\
checkvpw \
qmail-pop3d Maildir
In this scenario, checkpassword does the following:
1. It takes the user name and splits it into two at
the "@" sign
- e.g. [EMAIL PROTECTED] => "joe" and "virtual.com"
2. If there was no "@" sign, then the user name is the
"full user name" and the next step is skipped
3. It looks up the host name in the virtualdomains file
and prepends the real user name to the virtual user
name giving the full user name
- e.g. virtaldomains contains "virtual.com:handler",
then "joe" => "handler-joe"
4. If the "full user name" is found in /etc/password,
then checkvpw behaves just like checkpassword
5. If the "full user name" is not found in /etc/password,
then it removes the "extension" (e.g. the "-*") to
create the real user name
- e.g. "handler" is the real user name for
"handler-joe"
6. It then chdir's to the "real user"'s home directory
7. It now tries to authenticate the extension against the
password file found in the current directory
- e.g. "joe" & password is authenticated against
"~handler/password"
8. checkvpw exits if the authentication fails
9. It replaces the last argument on the command line
with "users/<extension>"
- e.g. "Maildir" => "handler/users/joe"
10. It runs qmail-pop3d with the "rewritten" Maildir
- e.g. it runs "qmail-pop3d ./handler/users/joe"
(Don't ask me how the leading "./" got there)
As can be seen by this procedure, checkvpw uses some "trickery" to get qmail-pop3d to handle both real and virtual users together.
5. qmail-pop3d & auth_pop =========================
auth_pop works like checkpassword, except that uses an LDAP directory instead of /etc/password. That is, it is invoked in a command line that looks something like:
....\
auth_pop \
qmail-pop3d Maildir
There is one difference:
1. auth_pop will autocreate the "Maildir" subdirectory
(the last line on the command line) if it does not
exist (similar to Binc autocreating the INBOX)
That is, every user gets a Maildir directory. This eliminates the distinction between virtual users and real users, since every user is listed uniformly in the directory (which qmail-ldap also uses for deliveries) and means that auth_pop does not need to resort to the trickery employed by checkvpw to set the correct directory.
6. bincimapd & checkvpw =======================
This is where things get trick due to the trickery employed by checkvpw and the differences between qmail-pop3d and bincimapd. To recap:
1. For non-virtual users, checkvpw will authenticate
against /etc/password and will chdir to the user's
home directory if the authentication was successful
- This works because bincimapd is invoked in a
directory that contains a Maildir (or IMAPdir or
whatever is specified in Binc's config file)
2. For virtual users, checkvpw will remove the
"extension" and chdir to the "real user"'s home
directory and authenticate against the password
file in the current directory and stay there if
the authentication is successful
- This is not good because bincimapd is going to
be invoked from the wrong directory and even
then bincimapd is expecting a Maildir (or IMAPdir
or whatever is specified in Binc's config file)
- Furthermore, if you try to follow the Binc way
of doing things and adding a parameter to
bincimapd (namely "--mailbox-path=Maildir") checkvpw
will replace it with the "extension"
("--mailbox-path=" and all!-)
I know of three ways to address this problem:
1. bincimapd could be changed to accept an unqualified
maildir parameter ala qmail-pop3d
- this would bring bincimapd and qmail-pop3d into
harmony
2. qmail-pop3d and checkvpw could be changed to use
a different mechanism for passing the maildir to
qmail-pop3d (e.g. through shell variables)
3. a wrapper could be inserted between checkvpw and
bincimapd:
- The wrapper (perl;untested) would look like:
#!/usr/bin/perl
# preserve all parameters except the last
chdir pop;
exec @ARGV if @ARGV;
- It would be invoked in a command line that looks
something like:
....\
checkvpw \
wrapper \
bincimapd Maildir
#YES the "Maildir" is necessary in the line above
- The following line in Binc's config file
path = "Maildir",
would have to be changed to
path = ".",
Note that although "Maildir" appears to be an argument to bincimapd, it is actually consumed by the wrapper. Furthermore, Maildir will be changed (to the subdirectory for the virtual user) for a virtual user.
7. bincimapd & auth_pop ========================
authpop requires the same wrapper as used with checkvpw. It should be invoked in a command line that looks something like:
....\
auth_pop \
wrapper \
bincimapd Maildir
Once again, Maildir is necessary so that auth_pop can ensure that it exists, and it is removed from the command by the wrapper so that bincimapd does not complain. Unlike checkvpw, there is no need to change Binc's config file.
8. Conclusion =============
A design decision (maybe more than one) was made for either checkvpw or qmail-pop3d resulting in checkvpw employing trickery to make qmail-pop3d work with both local and virtual users. This trickery is not required in checkpassword because it does handle virtual users nor is it required for auth_pop which handles local and virtual users uniformly.
A different design decision was made for bincimapd which makes its interface slightly different from qmail-pop3d. While it works fine with checkpassword and auth_pop, it requires a wrapper function to rearrange the tricery employed by checkvpw.
Ideally, qmail-pop3d and bincimapd should have the same interface with respect to authentication and directory selection so that they can be interchanged simply by changing qmail-pop3d to bincimapd (and vice versa) regardless of the authentication program being used. This probably means that the maildir (path in the Binc config file) should be passed through environment variables (and not on the command line) and that a better mechanism is required to make local and virtual users more similar (as is done for ldap).
Given that the interface to qmail-pop3d is not likely going to change in the near future, a design decision needs to be revisited for Binc IMAP, namely:
- Should bincimapd's interface be changed to align it better with qmail-pop3d; or,
- Should bincimapd's interface be left alone and the differences with qmail-pop3d be better documented.
Its not clear to me which of these two alternatives is the better one.
Regards, Henry
-- Henry Baragar Principal, Technical Architecture 416-453-5626 Instantiated Software Inc. http://www.instantiated.ca
