Debian Codegraph @

doc/html/_sources/imap/concepts/features/virtual-domains.rst.txt

raw
1 ===============
2 Virtual Domains
3 ===============
4
5 What are virtual domains?
6 =========================
7
8 Virtual domains means hosting a service for more than one
9 domain on a single server. Cyrus IMAP has the ability to host IMAP/POP
10 mailboxes for multiple domains (for example: ``[email protected]`` and
11 ``[email protected]``) on a single server or Murder.
12
13 Cyrus needs to know which domain to use when a mailbox is accessed.
14 There are two ways in which Cyrus can determine the domain:
15
16 Fully qualified userid
17 The client logs in with a userid
18 containing the domain in which the user belongs (for example:
19 ``[email protected]`` or ``[email protected]``)
20
21 IP address
22 The server looks up the domain based on the IP
23 address of the receiving interface (useful for servers with multiple
24 NICs or those using IP aliasing)
25
26 If the ``virtdomains`` option is set to ``off`` (or ``no``, ``0``, ``false``),
27 Cyrus does not know or care about domains, and only ever considers the local
28 part of email addresses. This configuration is never recommended, but is
29 currently the default.
30
31 If the ``virtdomains`` option is set to ``userid``, then only the
32 fully qualified userid is used. This is the only recommended configuration
33 for new deployments, and in the future may become the default or only option.
34 Existing deployments should strongly consider migrating towards this
35 configuration.
36
37 If the ``virtdomains`` option is set to ``on`` (or ``yes``, ``1``, ``true``),
38 Cyrus uses both mechanisms to work out the domain (with the fully qualified
39 userid taking precedence). This configuration is not recommended.
40
41 .. note::
42 If you are providing calendaring services, you MUST use the
43 ``virtdomains: userid`` configuration. Calendaring services require
44 a consistent single authoritative fully-qualified email address for
45 each user in order to function, and this is the only configuration
46 that provides it.
47
48 The ``virtdomains: off`` and ``virtdomains: on`` configurations both
49 allow users' domains to be changed from outside of Cyrus without Cyrus
50 knowing about it, which fundamentally breaks calendaring. These
51 configurations are only suitable for IMAP-only deployments.
52
53 Concepts
54 ========
55
56 Everyone is in a domain
57 It's best to think of every user as existing inside a domain. Unqualified users are technically inside the ``defaultdomain``.
58
59 Names can be qualified
60 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.
61
62 Here are some examples:
63
64 * ``cyradm> create user/[email protected]`` - create a user
65 * ``cyradm> create user/[email protected]`` - create another user
66 * ``cyradm> setquota user/[email protected] 50000`` - define a quota
67 * ``cyradm> setaclmailbox user/[email protected] [email protected] read`` - give Mercedes Knight read access to Luke Cage's mailbox
68 * ``cyradm> listmailbox *@example.net`` - list all mailboxes in the example.net domain
69
70 Each mailbox exists in only one domain
71
72 Domains are mutually exclusive
73 Users only have access to mailboxes within their own domain (intra-domain). The following
74 example will not work: ``setacl user/[email protected]
75 [email protected] read``.
76
77 Global and Domain admins
78 The Cyrus virtual domains
79 implementation supports per-domain administrators as well as
80 global (inter-domain) administrators.
81
82 Domain-specific administrators are specified with a fully qualified userid in the
83 ``admins`` option (e.g., ``[email protected]``) and only
84 have access to mailboxes in the associated domain.
85
86 Global administrators are specified with unqualified userids.
87
88
89 MOST OF THIS SHOULD BE IN DEPLOYMENT GUIDE?
90
91 Quick Start
92 ===========
93
94 * Add ``virtdomains: userid`` to :cyrusman:`imapd.conf(5)`
95 * Add a ``defaultdomain`` entry to :cyrusman:`imapd.conf(5)`
96 * Use cyradm (as a global or domain admin) to create mailboxes for each domain.
97
98 Configuration
99 =============
100
101 Support for virtual domains is enabled by turning on the ``virtdomains`` option in :cyrusman:`imapd.conf(5)`.
102
103 When upgrading from a single domain installation to a virtual
104 domain installation, the name of the existing domain (domain of the
105 server hostname) should be specified using the ``defaultdomain``
106 option in :cyrusman:`imapd.conf(5)`. This allows users to continue to
107 access their mailboxes using unqualified userids. For example, if the
108 primary IP address on your server resolves to 'www.xxx.yyy.zzz',
109 then set ``defaultdomain`` to 'xxx.yyy.zzz'.
110
111 Even for new installations, set the ``defaultdomain`` to the "real"
112 domain of the server (domain of its primary hostname).
113 See `Administrators`_ for further discussion.
114
115 Here is a sample ``imapd.conf`` with a minimal set of configuration
116 options::
117
118 configdirectory: /var/imap
119 partition-default: /var/spool/cyrus
120 admins: admin [email protected] [email protected]
121 virtdomains: yes
122 defaultdomain: exampleisp.net
123
124 This example has three domains: exampleisp.net, hisdomain.com, and
125 herdomain.net. ``admin`` can administer all three domains, while
126 ``[email protected]`` and
127 ``[email protected]`` can only administer their respective
128 domains.
129
130 Everyday users should not be administrators. In the
131 above example, Mercedes Knight and Luke Cage have separate administrative accounts for
132 their domains.
133
134 Multiple IP Addresses
135 ---------------------
136
137 In order to use a multiple IP address configuration, the server must
138 be able to do a reverse lookup on the IP address to determine the
139 hostname of the receiving interface. For example::
140
141 192.168.0.1 -> mail.example.com
142 192.168.0.2 -> mail.example.net
143 192.168.0.3 -> mail.foo.bar
144
145 Once the server obtains the fully qualified hostname of the
146 interface, it removes the localpart (i.e., 'mail') and uses the
147 remainder as the domain for any user that logs in.
148
149 This address to hostname mapping would usually be done via DNS,
150 ``/etc/hosts``, NIS, etc. Configuration of the various naming
151 services is beyond the scope of this document.
152
153 Delivering mail
154 ---------------
155
156 To deliver mail to your virtual domains, configure your MTA so that
157 the envelope recipient (RCPT TO) passed to ``lmtpd`` is fully
158 qualified with the correct domain.
159
160 Configuring Sendmail
161 ####################
162
163 Follow the basic :ref:`configuration instructions <installing>`.
164
165 Some items to be aware of:
166
167 * It is easiest to use the mailertable to route mail to Cyrus,
168 rather than adding the domain to the local-host-names file ($w).
169 This prevents Sendmail from changing the domain name to the local host name.
170
171 ``example.com cyrusv2:/var/imap/socket/lmtp``
172
173 * You'll have to use the Cyrus mailer in LMTP mode, and you'll have
174 to change the mailer flags so that it provides the full domain while
175 communicating via LMTP. Specifically these changes:
176
177 ``S=EnvFromSMTP/HdrFromSMTP, R=EnvToSMTP``
178
179 Mail Clients
180 ------------
181
182 The only changes you'll need to make to mail clients is to change
183 usernames to the fully qualified domain names, i.e., ``[email protected]``.
184 The ``user%example.com`` form of userid is also supported.
185
186 Users in the default domain will not
187 need to reconfigure their clients (as unqualified userids are assumed to
188 be in the default domain).
189
190 Administrators
191 --------------
192
193 The Cyrus virtual domains implementation supports per-domain
194 administrators as well as "global" (inter-domain) administrators.
195 Domain-specific administrators are specified with a
196 fully qualified userid in the ``admins`` option
197 (e.g., ``[email protected]``) and only have access to mailboxes in
198 the associated domain. Mailbox names should be specified in the same
199 fashion as on a single domain configuration.
200
201 Global administrators are specified with an unqualified userid in the
202 ``admins`` option and have access to *any* mailbox on the
203 server. Because global admins use unqualified userids, they belong
204 to the ``defaultdomain``. As a result, you CANNOT have a global
205 admin without specifying a ``defaultdomain``. Note that when
206 trying to login as a global admin to a multi-homed server from a remote
207 machine, it might be necessary to fully qualify the userid with the
208 ``defaultdomain``.
209
210 Global admins must use ``mailbox@domain`` syntax when
211 specifying mailboxes outside of the ``defaultdomain``. Examples
212 (using ``cyradm``):
213
214 To create a new INBOX for user 'test' in ``defaultdomain``::
215
216 cm user/test
217
218 To create a new INBOX for user 'test' in domain 'example.com'::
219
220 cm user/[email protected]
221
222 To list all mailboxes in domain 'example.com'::
223
224 lm *@example.com