Virtual Domains
***************


What are virtual domains?
=========================

Virtual domains means hosting a service for more than one domain on a
single server.  Cyrus IMAP has the ability to host IMAP/POP mailboxes
for multiple domains (for example: "test@cyrusisgreat.org" and
"test@ilovecyrus.com") on a single server or Murder.

Cyrus needs to know which domain to use when a mailbox is accessed.
There are two ways in which Cyrus can determine the domain:

Fully qualified userid
   The client logs in with a userid containing the domain in which the
   user belongs (for example: "test@cyrusisgreat.org" or
   "test@ilovecyrus.com")

IP address
   The server looks up the domain based on the IP address of the
   receiving interface (useful for servers with multiple NICs or those
   using IP aliasing)

If the "virtdomains" option is set to "off" (or "no", "0", "false"),
Cyrus does not know or care about domains, and only ever considers the
local part of email addresses.  This configuration is never
recommended, but is currently the default.

If the "virtdomains" option is set to "userid", then only the fully
qualified userid is used.  This is the only recommended configuration
for new deployments, and in the future may become the default or only
option. Existing deployments should strongly consider migrating
towards this configuration.

If the "virtdomains" option is set to "on" (or "yes", "1", "true"),
Cyrus uses both mechanisms to work out the domain (with the fully
qualified userid taking precedence).  This configuration is not
recommended.

Note:

  If you are providing calendaring services, you MUST use the
  "virtdomains: userid" configuration.  Calendaring services require a
  consistent single authoritative fully-qualified email address for
  each user in order to function, and this is the only configuration
  that provides it.The "virtdomains: off" and "virtdomains: on"
  configurations both allow users' domains to be changed from outside
  of Cyrus without Cyrus knowing about it, which fundamentally breaks
  calendaring.  These configurations are only suitable for IMAP-only
  deployments.


Concepts
========

Everyone is in a domain
   It's best to think of every user as existing inside a domain.
   Unqualified users are technically inside the "defaultdomain".

Names can be qualified
   Global admins can reference mailboxes and IDs by qualified names.
   That is, for any given mailbox command, you can add "@domain" to
   the end of the mailbox name.

   Here are some examples:

      * "cyradm> create user.lukecage@example.net" - create a user

      * "cyradm> create user.mercedesknight@example.net" - create
        another user

      * "cyradm> setquota user.lukecage@example.net 50000" - define a
        quota

      * "cyradm> setaclmailbox user.lukecage@example.net
        mercedesknight@example.net read" - give Mercedes Knight read
        access to Luke Cage's mailbox

      * "cyradm> listmailbox *@example.net" - list all mailboxes in
        the example.net domain

Each mailbox exists in only one domain

Domains are mutually exclusive
   Users only have access to mailboxes within their own domain (intra-
   domain).  The following example will not work: "setacl
   user.mercedesknight@herdomain.com lukecage@hisdomain.com read".

Global and Domain admins
   The Cyrus virtual domains implementation supports per-domain
   administrators as well as global (inter-domain) administrators.

   Domain-specific administrators are specified with a fully qualified
   userid in the "admins" option (e.g., "admin@example.net") and only
   have access to mailboxes in the associated domain.

   Global administrators are specified with unqualified userids.

MOST OF THIS SHOULD BE IN DEPLOYMENT GUIDE?


Quick Start
===========

* Add "virtdomains: userid" to imapd.conf(5)

* Add a "defaultdomain" entry to imapd.conf(5)

* Use cyradm (as a global or domain admin) to create mailboxes for
  each domain.


Configuration
=============

Support for virtual domains is enabled by turning on the "virtdomains"
option in imapd.conf(5).

When upgrading from a single domain installation to a virtual domain
installation, the name of the existing domain (domain of the server
hostname) should be specified using the "defaultdomain" option in
imapd.conf(5).  This allows users to continue to access their
mailboxes using unqualified userids.  For example, if the primary IP
address on your server resolves to 'www.xxx.yyy.zzz', then set
"defaultdomain" to 'xxx.yyy.zzz'.

Even for new installations, set the "defaultdomain" to the "real"
domain of the server (domain of its primary hostname). See
Administrators for further discussion.

Here is a sample "imapd.conf" with a minimal set of configuration
options:

   configdirectory: /var/imap
   partition-default: /var/spool/cyrus
   admins: admin lukecage.admin@hisdomain.com mercedesknight.admin@herdomain.net
   virtdomains: yes
   defaultdomain: exampleisp.net

This example has three domains: exampleisp.net, hisdomain.com, and
herdomain.net.  "admin" can administer all three domains, while
"lukecage.admin@hisdomain.com" and
"mercedesknight.admin@herdomain.net" can only administer their
respective domains.

Everyday users should not be administrators.  In the above example,
Mercedes Knight and Luke Cage have separate administrative accounts
for their domains.


Multiple IP Addresses
---------------------

In order to use a multiple IP address configuration, the server must
be able to do a reverse lookup on the IP address to determine the
hostname of the receiving interface.  For example:

   192.168.0.1  ->  mail.example.com
   192.168.0.2  ->  mail.example.net
   192.168.0.3  ->  mail.foo.bar

Once the server obtains the fully qualified hostname of the interface,
it removes the localpart (i.e., 'mail') and uses the remainder as the
domain for any user that logs in.

This address to hostname mapping would usually be done via DNS,
"/etc/hosts", NIS, etc.  Configuration of the various naming services
is beyond the scope of this document.


Delivering mail
---------------

To deliver mail to your virtual domains, configure your MTA so that
the envelope recipient (RCPT TO) passed to "lmtpd" is fully qualified
with the correct domain.


Configuring Sendmail
~~~~~~~~~~~~~~~~~~~~

Follow the basic configuration instructions.

Some items to be aware of:

* It is easiest to use the mailertable to route mail to Cyrus, rather
  than adding the domain to the local-host-names file ($w). This
  prevents Sendmail from changing the domain name to the local host
  name.

     "example.com              cyrusv2:/var/imap/socket/lmtp"

* You'll have to use the Cyrus mailer in LMTP mode, and you'll have to
  change the mailer flags so that it provides the full domain while
  communicating via LMTP.  Specifically these changes:

     "S=EnvFromSMTP/HdrFromSMTP, R=EnvToSMTP"


Mail Clients
------------

The only changes you'll need to make to mail clients is to change
usernames to the fully qualified domain names, i.e.,
"user@example.com". The "user%example.com" form of userid is also
supported.

Users in the default domain will not need to reconfigure their clients
(as unqualified userids are assumed to be in the default domain).


Administrators
--------------

The Cyrus virtual domains implementation supports per-domain
administrators as well as "global" (inter-domain) administrators.
Domain-specific administrators are specified with a fully qualified
userid in the "admins" option (e.g., "admin@example.net") and only
have access to mailboxes in the associated domain.  Mailbox names
should be specified in the same fashion as on a single domain
configuration.

Global administrators are specified with an unqualified userid in the
"admins" option and have access to *any* mailbox on the server.
Because global admins use unqualified userids, they belong to the
"defaultdomain".  As a result, you CANNOT have a global admin without
specifying a "defaultdomain".  Note that when trying to login as a
global admin to a multi-homed server from a remote machine, it might
be necessary to fully qualify the userid with the "defaultdomain".

Global admins must use "mailbox@domain" syntax when specifying
mailboxes outside of the "defaultdomain".  Examples (using "cyradm"):

To create a new INBOX for user 'test' in "defaultdomain":

   cm user.test

To create a new INBOX for user 'test' in domain 'example.com':

   cm user.test@example.com

To list all mailboxes in domain 'example.com':

   lm *@example.com
