summaryrefslogtreecommitdiff
path: root/Administrator_Guide/en-US/Hosted_Kolab_Groupware_Setup.xml
blob: fca24a1f47f8b3601db02b537b3b2a6153b35782 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Administrator_Guide.ent">
%BOOK_ENTITIES;
]>
<chapter id="chap-Administrator_Guide-Hosted_Kolab_Groupware_Setup">
    <title>Hosted Kolab Groupware Setup</title>
    <para>
        A hosted Kolab Groupware setup offers users or customers the opportunity to get one or more Kolab Groupware accounts by registering for an account, perhaps including payment.
    </para>
    <para>
        The nature of a hosted Kolab Groupware setup is such that;
    </para>
    <para>
        <itemizedlist>
            <listitem>
                <para>
                    Two or more isolated domains exist. One domain is the <emphasis>management domain</emphasis>, and the Kolab Groupware <emphasis>primary domain</emphasis>. The other domain is added later, after the setup of the management domain, and is considered the <emphasis>primary hosted domain</emphasis>.
                </para>
                <para>
                    The management domain contains the system and service users, and is intended for only the users of the organization providing the hosted Kolab Groupware deployment.
                </para>
                <para>
                    The primary hosted domain can have one or more domain aliases allowing users that register to choose between the options (for example "@example.org" or "@example.eu").
                </para>

            </listitem>
            <listitem>
                <para>
                    Users register (perhaps including payment) for a <emphasis>hosted plan</emphasis>, and are added to a <emphasis>hosted domain</emphasis>. Each hosted plan offers the user certain features, or lifts restrictions, and as such is a different type of account.
                </para>

            </listitem>

        </itemizedlist>

    </para>
    <procedure id="proc-Administrator_Guide-Hosted_Kolab_Groupware_Setup-Setting_up_Hosted_Kolab_Groupware">
        <title>Setting up Hosted Kolab Groupware</title>
        <para>
            This procedure assumes an existing, default Kolab Groupware deployment is available.
        </para>
        <step>
            <para>
                Add a hosted Kolab service account. This procedure uses a username of <literal>hosted-kolab-service</literal>, which is added to the management domain
            </para>
            <para>

<screen># <userinput>ldapadd -x -h localhost -D "cn=Directory Manager" -w $password</userinput>
dn: uid=hosted-kolab-service,ou=Special Users,<replaceable>$management_domain_root_dn</replaceable>
objectclass: top
objectclass: inetorgperson
objectclass: person
uid: hosted-kolab-service
cn: Hosted Kolab Service Account
sn: Service Account
givenname: Hosted Kolab
userpassword: <replaceable>$password</replaceable>

</screen>

            </para>

        </step>
        <step>
            <para>
                Make the list of domain name spaces accessible for the hosted Kolab service account:
            </para>
            <para>

<screen># <userinput>ldapmodify -x -h localhost -D "cn=Directory Manager" -w $password \</userinput>
&gt; <userinput>-f -</userinput>
dn: cn=kolab,cn=config
changetype: modify
add: aci
aci: (targetattr = "*") (version 3.0;acl "Hosted Kolab Services";allow
&nbsp;&nbsp;(read,compare,search)(userdn = "ldap:///uid=hosted-kolab-service,ou=
&nbsp;&nbsp;Special Users,<replaceable>$management_domain_root_dn</replaceable>");)

</screen>

            </para>

        </step>
        <step>
            <para>
                Prevent the hosted Kolab service account from reading the management domain, effectively hiding the management domain from the selection of available domains to register in;
            </para>
            <para>

<screen># <userinput>ldapmodify -x -h localhost -D "cn=Directory Manager" -w $password</userinput>
dn: associateddomain=<replaceable>$management_domain</replaceable>,cn=kolab,cn=config
changetype: modify
add: aci
aci: (targetattr = "*") (version 3.0;acl "Hosted Kolab Services";deny
&nbsp;&nbsp;(read,search)(userdn = "ldap:///uid=hosted-kolab-service,ou=Special
&nbsp;&nbsp;Users,<replaceable>$management_domain_root_dn</replaceable>");)

</screen>

            </para>

        </step>
        <step>
            <para>
                Using the Kolab Web Administration Panel, create a new domain.
            </para>

        </step>
        <step>
            <para>
                Create a new section for the hosted settings in <filename>/etc/kolab/kolab.conf</filename> as follows:
            </para>
            <para>

<screen language="INI Files">[kolab_hosting]
primary_domain = <replaceable>$hosted_domain</replaceable>
bind_dn = uid=hosted-kolab-service,ou=Special Users,<replaceable>$management_domain_root_dn</replaceable>
bind_pw = <replaceable>$hosted_service_account_password</replaceable></screen>

            </para>

        </step>
        <step>
            <para>
                Create a new section for the primary hosted domain in <filename>/etc/kolab/kolab.conf</filename>.
            </para>
            <para>
                A section for the management domain already exists, which you could copy/paste and rename to the new domain name space.
            </para>
            <para>
                Alternatively, all settings included in the <literal>[ldap]</literal> and <literal>[example.org]</literal> sections in the <ulink url="http://git.kolab.org/pykolab/tree/conf/kolab.conf">default configuration file</ulink> are available for the new domain name space.
            </para>

        </step>
        <step>
            <para>
                Create an Administrator user in the new domain, which you can use to create new users, and test the configuration / deployment.
            </para>
            <para>

<screen># <userinput>ldapmodify -x -h localhost -D "cn=Directory Manager" -w $password</userinput>
dn: uid=doe,ou=People,<replaceable>$hosted_domain_root_dn</replaceable>
objectclass: top
objectclass: inetorgperson
objectclass: person
uid: doe
cn: John Doe
sn: Doe
givenname: John
displayName: Doe, John
mail: doe@<replaceable>$hosted_domain</replaceable>
nsroledn: cn=kolab-admin,<replaceable>$hosted_domain_root_dn</replaceable>
userpassword: <replaceable>$password</replaceable>

</screen>

            </para>

        </step>
        <step>
            <para>
                Allow the hosted Kolab service account to create new entries in the hosted domain root dn:
            </para>
            <para>

<screen># <userinput>ldapmodify -x -h localhost -D "cn=Directory Manager" -w $password</userinput>
dn: ou=People,<replaceable>$hosted_domain_root_dn</replaceable>
changetype: modify
add: aci
aci: (targetattr = "*") (version 3.0;acl "Hosted Kolab Services";allow
&nbsp;&nbsp;(all)(userdn = "ldap:///uid=hosted-kolab-service,ou=Special Users,
&nbsp;&nbsp;<replaceable>$management_domain_root_dn</replaceable>");)

</screen>

            </para>

        </step>
        <step>
            <para>
                TODO: A list of illegitimate user ID that are not available for registration (i.e. root@, etc.).
            </para>

        </step>
        <step>
            <para>
                Add new user_types specifically designed for a hosted registration interface.
            </para>
            <para>

<screen># <userinput>mysql --user=kolab --password=<replaceable>$password</replaceable> \</userinput>
&gt; <userinput> kolab &lt; /usr/share/doc/kolab-webadmin-*/kolab_hosted-*.sql</userinput></screen>

            </para>

        </step>

    </procedure>

    <procedure id="proc-Administrator_Guide-Hosted_Kolab_Groupware_Setup-Removing_Canonification_from_Cyrus_IMAP">
        <title>Removing Canonification from Cyrus IMAP</title>
        <para>
            This procedure removes canonification from Cyrus IMAP
        </para>
        <step>
            <para>
                Edit <filename>/etc/imapd.conf</filename> removing auth_mech, pts_module and ldap_* settings.
            </para>

        </step>
        <step>
            <para>
                Restart Cyrus IMAP.
            </para>

        </step>
        <step>
            <para>
                Test with
            </para>

        </step>

    </procedure>

    <!--
    <procedure id="proc-Administrator_Guide-Hosted_Kolab_Groupware_Setup-Multiple_Domain_Canonification_through_Referrals">
        <title>Multiple Domain Canonification through Referrals</title>
        <para>
            This procedure sets up Cyrus IMAP to chase referrals from the management domain onto the hosted domains.
        </para>
        <step>
            <para>
                Edit <filename>/etc/imapd.conf</filename>
            </para>

        </step>
        <step>
            <para>
                Test with
            </para>

        </step>

    </procedure>

    <procedure id="proc-Administrator_Guide-Hosted_Kolab_Groupware_Setup-Setting_up_Multiple_Isolated_Cyrus_IMAP_Server_Instances">
        <title>Setting up Multiple Isolated Cyrus IMAP Server Instances</title>
        <para>
            This procedure sets up a separate group of Cyrus IMAP services for each hosted domain.
        </para>
        <step>
            <para>
                Test with
            </para>

        </step>

    </procedure>
//    --> <procedure id="proc-Administrator_Guide-Hosted_Kolab_Groupware_Setup-Update_Postfix_LDAP_Lookup_Tables">
        <title>Update Postfix LDAP Lookup Tables</title>
        <para>
            This procedure sets up Postfix to be able to lookup parent domain name spaces with one dot (.) character. It will work for <emphasis>example.org</emphasis>, but not for <emphasis>demo.example.org</emphasis> recipient email addresses.
        </para>
        <remark>Fact check needed for the aforementioned (relates to matching parent domains in Postfix)</remark>
        <step>
            <para>
                Edit the following files, replacing the <literal>base_dn</literal> setting with a value of <literal>dc=%2,dc=%1</literal>.
            </para>
            <para>
                <itemizedlist>
                    <listitem>
                        <para>
                            <filename>/etc/postfix/ldap/local_recipient_maps.cf</filename>
                        </para>

                    </listitem>
                    <listitem>
                        <para>
                            <filename>/etc/postfix/ldap/mailenabled_distgroups.cf</filename>
                        </para>

                    </listitem>
                    <listitem>
                        <para>
                            <filename>/etc/postfix/ldap/mailenabled_dynamic_distgroups.cf</filename>
                        </para>

                    </listitem>
                    <listitem>
                        <para>
                            <filename>/etc/postfix/ldap/transport_maps.cf</filename>
                        </para>

                    </listitem>
                    <listitem>
                        <para>
                            <filename>/etc/postfix/ldap/virtual_alias_maps.cf</filename>
                        </para>

                    </listitem>

                </itemizedlist>

            </para>
            <para>
                The short version of this is a single command:
            </para>
            <para>

<screen># <userinput>sed -r -i \</userinput>
&gt; <userinput>-e 's/^search_base = .*$/search_base = dc=%1,dc=%2/g' \</userinput>
&gt; <userinput>`find /etc/postfix/ldap/ -type f -name "*.cf" ! -name "mydestination.cf"`</userinput></screen>

            </para>

        </step>
        <step>
            <para>
                Restart the <literal>postfix</literal> service:
            </para>
            <para>

<screen># <userinput>service postfix restart</userinput></screen>

            </para>

        </step>
        <step>
            <para>
                Test looking up the primary domain name space:
            </para>
            <para>

<screen># <userinput>postmap -q <replaceable>$management_domain</replaceable> ldap:/etc/postfix/ldap/mydestination.cf</userinput></screen>

            </para>

        </step>
        <step>
            <para>
                Should any email recipient exist in the primary domain name space, test the primary recipient email address for this user:
            </para>
            <para>

<screen># <userinput>postmap -q <replaceable>$email_address</replaceable> ldap:/etc/postfix/ldap/local_recipient_maps.cf</userinput></screen>

            </para>

        </step>
        <step>
            <para>
                Test a secondary recipient email address for this user:
            </para>
            <para>

<screen># <userinput>postmap -q <replaceable>$email_address</replaceable> ldap:/etc/postfix/ldap/local_recipient_maps.cf</userinput></screen>

            </para>

        </step>
        <step>
            <para>
                Test the primary recipient email address for the administrator user created in the primary hosted domain:
            </para>
            <para>

<screen># <userinput>postmap -q <replaceable>$email_address</replaceable> ldap:/etc/postfix/ldap/local_recipient_maps.cf</userinput></screen>

            </para>

        </step>
        <step>
            <para>
                Test a secondary recipient email address for this user:
            </para>
            <para>

<screen># <userinput>postmap -q <replaceable>$email_address</replaceable> ldap:/etc/postfix/ldap/local_recipient_maps.cf</userinput></screen>

            </para>

        </step>

    </procedure>

    <procedure id="proc-Administrator_Guide-Hosted_Kolab_Groupware_Setup-Configuring_Roundcube">
        <title>Configuring Roundcube</title>
        <para>
            This procedure configures the Roundcube webmail client to use different settings for different webserver virtual hosts.
        </para>
        <step>
            <para>
                Create a directory specific to the vhost:
            </para>
            <para>

<screen># <userinput>mkdir /etc/roundcubemail/<replaceable>$http_host</replaceable>/</userinput></screen>

            </para>
            <para>
                where <literal>$http_host</literal> is the server address name your users will use to connect to the webmail interface. For example, if your users visit <ulink url="https://webmail.example.org/">http://webmail.example.org/</ulink> to get to the webmail interface, then the <literal>$http_host</literal> is <literal>webmail.example.org</literal> and the directory to create is <filename>/etc/roundcubemail/webmail.example.org/</filename>.
            </para>

        </step>
        <step>
            <para>
                Copy <filename>/etc/roundcubemail/main.inc.php</filename> and <filename>/etc/roundcubemail/kolab_auth.inc.php</filename> to the new <filename>/etc/roundcubemail/<replaceable>$http_host</replaceable>/</filename> directory.
            </para>

        </step>
        <step>
            <para>
                Edit <filename>/etc/roundcubemail/main.inc.php</filename> as follows:
            </para>
            <para>
                <itemizedlist>
                    <listitem>
                        <para>
                            Remove the <literal>$rcmail_config['ldap_public']</literal> configuration in its entirety.
                        </para>
                        <para>
                            The configuration for any sort of global address book is supposed to be a business hosted plan feature only.
                        </para>

                    </listitem>
                    <listitem>
                        <para>
                            Edit the <literal>$rcmail_config['plugins']</literal> setting to only list the plugins that are to be enabled for the personal hosted plan.
                        </para>
                        <para>
                            For example, this list of plugins could be as minimal as:
                        </para>
                        <para>

<screen>$rcmail_config['plugins'] = array(
        'calendar',
        'kolab_addressbook',
        'password'
    );</screen>

                        </para>

                    </listitem>

                </itemizedlist>

            </para>

        </step>
        <step>
            <para>
                Replace the contents of <filename>/etc/roundcubemail/kolab_auth.inc.php</filename> with the following:
            </para>
            <para>

<screen language="PHP/PHP">&lt;?php
if (file_exists(
        RCMAIL_CONFIG_DIR . '/' .
        $_SERVER["HTTP_HOST"] . '/' .
        basename(__FILE__))
    ) {

    include_once(
            RCMAIL_CONFIG_DIR . '/' .
            $_SERVER["HTTP_HOST"] . '/' .
            basename(__FILE__));
}
?&gt;</screen>

            </para>

        </step>
        <step>
            <para>
                Edit <filename>/etc/roundcubemail/<replaceable>$http_host</replaceable>/main.inc.php</filename> and change the settings related to the <literal>$rcmail_config['ldap_public']['kolab_addressbook']</literal> configuration.
            </para>
            <para>
                <itemizedlist>
                    <listitem>
                        <para>
                            Depending on the division of features in your hosted plans, you may want to remove the entire LDAP address book configuration. Hosted plans with an increased number of features (such as this LDAP address book) are configured later, elsewhere.
                        </para>

                    </listitem>
                    <listitem>
                        <para>
                            Make sure that the configuration file includes a statement similar to the following (lines terminated prematurely for legibility purposes):
                        </para>
                        <para>

<screen>if (file_exists(
                        RCMAIL_CONFIG_DIR . '/' .
                        $_SERVER["HTTP_HOST"] . '/' .
                        basename(__FILE__))
                    ) {

                include_once(
                        RCMAIL_CONFIG_DIR . '/' .
                        $_SERVER["HTTP_HOST"] . '/' .
                        basename(__FILE__));
            }</screen>

                        </para>

                    </listitem>

                </itemizedlist>

            </para>

        </step>
        <step>
            <para>
                Edit <filename>/etc/roundcubemail/<replaceable>$http_host</replaceable>/kolab_auth.inc.php</filename> and make sure the settings in the <literal>$rcmail_config['kolab_auth_addressbook']</literal> reflect the settings required for the corresponding hosted domain.
            </para>
            <para>
                <itemizedlist>
                    <listitem>
                        <para>
                            The <literal>$rcmail_config['kolab_auth_addressbook']['base_dn']</literal> and <literal>$rcmail_config['kolab_auth_addressbook']['groups']['base_dn']</literal> settings need to be updated to the hosted domain root dn.
                        </para>
                        <para>
                            The <literal>$rcmail_config['kolab_auth_addressbook']['bind_dn']</literal> setting does not need to be updated as the <literal>uid=kolab-service</literal> user in the management domain is supposed to be allowed to read all of the contents of all of the domain name spaces hosted, including other root dns.
                        </para>

                    </listitem>
                    <listitem>
                        <para>
                            Make sure that the configuration file includes a statement similar to the following (lines terminated prematurely for legibility purposes):
                        </para>
                        <para>

<screen>if (file_exists(
                        RCMAIL_CONFIG_DIR . '/' .
                        $_SERVER["HTTP_HOST"] . '/' .
                        basename(__FILE__))
                    ) {

                include_once(
                        RCMAIL_CONFIG_DIR . '/' .
                        $_SERVER["HTTP_HOST"] . '/' .
                        basename(__FILE__));
            }</screen>

                        </para>

                    </listitem>

                </itemizedlist>

            </para>

        </step>

    </procedure>

    <section id="sect-Administrator_Guide-Hosted_Kolab_Groupware_Setup-Role_based_Enabling_of_Plugins_and_Pinning_of_Settings_for_Roundcube">
        <title>Role-based Enabling of Plugins and Pinning of Settings for Roundcube</title>
        <para>
            This section outlines how to set up Roundcube to match the various specifications of the hosted plans outlined on <ulink url="http://wiki.kolab.org/Hosted_Kolab_for_Kolab_3.0">this wiki page</ulink>.
        </para>
        <para>
            The <literal>kolab_auth</literal> plugin allows two separate settings to be configured, that on a role-by-role basis enable certain plugins, or configure (the default for) certain settings (and optionally pin them down so that the user is not allowed to change them).
        </para>
        <para>
            Having removed the <literal>acl</literal> plugin from the list of plugins in the <literal>$rcmail_config['plugins']</literal> setting in <filename>/etc/roundcubemail/main.inc.php</filename> allows the plugin to be selectively re-enabled, for example only for users with the <literal>professional-user</literal> role:
        </para>
        <para>

<screen>$rcmail_config['kolab_auth_role_plugins'] = array(
        "cn=professional-user,dc=example,dc=org" =&gt; array(
                'acl',
            ),
    );</screen>

        </para>
        <para>
            Similarly, a personal hosted plan user may be restricted from using the HTML editor, while a professional hosted plan user may be allowed to choose:
        </para>
        <para>

<screen>$rcmail_config['kolab_auth_role_settings'] = array(
        "cn=professional-user,dc=example,dc=org" =&gt; array(
                'htmleditor' =&gt; array(
                        'mode' =&gt; 'override',
                        'value' =&gt; 1,
                        'allow_override' =&gt; true,
                    ),
            ),
        "cn=personal-user,dc=example,dc=org" =&gt; array(
                'htmleditor' =&gt; array(
                        'mode' =&gt; 'override',
                        'value' =&gt; 0,
                        'allow_override' =&gt; false,
                    ),

            ),
    );</screen>

        </para>
        <note>
            <para>
                Please note that setting a default for a particular role and setting is necessary only if the default needs to change from the default configured in <filename>/etc/roundcubemail/main.inc.php</filename> (global) and <filename>/etc/roundcubemail/<replaceable>$http_host</replaceable>/main.inc.php</filename> (domain specific).
            </para>

        </note>

    </section>


</chapter>