install-virtdomains.html [plain text]
<!-- $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>