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. email@example.com and firstname.lastname@example.org) 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:
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.
Perhaps the most important part of this process is to understand the changes in the paradigm.
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 email@example.com firstname.lastname@example.org virtdomains: yes defaultdomain: exampleisp.net
This example has three domains: exampleisp.net, hisdomain.com, and herdomain.net. admin can administer all three domains, while email@example.com and firstname.lastname@example.org 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.
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.
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.
In general, follow the basic configuration instructions. Here are a few caveots:
The only changes you'll need to make to the mail client is to change the username to the fully qualified domain name, ie email@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)
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. firstname.lastname@example.org) 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:
To create a new INBOX for user 'test' in domain 'example.com':
cm email@example.comTo list all mailboxes in domain 'example.com':