Configuring Virtual Domains

Introduction

    Virtual domains is the practice of hosting a service for more than one
    domain on one server. Cyrus IMAP has the ability to host IMAP/POP
    mailboxes for multiple domains (e.g. test@example.com and
    test@example.net) on a single server or Murder. 

    In order to accomplish this, Cyrus needs to know which domain to look
    in 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 (e.g
        test@example.com or test%example.net) 
      * IP address - the server looks up the domain based on the IP address
        of the receiving interface (useful for servers with multiple NICs
        or using IP aliasing) 

    Both of these methods are active if the virtdomains option is set to on
    (or yes, 1, true) and can be used in conjunction with one another. If
    the virtdomains option is set to userid, then only the first method is
    used. Note that a fully qualified userid takes precedence over a domain
    obtained from the IP address. 

Concepts

    Perhaps the most important part of this process is to understand the
    changes in the paradigm. 

      * 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.jill@example.net (create a user) 
          * cyradm> create user.rick@example.net (create another user) 
          * cyradm> setquota user.rick@example.net 50000 (define a quota) 
          * cyradm> setaclmailbox user.rick@example.net jill@example.net
            read (give Jill read access to Rick'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.jill@herdomain.com
        rick@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 an
        unqualified userid. 

Quick Start

     1. Add virtdomains: yes to imapd.conf 
     2. Add a defaultdomain entry to imapd.conf 
     3. 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. 

    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. 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, it is recommended that the "real" domain of
    the server (domain of its primary hostname), be set to the
    defaultdomain. See Administrators below for further discussion. 

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

    configdirectory: /var/imap
    partition-default: /var/spool/imap
    admins: admin rick.admin@hisdomain.com jill.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
    rick.admin@hisdomain.com and jill.admin@herdomain.net can only
    administer their respective domains. 

    Note that everyday users should not be administrators. In the above
    example, Jill and Rick 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 (ie, '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

    In general, follow the basic configuration instructions. Here are a few
    caveots: 

      * 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 LMTP. Specifically these changes: 

        S=EnvFromSMTP/HdrFromSMTP, R=EnvToSMTP

Mail Clients

    The only changes you'll need to make to the mail client is to change
    the username to the fully qualified domain name, ie user@example.com.
    Note that to support some mail clients, the user%example.com form of
    userid is also supported. Users in the default domain will not need to
    reconfigur their clients (as unqualified userids are assumed to be in
    the default domain) 

Administration

    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 can NOT have a global admin without
    specifying a defaultdomain. Note that when trying to login as a global
    admin to a multi-homed server from remote machine, it might be
    necessary to fully qualify the userid with the defaultdomain. 

    Global admins must use a 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