install-virtdomains.html   [plain text]

<!-- $Id: install-virtdomains.html,v 1.4 2006/11/30 17:11:16 murch Exp $ -->
<TITLE>Configuring Virtual Domains
<h1>Configuring Virtual Domains


<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></tt> and
<tt></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>

<li>Fully qualified userid - the client logs in with a userid
containing the domain in which the user belongs (e.g
<tt></tt> or <tt></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>

<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>

<p>Perhaps the most important part of this process is to understand
the changes in the paradigm.</p>

<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
<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:
    <li><tt>cyradm> create</tt> <em>(create a
    <li><tt>cyradm> create</tt> <em>(create
    another user)</em></li>
    <li><tt>cyradm> setquota 50000</tt>
    <em>(define a quota)</em></li>
    <li><tt>cyradm> setaclmailbox read</tt> <em>(give Jill read access to Rick's
    <li><tt>cyradm> listmailbox *</tt> <em>(list all
    mailboxes in the domain)</em></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 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></tt>) and only
    have access to mailboxes in the associated domain.  Global
    administrators are specified with an unqualified userid.

<h2>Quick Start</h2>
<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>

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 '',
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

configdirectory: /var/imap
partition-default: /var/spool/imap
admins: admin
virtdomains: yes

<p>This example has three domains:,, and  <tt>admin</tt> can administer all three domains, while
<tt></tt> and
<tt></tt> can only administer their respective

<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>  ->  ->  ->

<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>

<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

<pre>              cyrusv2:/var/imap/socket/lmtp

<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:


<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></tt>.
Note that to support some mail clients, the <tt></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></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

<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>

   cm user.test

<p>To create a new INBOX for user 'test' in domain '':</p>


To list all mailboxes in domain '':</p>

   lm *

last modified: $Date: 2006/11/30 17:11:16 $