Virtual domain support for qmail-ldap
=====================================

Author: Kristof Bajnok (bajnokk@sztaki.hu) 
9 January 2004

--------

The term "virtual domain support" means that you can define seperate ldap 
brunches (base DN's) for your different domains used in authentication in
order to have them being administered independently.

There are basically two types of virtual domain support
  - IP based virtual domains
  - username based virtual domains

1. IP based virtual domains
---------------------------
You should use IP based virtual domains, if you have to integrate several 
different user databases, coming from non-virtual environment. In this case,
you can rarely guarantee that usernames are unique.
If you don't want your users to change their usernames from 'user' to 
'user@domain' form, you should use different IP addresses for each
virtual domain, so that you can define a base DN for each address.
The whole concept of this implementation assumes that you are using a tcp 
wrapper in front of your [smtp|pop3|imap] servers, which sets the TCPLOCALIP 
environment variable, containing the IP address (of the server) to which the
client is bound. Tcpserver (included in ucspi-tcp package) is OK.
When a connection comes in, the base DN being used for authenticating the 
user is selected according to TCPLOCALIP.
You can specify 'local ip' -> 'ldap' basedn mappings in control/ipvirtualbasedn.
The form of this file is as follows: ip_address:ldap_basedn
You can specify more than one mapping, the file is multiline. Only one mapping
per a single IP address is allowed. 
Unless a mapping is defined for TCPLOCALIP, control/ldapbasedn will be used.

2. Username based virtual domains
---------------------------------
If your users have usernames that have a "virtual domain part" (something 
that can identify the virtual domain, ie: john@domain.com), you can assign
different ldap basedn's for each domain. 
By default the separator between user and domain parts is '@'. You can change
it by editing qldap.h (VIRTUAL_SEPARATOR), but then you should take a look at
check.c!
You can define 'domain' -> 'ldap basedn' mappings in control/namedvirtualbasedn
The form of this file is as follows: domain:ldap_basedn
You can specify more than one mapping, the file is multiline. Only one mapping
per domain is allowed.
In the LDAP database the uid field of the users in the virtual domain brunch 
should contain only the "username" part, and not "@domain". (Users still have 
to use username@domain form in their mail client.)
If the domain is not found in control/namedvirtualbasedn, control/ldapbasedn
will be used and authentication will go as usual (searching for
uid=username@domain).

Mixing IP-based and username based virtual domains
--------------------------------------------------
The procedure is as follows:
 - if the username has a virtual domain part, then the basedn will be set
   according to control/namedvirtualbasedn
 - control/ipvirtualbasedn is only checked if username doesn't contain 
   virtual domain
 - if neither approach succeeds, ldap search for authentication will have a 
   basedn defined in control/ldapbasedn (and username unchanged).


Please send your questions and comments to bajnokk@sztaki.hu