<!-- $Id: install-virtdomains.html,v 1.4 2006/11/30 17:11:16 murch Exp $ --> <HTML> <HEAD> <TITLE>Configuring Virtual Domains </title> </head> <h1>Configuring Virtual Domains </h1> <body> <h2>Introduction</h2> <p>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. <tt>test@example.com</tt> and <tt>test@example.net</tt>) on a single server or Murder.</p> <p>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:</p> <ul> <li>Fully qualified userid - the client logs in with a userid containing the domain in which the user belongs (e.g <tt>test@example.com</tt> or <tt>test%example.net</tt>)</li> <li>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)</li> </ul> <p>Both of these methods are active if the <tt>virtdomains</tt> option is set to <tt>on</tt> (or <tt>yes</tt>, <tt>1</tt>, <tt>true</tt>) and can be used in conjunction with one another. If the <tt>virtdomains</tt> option is set to <tt>userid</tt>, then only the first method is used. Note that a fully qualified userid takes precedence over a domain obtained from the IP address.</p> <h3>Concepts</h3> <p>Perhaps the most important part of this process is to understand the changes in the paradigm.</p> <ul> <li><b>Everyone is in a domain</b> - It's best to think of every user as existing inside a domain. Unqualified users are technically inside the <tt>defaultdomain</tt>.</li> <li><b>Names can be qualified</b> - Global admins can reference mailboxes and ids by qualified names. That is, for any given mailbox command, you can add <tt>@domain</tt> to the end of the mailbox name. Here are some examples: <ul> <li><tt>cyradm> create user.jill@example.net</tt> <em>(create a user)</em></li> <li><tt>cyradm> create user.rick@example.net</tt> <em>(create another user)</em></li> <li><tt>cyradm> setquota user.rick@example.net 50000</tt> <em>(define a quota)</em></li> <li><tt>cyradm> setaclmailbox user.rick@example.net jill@example.net read</tt> <em>(give Jill read access to Rick's mailbox)</em></li> <li><tt>cyradm> listmailbox *@example.net</tt> <em>(list all mailboxes in the example.net domain)</em></li> </ul></li> <li><b>Each mailbox exists in only one domain</b></li> <li><b>Domains are mutually exclusive</b> - Users only have access to mailboxes within their own domain (intra-domain). The following example will not work: <tt>setacl user.jill@herdomain.com rick@hisdomain.com read</tt>. <li><b>Global and Domain admins</b> - 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 <tt>admins</tt> option (e.g. <tt>admin@example.net</tt>) and only have access to mailboxes in the associated domain. Global administrators are specified with an unqualified userid. </ul> <h2>Quick Start</h2> <ol> <li>Add <tt>virtdomains: yes</tt> to <tt>imapd.conf</tt></li> <li>Add a <tt>defaultdomain</tt> entry to <tt>imapd.conf</tt></li> <li>Use cyradm (as a global or domain admin) to create mailboxes for each domain.</li> </ol> <h2>Configuration</h2> Support for virtual domains is enabled by turning on the <tt>virtdomains</tt> option in <tt>imapd.conf</tt>. <p>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 <tt>defaultdomain</tt> option in <tt>imapd.conf</tt>. 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 <tt>defaultdomain</tt> to 'xxx.yyy.zzz'. <p>Even for new installations, it is <i>recommended</i> that the "real" domain of the server (domain of its primary hostname), be set to the <tt>defaultdomain</tt>. See <a href=#admins>Administrators</a> below for further discussion. <p>Here is a sample <tt>imapd.conf</tt> with a minimal set of configuration options.</p> <pre> configdirectory: /var/imap partition-default: /var/spool/imap admins: admin rick.admin@hisdomain.com jill.admin@herdomain.net virtdomains: yes defaultdomain: exampleisp.net </pre> <p>This example has three domains: exampleisp.net, hisdomain.com, and herdomain.net. <tt>admin</tt> can administer all three domains, while <tt>rick.admin@hisdomain.com</tt> and <tt>jill.admin@herdomain.net</tt> can only administer their respective domains.</p> <p>Note that everyday users should not be administrators. In the above example, Jill and Rick have separate administrative accounts for their domains.</p> <h3>Multiple IP Addresses</h3> <p>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:</p> <pre><kbd> 192.168.0.1 -> mail.example.com 192.168.0.2 -> mail.example.net 192.168.0.3 -> mail.foo.bar </kbd></pre> <p>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.</p> <p>This address to hostname mapping would usually be done via DNS, <tt>/etc/hosts</tt>, NIS, etc. Configuration of the various naming services is beyond the scope of this document.</p> <h3>Delivering mail</h3> <p>To deliver mail to your virtual domains, configure your MTA so that the envelope recipient (RCPT TO) passed to <tt>lmtpd</tt> is fully qualified with the correct domain.</p> <h4>Configuring Sendmail</h4> <p>In general, follow the basic <a href=install-configure.html>configuration instructions</a>. Here are a few caveots:</p> <ul> <li> 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. <pre> example.com cyrusv2:/var/imap/socket/lmtp </pre></li> <li> 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: <pre> S=EnvFromSMTP/HdrFromSMTP, R=EnvToSMTP </pre></li> </ul> <h3>Mail Clients</h3> <p>The only changes you'll need to make to the mail client is to change the username to the fully qualified domain name, ie <tt>user@example.com</tt>. Note that to support some mail clients, the <tt>user%example.com</tt> 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)</p> <a name="admins"><h3>Administration</h3></a> <p>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 <tt>admins</tt> option (e.g. <tt>admin@example.net</tt>) 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.</p> <p>Global administrators are specified with an unqualified userid in the <tt>admins</tt> option and have access to <i>any</i> mailbox on the server. Because global admins use unqualified userids, they belong to the <tt>defaultdomain</tt>. As a result, you can NOT have a global admin without specifying a <tt>defaultdomain</tt>. 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 <tt>defaultdomain</tt>.</p> <p>Global admins must use a <tt>mailbox@domain</tt> syntax when specifying mailboxes outside of the <tt>defaultdomain</tt>. Examples (using <tt>cyradm</tt>):</p> <p>To create a new INBOX for user 'test' in <tt>defaultdomain</tt>:</p> <pre><kbd> cm user.test </kbd></pre> <p>To create a new INBOX for user 'test' in domain 'example.com':</p> <pre><kbd> cm user.test@example.com </kbd></pre> To list all mailboxes in domain 'example.com':</p> <pre><kbd> lm *@example.com </kbd></pre> <P><HR> last modified: $Date: 2006/11/30 17:11:16 $ </BODY></HTML>