"Fossies" - the Fresh Open Source Software Archive 
Member "courier-1.2.2/libs/maildir/README.sharedfolders.txt" (22 Jan 2022, 38690 Bytes) of package /linux/misc/courier-1.2.2.tar.bz2:
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1 Shared folders
2
3 This document describes how shared folders are implemented by
4 Courier-IMAP, and SqWebMail.
5
6 Courier-IMAP and SqWebMail actually have two different shared folder
7 implementations, for two situations: A) Filesystem permissions-based
8 shared folders, for systems with traditional shell login accounts, and
9 mailboxes; and B) virtual shared folders, for closed systems that provide
10 mail access only, with all mailboxes using the same system userid/groupid,
11 and no end-user shell login access.
12
13 This documentation is also applicable to the Courier mail server, which
14 includes Courier-IMAP and SqWebMail as its components. There are some
15 minor implementation differences between the standalone Courier-IMAP and
16 SqWebMail packages, and Courier; namely the different locations of several
17 key configuration files. Aside from that, both implementation are
18 equivalent.
19
20 Table Of Contents
21 Virtual shared folders
22 Terminology
23 Technical Overview
24 Functional Overview
25 Combining Courier-IMAP's and SqWebMail index files
26 IMAP Access Control List and account groups
27
28 Filesystem permissions-based shared folders
29 Terminology
30 Technical Overview
31 Functional Overview
32 Accessing shared folders
33 Subscribing to a shared folder
34 Unsubscribing to a shared folder
35 Opening a shared folder
36
37 Virtual shared folders
38
39 Terminology
40
41 Virtual shared folders are implemented in a completely different manner.
42 In a virtual setup, all mailboxes use the same system userid and groupid;
43 there is no shell login access to the mail server, and all access is
44 managed by setting up access control lists. Each individual user may
45 voluntarily grant access to a folder to another user or group of user.
46 Access control lists permit fine-grained control. It is possible to
47 specify what different users are permitted to do to the folder or its
48 contents. Since there is no shell login access, all access to mail folders
49 occurs through an IMAP connection to the server, and the IMAP server
50 observes the defined access control lists on each folder.
51
52 NOTE:
53
54 The references to IMAP in this documentation equally apply to SqWebMail
55 as well. This documentation file is included in Courier-IMAP's and
56 SqWebMail's tarballs. When reading this documentation file in the
57 SqWebMail tarball, mentally replace all references to IMAP with webmail.
58 SqWebMail does not use IMAP, the server reads the maildirs directory;
59 but it uses the same shared library as Courier-IMAP, which explains the
60 similar implementation.
61
62 For more information on how to set up access control lists, see the
63 maildiracl(1) manual page.
64
65 Technical Overview
66
67 After logging in, the server process runs in the logged in account's
68 maildir. As the INSTALL file describes in great detail, virtual mail
69 accounts may be maintained via a wide variety of back-end databases,
70 including MySQL, PostgresSQL, or an LDAP directory. If now the server
71 needs to check the access controls on another account's mail folder, to
72 determine if the user has access to it, the server needs to now locate
73 where the other account is located.
74
75 However, there are several reasons why the server cannot directly go back
76 to the authentication database. The first reason is that after logging in
77 the server process no longer has root privileges; and database
78 configuration files normally require root privileges (since they may
79 contain administrative passwords). Although there might be ways to hack
80 around that, the second reason is the show-stopper: IMAP's design permits
81 clients to enumerate all available shared mail accounts, or arbitrary
82 subsets of them. And, in fact, many of them do just that; mainly because
83 IMAP's design leaves no other alternative, in some situations.
84
85 Clearly, it is not feasible to have hundreds of clients hammering at the
86 database server, repeatedly downloading huge lists of available shared
87 folders (which may number in tens of thousands, on a busy server).
88 Therefore, the following approach is used.
89
90 One or more flat text files are set up, which contain an index of all
91 virtual mail folders. The list is, essentially, downloaded from the
92 authentication database. The text file contain a subset of the data in the
93 authentication database; only the minimum amount of fields necessary to
94 specify the account's name, and where the account lives. The server
95 process quickly reads the text file(s) in order to locate another
96 account's folder, and to check its access control list.
97
98 The system administrator will need to set up a regularly-scheduled process
99 that rebuilds the shared folder index. Yes, that means that a new
100 account's shared folders will not be accessible, by other accounts, until
101 the shared folder index gets rebuilt (but the account still has immediate
102 access to its own folders, after creation). The shared folder index will
103 be updated in a manner that allows the update to occur live, without
104 requiring any system downtime.
105
106 On moderately-sized systems it might be feasible to invoke the shared
107 index update script as part of the process that adds or removes an
108 account; thereby the shared folder index files will always be kept up to
109 date.
110
111 In its most simple form, the shared index is a single file, called
112 SYSCONFDIR/shared/index, where "SYSCONFDIR" is the server's configuration
113 directory. The following table provides the default locations of the
114 configuration file:
115
116 Courier-IMAP: /usr/lib/courier-imap/etc/shared/index
117 Courier: /usr/lib/courier/etc/shared/index
118 Courier (Red Hat/Fedora build): /etc/courier/shared/index
119 SqWebMail (standalone build): /usr/local/share/sqwebmail/shared/index
120
121 NOTE:
122
123 If the "shared" directory doesn't exist, just create it.
124
125 Blank lines in this file are ignored, as well as lines that begin with a
126 single "#" character, which are arbitrary comments. Each remaining line
127 specifies the location of an account's maildir. The line contains the
128 following fields, separated by a single tab character:
129
130 1. name
131 2. system userid
132 3. system groupid
133 4. virtual home directory
134 5. maildir path, relative to the virtual home directory
135
136 "name" SHOULD be the account's login name (which in some rare
137 configurations may not actually match the IMAP login used by the client;
138 this is the name that's logged to syslog when the account successfully
139 logs in, which is usually the same as the IMAP login id). In most
140 situations all accounts will have the same system userid and groupid. The
141 server doesn't actually do anything with these fields at this time, but
142 may do so in the future.
143
144 The virtual account's home directory is taken verbatim from the
145 authentication database. The maildir path field is optional. If missing,
146 it defaults to "./Maildir". Combining the home directory, and the maildir
147 path, results in the location where the specified account's maildir
148 folders may be found.
149
150 Inaccessible accounts are silently ignored. This allows the shared folder
151 index to be itself shared between multiple servers even though that
152 accounts themselves are not shared. Each server will only see the accounts
153 it can access.
154
155 As mentioned previously, IMAP clients will often want to obtain a complete
156 list of shared folders. If the mail server has more than a a couple of
157 hundred accounts, a single index file may be inefficient, and the mail
158 accounts should be segregated into different groups. An account group
159 entry in the index file looks like this:
160
161 1. group name
162 2. *
163 3. filename
164
165 When the second tab-delimited field is a single asterisk, the first field
166 is taken to be a name of an account group; and "filename" is the name of
167 another, separate, index file that lists all accounts that belong in this
168 group. The second file should also be installed in SYSCONFDIR/shared.
169
170 When it's time to use account groups, SYSCONFDIR/shared/index will usually
171 contain only group entries, with the accounts themselves dispersed in
172 other files in the same directory.
173
174 Account names and group names use the UTF-8 character set. This is not
175 usually an issue for account names, which are almost always limited to the
176 Latin character set. Group names may be arbitrary, though, and include
177 non-Latin characters, using UTF-8.
178
179 Courier does not allow IMAP folder names to contain the "." or the "/"
180 characters. The shared index file may include those characters in account
181 or group names, and they will be automatically replaced by spaces (which
182 are allowed).
183
184 This is not normally an issue, unless there exists two separate accounts
185 or groups whose names are the same, except that one name contains spaces,
186 and the other name contains the forbidden characters. This is obviously
187 not something that is likely to occur, but if it did the end result would
188 be that one of the names will have its punctuation characters replaced by
189 spaces, and now two virtual folders will exist with the same name.
190
191 If this rather unlikely scenario somehow materializes the solution is to
192 enable the IMAP_SHAREDMUNGENAMES setting in Courier-IMAP's configuration
193 file. When enabled, this setting replaces the "." and "/" with a two
194 character sequence: "\:" and "\;". Any the existing backslashes are
195 doubled, thus preserving folder name uniqueness. This is not something
196 you'd want to do unless you have no other choice.
197
198 The equivalent setting for SqWebMail (or Courier's webmail server) is the
199 SQWEBMAIL_SHAREDMUNGENAMES. When using SqWebMail at the same time as
200 Courier-IMAP, and if IMAP_SHAREDMUNGENAMES is set, the
201 SQWEBMAIL_SHAREDMUNGENAMES variable must also be set in order for everyone
202 to be in sync. This can be done in one of two different ways:
203
204 1. Set this variable before running the sqwebmaild start command:
205
206 SQWEBMAIL_SHAREDMUNGENAMES=1
207 export SQWEBMAIL_SHAREDMUNGENAMES
208 sqwebmaild start
209
210 2. Set this environment variable in the web server's configuration
211 files. With Apache, for example:
212
213 SetEnv SQWEGBMAIL_SHAREDMUNGENAMES 1
214
215 Many Shared Accounts
216
217 When the number of mail accounts begins to exceed a couple of thousand (or
218 even less, depending on the mail server), even account groups will not be
219 enough. If a single mail server has tens of thousands of accounts, an
220 individual IMAP client may potentially access hundreds of thousands of
221 folders.
222
223 It is a sad fact of life that there are poorly-designed IMAP clients that
224 insist on searching for every accessible folder, every time. They will
225 stubornly scan the entire IMAP folder namespace, recursively reading each
226 folder hierarchy, to compile a list of available folders. Even though
227 there may only be a few folders shared by their owners, the server still
228 has to check whether the IMAP client has access to each folder, in order
229 to compile the list of accessible folders. No mail server will like an
230 IMAP client that insists on reading the access control lists of hundreds
231 of thousand of folders.
232
233 This problem is solved by setting the "sharedgroup" option for each
234 account. The INSTALL file contains a more specific description of how to
235 initialize account options. Normally, the shared folder index file is
236 "SYSCONFDIR/shared/index"; however, if the "sharedgroup" option is set,
237 the value of "sharedgroup" is appended to the shared folder index
238 filename. So, if user1's account has the "sharedgroup=12" option, as far
239 as this account is concerned the shared folder index file is
240 "SYSCONFDIR/shared/index12". Note that SYSCONFDIR/shared/index12 may still
241 contain account group entries that point to other shared index files.
242
243 This enables the ability to partition all accounts into smaller
244 "universes". The list of accounts is broken up into individual universe.
245 Accounts within a universe can only see other accounts in the same
246 universe. Even if a given folder's access control lists permit global
247 access, only accounts in the same universe will be able to access it.
248
249 Also note that trans-universal wormholes are possible. Two, or more,
250 top-level index files may list the same set of account groups, and those
251 accounts will be visible from both (or more) universes.
252
253 IMPORTANT: Under no circumstances should you install circular wormholes
254 (index file A lists index file B as a group, and index file B lists index
255 file A as a group). The consequences would be disastrous for both
256 universes.
257
258 Functional Overview
259
260 As mentioned in the previous section, it is necessary to set up a
261 regularly-scheduled system process that updates the shared folder index
262 files. The procedure for doing so is site-specific. Individual sites will
263 need to put together a set of custom scripts that create the shared folder
264 index files in SYSCONFDIR/shared. This is likely to be a highly
265 site-specific code; however Courier installs several generic shell scripts
266 that can be used as a working starting point.
267
268 The most important step in the process is actually the final step of
269 installing new shared folder index files in SYSCONFDIR/shared. They must
270 be installed in a way that can be done live, without shutting down the
271 system, and without affecting any existing processes. This can be done
272 using the “sharedindexinstall” script, which may be found in the sbin
273 directory. To use sharedindexinstall, first create the shared index files
274 in a temporary directory called SYSCONFDIR/shared.tmp, then run the script
275 to move all the files in this directory to SYSCONFDIR/shared.
276
277 So a typical script that updates shared index files will generally look
278 like this (this example uses Courier-IMAP, for SqWebMail the directory
279 locations will be different):
280
281 --------------------------------------------------------------------------
282
283 #!/bin/sh
284 sysconfdir="/usr/lib/courier-imap/etc" # Or /etc/courier, or whatever...
285 sbindir="/usr/lib/courier-imap/sbin" # Or, wherever it actually is...
286
287 rm -rf $sysconfdir/shared.tmp
288 mkdir $sysconfdir/shared.tmp || exit 1
289
290 #
291 # A magical process creates updated shared index files right about now...
292 #
293
294 $sbindir/sharedindexinstall
295
296 --------------------------------------------------------------------------
297
298 NOTE
299
300 Existing IMAP server processes may continue to use cached shared folder
301 index data for some time, after sharedindexinstall. This will not cause
302 any problems.
303
304 Using authenumerate
305
306 In most cases, systems that use a single shared index file are likely to
307 need to only run the “authenumerate” program in order to build the shared
308 folder index. As long as Courier's authentication modules are properly
309 configured (and authdaemond is running) authenumerate will download the
310 list of accounts from the configured authentication module, and generate a
311 suitably-formatted list on standard output. So the complete shared folder
312 index update script will look like this:
313
314 --------------------------------------------------------------------------
315
316 #!/bin/sh
317 sysconfdir="/usr/lib/courier-imap/etc"
318 sbindir="/usr/lib/courier-imap/sbin"
319
320 rm -rf $sysconfdir/shared.tmp
321 mkdir $sysconfdir/shared.tmp || exit 1
322
323 $sbindir/authenumerate -s >$sysconfdir/shared.tmp/index || exit 1
324
325 $sbindir/sharedindexinstall
326
327 --------------------------------------------------------------------------
328
329 The functionality to enumerate accounts is new to Courier-IMAP 3.0. When
330 upgrading from an earlier versions, systems that are configured to use a
331 custom MySQL, PostgreSQL, or LDAP queries will need to enter a new
332 configuration setting in the appropriate configuration file. The update
333 process will add a new variable to the configuration file, which must be
334 initialized to contain the custom query that reads the account list
335 accordingly. In most cases the query only needs to be a slight variation
336 on the existing query that checks the password of a specific account
337 that's requesting authentication.
338
339 Systems that do not use the custom query option should not need to make
340 any additional setting, as the standard query authentication variables
341 contain all the information that's needed to obtain a complete list of
342 accounts.
343
344 If only a small proportion of your users are entitled to use shared
345 mailboxes, then it helps scalability enormously if you restrict the shared
346 index file to contain just those accounts. The -s flag to authenumerate
347 implements this, by discarding all accounts which have the option
348 disableshared set to a non-zero value. Further efficiency can be gained by
349 customising your database query so that the database itself returns only
350 the relevant accounts. Use option MYSQL_ENUMERATE_CLAUSE,
351 PGSQL_ENUMERATE_CLAUSE or LDAP_ENUMERATE_FILTER as appropriate.
352
353 Note also that you can set DEFAULTOPTIONS="disableshared=1" in
354 authdaemonrc to make sharing disabled for everyone, and then set option
355 disableshared=0 only on permitted accounts.
356
357 NOTE
358
359 authenumerate tries not to download the complete results of each query
360 into a memory buffer, but it may be that this still happens due to
361 circumstances out of its control (e.g. older versions of MySQL or
362 PostgreSQL client libraries may force this to happen). If so, it's
363 possible that authenumerate's memory requirements may be large enough to
364 affect the running system. In this case you will need to come up with an
365 alternative mechanism to obtain the list of accounts, in some other way.
366
367 NOTE
368
369 The PAM library does not have a function that obtains a list of
370 available accounts. Therefore, on all systems that use the authpwd,
371 authshadow, or authpam modules, authenumerate works in exactly the same
372 way: by using the getpwent() function. Systems that use certain PAM
373 modules, such as ones that authenticate against a MySQL, a PostgreSQL,
374 or an LDAP database, will not be able to use authenumerate, and must
375 come up with a suitable replacement.
376
377 Using sharedindexsplit
378
379 As mentioned in the technical overview, a single index file may not be
380 feasible if the number of accounts is more than a thousand, or so. At that
381 point it becomes necessary to split the shared folder index into multiple
382 files.
383
384 The sharedindexsplit script reads a list of all accounts, formatted as a
385 single shared folder index (which, incidentally, matches authenumerate's
386 output format as well) and splits it into multiple files. The first
387 argument to sharedindexsplit is the name of the directory where the output
388 files are going to be created. The directory must be empty.
389
390 sharedindexsplit splits the index into multiple files, based on either the
391 'sharedgroup' account option, or the first character or characters of the
392 account's name. Use the optional second argument to sharedindexsplit to
393 specify a number, if splitting the account list based on initial
394 characters is desired. If splitting based on the 'sharedgroup' account
395 option then use the -o flag to authenumerate to get it to include the
396 account options in its output.
397
398 Perl 5.8.0, or greater, must be installed if account names include
399 non-Latin characters. For best results, the shared folder index input to
400 sharedindexsplit should already be sorted, but it doesn't have to be.
401
402 Therefore, the following scripts should produce good results on a system
403 with a large, but a moderate number of accounts. Split on 'sharedgroup' if
404 you have a number of separate 'universes' where sharing is only permitted
405 within each universe; otherwise split on the account name if all users can
406 potentially access all shared mailboxes.
407
408 --------------------------------------------------------------------------
409
410 #!/bin/sh
411 sysconfdir="/usr/lib/courier-imap/etc"
412 sbindir="/usr/lib/courier-imap/sbin"
413
414 rm -rf $sysconfdir/shared.tmp
415 mkdir $sysconfdir/shared.tmp || exit 1
416
417 # split on the 'sharedgroup' option
418 $sbindir/authenumerate -s -o >$sysconfdir/shared.tmp/.tmplist || exit 1
419 $sbindir/sharedindexsplit $sysconfdir/shared.tmp <$sysconfdir/shared.tmp/.tmplist || exit 1
420 rm -f $sysconfdir/shared.tmp/.tmplist
421 $sbindir/sharedindexinstall
422
423 --------------------------------------------------------------------------
424
425 #!/bin/sh
426 sysconfdir="/usr/lib/courier-imap/etc"
427 sbindir="/usr/lib/courier-imap/sbin"
428
429 rm -rf $sysconfdir/shared.tmp
430 mkdir $sysconfdir/shared.tmp || exit 1
431
432 # split on the first 1 character of the username
433 $sbindir/authenumerate -s >$sysconfdir/shared.tmp/.tmplist || exit 1
434 $sbindir/sharedindexsplit $sysconfdir/shared.tmp 1 <$sysconfdir/shared.tmp/.tmplist || exit 1
435 rm -f $sysconfdir/shared.tmp/.tmplist
436 $sbindir/sharedindexinstall
437
438 --------------------------------------------------------------------------
439
440 authenumerate is saved to a temporary file, instead of being piped
441 directly, is so that its exit code can be checked. We want to abort the
442 entire process if authenumerate terminates with a non-zero exit code. If
443 authenumerate pipes its output directly to sharedindexsplit, and aborts
444 with an error, then sharedindexsplit will read an empty shared folder
445 index, consequently the output directory will be empty, and then
446 sharedindexinstall will obligingly install an empty list of shared
447 folders.
448
449 As mentioned previously, at some point authenumerate's memory requirements
450 may become too much to handle, and an alternative mechanism will need to
451 be improvised. sharedindexsplit's memory requirements are not dependent on
452 the number of accounts, so this script can still be used even with very
453 many accounts.
454
455 When it's time to use account groups, SYSCONFDIR/shared/index will usually
456 contain only group entries, with the accounts themselves dispersed in
457 other files in the same directory.
458
459 Combining Courier-IMAP's and SqWebMail index files
460
461 The information in this section is applicable only when running both
462 Courier-IMAP and SqWebMail packages. This is not applicable when running
463 Courier, which includes both the IMAP server and the webmail server. In
464 the Courier build, both servers are set up to use the same shared index
465 file.
466
467 But, if both standalone builds are installed, Courier-IMAP will want to
468 use /usr/lib/courier-imap/etc/shared/index as its shared index file, while
469 SqWebMail will read /usr/local/share/sqwebmail/shared/index.
470
471 To make both servers use the same shared folder index, create a soft link:
472
473 ln -s /usr/lib/courier-imap/etc/shared /usr/local/share/sqwebmail/shared
474
475 It's important to create a soft link to the entire "shared" directory,
476 otherwise index group files will not work.
477
478 IMAP Access Control List and account groups
479
480 Even after setting up shared folders indexes correctly, the mail client
481 will show an empty list of shared folders. This is because even though
482 each account's folders may be shared, they will not be visible to other
483 accounts until the mail account's owner explicitly grants public access to
484 a folder. This can be done using an IMAP mail client that understands
485 access control lists, using Courier's SqWebMail, or the maildiracl
486 command. The maildiracl manual page includes an overview of access control
487 lists and how to control who gets what kind of rights on a folder. See the
488 maildiracl manual page for more information.
489
490 Filesystem permissions-based shared folders
491
492 Terminology
493
494 * Sharable Maildir - a maildir that contains folders that can be shared.
495 * Sharable folder - one or more folders in a sharable Maildir that can
496 be shared.
497
498 Technical Overview
499
500 * They are a somewhat logical extension of the base Maildir format.
501 * Older versions of Courier-IMAP and SqWebMail will completely ignore
502 shared folders.
503 * Messages in shared folders do not count towards any individual maildir
504 quotas (see README.maildirquota.html).
505 * Shared folders are implemented as additional, Maildir-based folders.
506 The messages will be soft links to the messages in the sharable
507 folder. Soft links will be used instead of hard links in order to be
508 able to have a folder containing large messages, and then be able to
509 reclaim space immediately when the messages are purged, instead of
510 waiting for everyone to sync up and delete their hard link. The flip
511 side is that you can expect the usual sorts of errors and increased
512 confusion if someone attempts to read a message that has just been
513 removed, but their client (Courier-IMAP or SqWebMail) doesn't know
514 that yet. That's unavoidable. You'll probably have to set some kind of
515 a policy in order to keep the expected insanity to a minimum.
516 * Sharable folders are subscribed to by creating a separate maildir-type
517 directory within the main Maildir. It's created in a separate
518 subdirectory that is ignored by other Maildir clients.
519 * The new directory will contains soft links to the messages in the
520 sharable folder. "Synchronization" code will be used to synchronize
521 the contents of the sharable folder, and the copy of it in the regular
522 Maildir. Once links to the messages are created, they can be
523 manipulated like regular messages in a Maildir. This procedure will be
524 transparently performed by Courier-IMAP or SqWebMail behind the
525 scenes.
526 * Access to shared folders is controlled by a combination of an explicit
527 configuration, plus regular filesystem permissions. If account owners
528 have shell access to the server, they can create shared folders, and
529 link their mailbox to other accounts' shared folders. Then, the actual
530 access is controlled by regular filesystem permissions. The owner of
531 the shared folder will use the regular filesystem permission to give
532 read and/or write access to either everyone else, or everyone else who
533 uses the same system group ID. Read access allows people to read
534 messages from a shared folder. Write access allows people to add and
535 delete messages in the shared. The owner of the shared folder can
536 remove any message, everyone else will be able to remove only their
537 own messages.
538
539 Functional Overview
540
541 Generally speaking, shared folders are configured using a feature-enhanced
542 maildirmake command as follows:
543
544 * make install will install a maildirmake command that has a bunch of
545 funny options. The modified maildirmake command is installed into
546 Courier-IMAP's or SqWebMail's installation directory.
547 * Somebody, maybe you, will use some of these options to create a
548 maildir with modified permissions. The same somebody will run
549 maildirmake again, with a few other options, to create folders in that
550 maildir, also with modified permissions. Those permissions allows
551 global read (and optionally write) access to those folders.
552 * Do NOT use this maildir as the primary mailbox, INBOX, for an account.
553 Instead, you must create this maildir separately, perhaps as
554 $HOME/Maildir-shared, then set it up as one of your sharable maildirs
555 (see below), and access it in shared mode. Because you own it, you
556 have unlimited read/write access to it. The previously mentioned
557 options will select whether or not access permissions are given to
558 everyone else, and they do not apply to you.
559 * Everyone else will run maildirmake with even more funny options. Those
560 options install a link from their own maildir to a maildir that
561 contains sharable folders. A given maildir may contain links to more
562 than one sharable maildir. As long as their system user/group
563 permissions allow them to access messages, they can SUBSCRIBE via
564 their IMAP client to the folder, or use the SUBSCRIBE function in
565 SqWebmail.
566 * If people do not have shell access, the system administrator will have
567 to run maildirmake on their behalf, in order to create the links to
568 the sharable maildirs.
569 * People with write access can add messages to a sharable folder.
570 Messages from a sharable folder can be removed only by the owner of
571 the shared folder, or by the owner of each message.
572 * This sharable maildir implementation cannot use maildir soft-quotas.
573 There cannot be a soft-quota installed in a sharable maildir. If you
574 need quota support, you will have to use filesystem-based quotas.
575 There are some sticky issues with updating quotas on a sharable
576 maildir.
577
578 Also, note that anyone, not just the superuser, can create a sharable
579 maildir in their account, and invite anyone else to access it, as long as
580 their system user/group permissions allow them access.
581
582 To summarize:
583
584 * Use the -S option to maildirmake to create a maildir that can contain
585 sharable folders.
586 * Use the -s and -f options to maildirmake to create sharable folders.
587 The same sharable maildir may contain multiple sharable folders with
588 different access permissions, as selected by the -s option.
589 * Use the --add option to install a link from a regular maildir to a
590 sharable maildir. Afterwards, IMAP clients will be able to subscribe
591 to folders in the sharable maildir.
592 * Use the --del option to remove a link.
593
594 For more information on these options, see the maildirmake manual page
595 that will be installed.
596
597 More on additional options for the maildirmake command
598
599 The '-S' option to maildirmake to create a maildir that will contain
600 shared folders. The -S option gives group and world read permissions on
601 the maildir itself (where group/world permissions are normally not set for
602 a regular maildir). This allows access to any folders in the shared
603 maildir, and that's why you should not use this Maildir directly as your
604 primary mailbox.
605
606 The "new" and "cur" subdirectories will not be used or shared, although
607 they will still be created. Both SqWebMail and Courier-IMAP create their
608 auxiliary files in the main Maildir with the group and world permissions
609 turned off, so this maildir can, theoretically, still be used as the
610 primary INBOX, but I don't recommend that.
611
612 The -S option is not limited to the system administrator. In fact, anyone
613 can use the -S option, to create shared maildirs that they maintain.
614
615 Shared folders are created like any other folder, using the -f option to
616 maildirmake. However, that normally creates a folder that is not sharable,
617 because it will not have any group or world permissions. Therefore,
618 maildirmake will take the following options to create a sharable folder:
619
620 * -s read will create a "moderated" folder. The folder will have group
621 and world read permissions, letting anyone read messages, but only the
622 owner of the sharable Maildir can add messages to the sharable folder.
623 * -s write will create an "unmoderated" folder. The folder will have
624 group and world read/write permissions, letting anyone read and add
625 messages to the folder. The folder will be created with the sticky bit
626 set, like the /tmp directory, preventing people from removing someone
627 else's messages.
628 * -s read,group/-s write,group append a comma and the word "group" to
629 modify the semantics of moderated and unmoderated folders only on the
630 group level, not the group and world level, as far as permissions go.
631 This restricts sharing the folder only to members of the same system
632 group as the owner of the sharable maildir.
633
634 It's worth noting that it is perfectly permissible for folders in the same
635 sharable maildir to have different access levels.
636
637 Also, this is driven entirely by filesystem permissions, so theoretically
638 it's possible to create a folder that has write permissions for the group,
639 and read permissions for everyone else. However, I'm too lazy to actually
640 do it. Feel free to patch maildirmake to add this functionality, then send
641 me the patch.
642
643 Accessing shared folders
644
645 The rest of the document consists of technical implementation notes.
646
647 Accessing a collection of shared folders is implemented by a new file that
648 is installed in the primary maildir (usually $HOME/Maildir), and a new
649 subdirectory hierarchy underneath the primary maildir, which are hereby
650 declared.
651
652 shared-maildirs
653
654 This file must be created by the administrator or by the maildir owner,
655 manually. This file lists all available sharable maildirs that this
656 maildir can access in shared mode (confused yet?). This file contains one
657 or more lines of the following format:
658
659 name /path/to/shared/maildir
660
661 "name" is an arbitrary name that's given to this collection of shared
662 folders. The name may not contain slashes, periods, or spaces. This is
663 followed by a pathname to the maildir containing shared folders. Note that
664 this is NOT the sharable folder itself, but the maildir that contains one
665 or more sharable folders. The maildir client will be able to selectively
666 subscribe to any sharable folder in that maildir.
667
668 shared-folders
669
670 This subdirectory forms the root of all the shared folders that are
671 subscribed to. Let's say that shared-maildirs has the following contents:
672
673 firmwide /home/bigcheese/Maildir-shared tech /home/gearhead/Maildir-shared
674
675 Subscribing to folders 'golf' and 'boat' in bigcheese's shared Maildir,
676 and to the folder 'maintenance' in gearhead's shared Maildir involves
677 creating the following subdirectories: shared-folders/firmwide/.golf,
678 shared-folders/firmwide/.boat, and shared-folders/tech/.maintenance.
679
680 shared
681
682 This is a soft link that's automatically created in shared-folders/name.
683 It is a soft link that points to the sharable maildir, which contains the
684 sharable folders.
685
686 Subscribing to a shared folder
687
688 * Read shared-maildirs.
689 * Read the shared-folders hierarchy to determine which folders are
690 already subscribed to.
691 * Read the folders in each maildir listed in shared-folders, and ignore
692 the ones that are already subscribed to. Make sure to stat() each
693 folder to make sure that you can read it.
694 * If necessary, create shared-folders/name, and create the
695 shared-folders/name/shared soft link.
696 * Create shared-folders/name/.foldername, then create the standard tmp,
697 new, and cur subdirectories. All the directories are created without
698 any group or world permissions.
699
700 Unsubscribing
701
702 * Delete everything in shared-folders/name/foldername.
703 * If this is there are no more subscribed folders in this sharable
704 maildir, delete shared-folders/name for good measure as well.
705
706 Opening a shared folder
707
708 The process of "opening" a shared folder involves basically "syncing" the
709 contents of shared-folders/name/.foldername with the contents of the
710 sharable folder in the original sharable maildir.
711
712 * Do the usual processing on the tmp subdirectory.
713 * Read the contents of shared-folders/name/foldername/shared/new. If you
714 find anything in there, rename it to ../cur, ignoring any errors from
715 the rename. The sharable maildir owner can arrange for mail to be
716 delivered directly to this folder, and the first one to open it will
717 put the message into cur.
718 * Read the contents of shared-folder/name/foldername/shared/cur. Call
719 this directory "A", for short.
720 * Read the contents of shared-folder/name/foldername/cur. Call this
721 directory "B", for short.
722 * stat() A and B to see if they live on different devices.
723 * Remove all messages in B that do not exist in A. You want to compare
724 the filenames up to the : character.
725 * Create soft links from messages that exist in A and do not exist in B.
726 The name in B should not have any flags after the :, so it shows up as
727 a new message.
728 * You can now do whatever you normally do with a maildir. Note that new
729 is completely ignored, though. Moving messages IN and OUT of the
730 shared folder involves copying the message as if it were a new
731 message. Copying the message INTO the shared folder means copying the
732 message into the underlying sharable folder's tmp/cur directory, and
733 it will show up after the next sync.
734
735 References
736
737 Visible links
738 . file:///home/mrsam/src/courier.git/courier/libs/maildir/README.sharedfolders.html#newshared
739 . file:///home/mrsam/src/courier.git/courier/libs/maildir/README.sharedfolders.html#newsharedterm
740 . file:///home/mrsam/src/courier.git/courier/libs/maildir/README.sharedfolders.html#newsharedtech
741 . file:///home/mrsam/src/courier.git/courier/libs/maildir/README.sharedfolders.html#newsharedfunc
742 . file:///home/mrsam/src/courier.git/courier/libs/maildir/README.sharedfolders.html#combo
743 . file:///home/mrsam/src/courier.git/courier/libs/maildir/README.sharedfolders.html#imapacl
744 . file:///home/mrsam/src/courier.git/courier/libs/maildir/README.sharedfolders.html#oldshared
745 . file:///home/mrsam/src/courier.git/courier/libs/maildir/README.sharedfolders.html#oldsharedterm
746 . file:///home/mrsam/src/courier.git/courier/libs/maildir/README.sharedfolders.html#oldsharedtech
747 . file:///home/mrsam/src/courier.git/courier/libs/maildir/README.sharedfolders.html#oldsharedfunc
748 . file:///home/mrsam/src/courier.git/courier/libs/maildir/README.sharedfolders.html#oldsharedaccess
749 . file:///home/mrsam/src/courier.git/courier/libs/maildir/README.sharedfolders.html#oldsharedsub
750 . file:///home/mrsam/src/courier.git/courier/libs/maildir/README.sharedfolders.html#oldsharedunsub
751 . file:///home/mrsam/src/courier.git/courier/libs/maildir/README.sharedfolders.html#oldsharedopen
752 . file:///home/mrsam/src/courier.git/courier/libs/maildir/maildiracl
753 . file:///home/mrsam/src/courier.git/courier/libs/maildir/README.sharedfolders.html#newsharedtech
754 . file:///home/mrsam/src/courier.git/courier/libs/maildir/README.maildirquota.html