
			IP BASED VIRTUAL HOSTING

You can specify different configuration parameters depending on address
client is connected to. Global configuration file is parsed
before any client-server interaction. All parsed options from global
configuration file have effect (It sounds weird, but you will understand
it after reading "non-IP based virtual hosting" section). 
Remember - IP addresses are used in IP based virtual hosting, you shouldn't
specify host names! Host names are used in non-IP based virtual hosting,
which is described in other section.
Some example configuration:

<Global>
	ChangeGID	yes
	AllowAPOP	yes
	AutoLogoutTime	10m
</Global>

<VirtualHost 192.168.1.1>
	APOPServerName	firma1.com.pl
	MailDropName	/var/mail/firma1/%s
	MailDropType	mailbox
</VirtualHost>

<VirtualHost 192.168.1.2>
	APOPServerName	firma2.com.pl
	MailDropName	/var/mail/firma2/%s
	MailDropType	mailbox
</VirtualHost>

If client connects to 192.168.1.1 options from <Global>
and <VirtualHost 192.168.1.1> blocks are parsed. Options from
<VirtualHost 192.168.1.2> block are ignored. If client connects to 192.168.1.2
options from <Global> and <VirtualHost 192.168.1.2> blocks are parsed.
Options from <VirtualHost 192.168.1.1> are ignored.
Support for IP based virtual hosting is compiled in by default (./configure
--enable-configfile).



			NON-IP BASED VIRTUAL HOSTING

You can have few virtual servers on one IP. This approach is something weird,
because there is no support for virtual hosting in POP3 protocol.
In non-IP virtual hosting domain names matter. IP adresses are specific
to IP based virtual hosting. Users must login with name@domain (or user%domain
if client doesn't allow '@' character in username) as their user names.
The domain part is used when global configuration file is parsed.
Some example configuration:

<Global>
	ChangeGID	yes
	AllowAPOP	yes
	AutoLogoutTime	10m
</Global>

<VirtualHost firma1.com.pl>
	MailDropName	/var/mail/firma1/%s
	MailDropType	mailbox
</VirtualHost>

<VirtualHost firma2.com.pl>
	MailDropName	/var/mail/firma2/%s
	MailDropType	mailbox
</VirtualHost>

If client logs in as user@firma1.com.pl, options from <Global>
and <VirtualHost firma1.com.pl> blocks are parsed. Options from
<VirtualHost firma2.com.pl> block are ignored. If client logs in
as user@firma2.com.pl, options from <Global> and <VirtualHost firma2.com.pl>
blocks are parsed. Options from <VirtualHost firma1.com.pl> are ignored.

Remember: in non-IP virtual hosting global configuration file is parsed
after some client-server interaction, just before entering transaction state.
Server sends a greeting, client sends username and password. Some options
must be known before any client-server interaction, so they have no effect
in non-IP virtual hosting. For example: APOPServerName (it is sent
in greeting), AllowAPOP, AllowUser, SASLAllow (these option would be parsed
after user selects method of authentication), TLSAllow (TLS connection can
be established only in authentication state). You can specify these options,
but remember that they don't matter.

You should run ./configure --enable-nonip to add support for non-IP based
virtual hosting to server.

Remember: global configuration file is parsed first time (always) before
any client-server interaction. <Global> and <VirtualHost ipaddr> (IP based
virtual hosting) blocks matter then. If user specifies domain part in her/his
username and non-IP based virtual hosting is allowed configuration file
is parsed second time (<Global>, <VirtualHost ipaddr>,
<VirtualHost domainname> blocks matter). Non-IP based virtual hosting
isn't very efficient (configuration file is parsed twice).

You can disable non-IP based virtual hosting in <Global>, <VirtualHost ipaddr>
blocks (AllowNonIP option).

You can specify <VirtualHost ipaddr domainname> blocks. It has the same
effect as two separate <VirtualHost ipaddr>, <VirtualHost domainname>
blocks with the same options. Some example configuration:

<Global>
	ChangeGID	yes
	AllowAPOP	yes
	AutoLogoutTime	10m
</Global>

<VirtualHost 192.168.1.1 firma1.com.pl>
	APOPServerName	firma1.com.pl
	MailDropName	/var/mail/firma1/%s
	MailDropType	mailbox
</VirtualHost>

<VirtualHost 192.168.1.2 firma2.com.pl>
	APOPServerName	firma2.com.pl
	MailDropName	/var/mail/firma2/%s
	MailDropType	mailbox
</VirtualHost>



				USER MAPPING

You can map user names. Mapping means that user logs in with some "username",
but "mapname" is used for authentication. Also UID, GID, home directory
of "mapname" user are used. This allows you to have the same user names
for different virtual domains (for example: office@firma1.com.pl
and office@firma2.com.pl). User mapping can be performed in two ways:

- through user mapping database (UserMapFile option). You can create/maintain
  such database with spdbm(8) utility.
  
- an automated way, through PreAuthMap option.

Some example configuration:

<Global>
	ChangeGID	yes
	AllowAPOP	yes
	AutoLogoutTime	10m
	DoMapping	yes
</Global>

<VirtualHost 192.168.1.1 firma1.com.pl>
	PreAuthMap	f1-%s
	APOPServerName	firma1.com.pl
	MailDropName	/var/mail/firma1/%s
	MailDropType	mailbox
</VirtualHost>

<VirtualHost 192.168.1.2 firma2.com.pl>
	PreAuthMap	f2-%s
	APOPServerName	firma2.com.pl
	MailDropName	/var/mail/firma2/%s
	MailDropType	mailbox
</VirtualHost>

If user logs in as jurekb@firma1.com.pl (or connect to 192.168.1.1 address
and logs in as jurekb) he will be authenticated against f1-jurekb entry
from password database. UID/GID of f1-jurekb user will be used.

You should run ./configure --enable-mapping to add support for user mapping
to server.

User mapping is always disabled if SASLAllow is enabled.



			DOMAIN-PER-UID MECHANISM

You can have virtual domain with many users sharing one UID number.
Solid POP3 maintains their passwords/APOP secrets database.
Some example configuration:

<Global>
	ChangeGID	yes
	AllowAPOP	yes
	AutoLogoutTime	10m
	DpUIDEnable	yes
</Global>

<VirtualHost 192.168.1.1 firma1.com.pl>
	APOPServerName	firma1.com.pl
	MailDropName	/var/mail/firma1/%s
	MailDropType	mailbox
	DpUIDUser	firma1
	DpUIDDBFile	/etc/pop3/domains/firma1
</VirtualHost>

<VirtualHost 192.168.1.2 firma2.com.pl>
	APOPServerName	firma2.com.pl
	MailDropName	/var/mail/firma2/%s
	MailDropType	mailbox
	DpUIDUser	firma2
	DpUIDDBFile	/etc/pop3/domains/firma2
</VirtualHost>

For each user of virtual domain there is one entry in DpUIDDBFile database.
Each entry contains MD5-encrypted password, APOP secret, maildrop name
and maildrop type. You can create/maintain such database with spdbm(8) utility.
If user logs in as "username", entry for "username" is searched in database.
If it is found, user is authenticated against MD5-password (or APOP secret)
from this entry. Maildrop name and maildrop type from this entry are used.
Privileges (UID/GID/home directory) of DpUIDUser are used. All maildrops
from this virtual domain must be accessable for this user.

User can't authenticate through USER/PASS (APOP) mechanism
if his/her password (APOP secret) is empty. 

You needn't to specify maildrop name and type for each user. You can use
one global setting in <Global> or <VirtualHost ...> blocks. Just like
in example configuration.

Remember that DpUIDDBFile database must be readable for DpUIDUser.

You can't use UserOverride and SASLAllow options with domain-per-uid mechanism.
Server always disable UserOverride, SASLAllow options if DpUIDEnable
is enabled.

You should run ./configure --enable-dpuid to add support for domain-per-uid
mechanism to server.
