"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
    3    This document describes how shared folders are implemented by
    4    Courier-IMAP, and SqWebMail.
    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.
   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.
   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
   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
   37                              Virtual shared folders
   39 Terminology
   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.
   52      NOTE:
   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.
   62    For more information on how to set up access control lists, see the
   63    maildiracl(1) manual page.
   65 Technical Overview
   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.
   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.
   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.
   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.
   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.
  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.
  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:
  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
  121      NOTE:
  123      If the "shared" directory doesn't exist, just create it.
  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:
  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
  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.
  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.
  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.
  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:
  161     1. group name
  162     2. *
  163     3. filename
  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.
  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.
  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.
  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).
  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.
  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.
  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:
  204       1. Set this variable before running the sqwebmaild start command:
  208  sqwebmaild start
  210       2. Set this environment variable in the web server's configuration
  211          files. With Apache, for example:
  215   Many Shared Accounts
  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.
  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.
  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.
  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.
  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.
  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.
  258 Functional Overview
  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.
  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.
  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):
  281    --------------------------------------------------------------------------
  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...
  287  rm -rf $sysconfdir/shared.tmp
  288  mkdir $sysconfdir/shared.tmp || exit 1
  290  #
  291  # A magical process creates updated shared index files right about now...
  292  #
  294  $sbindir/sharedindexinstall
  296    --------------------------------------------------------------------------
  298     NOTE
  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.
  304   Using authenumerate
  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:
  314    --------------------------------------------------------------------------
  316  #!/bin/sh
  317  sysconfdir="/usr/lib/courier-imap/etc"
  318  sbindir="/usr/lib/courier-imap/sbin"
  320  rm -rf $sysconfdir/shared.tmp
  321  mkdir $sysconfdir/shared.tmp || exit 1
  323  $sbindir/authenumerate -s >$sysconfdir/shared.tmp/index || exit 1
  325  $sbindir/sharedindexinstall
  327    --------------------------------------------------------------------------
  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.
  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.
  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,
  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.
  357     NOTE
  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.
  367     NOTE
  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.
  377   Using sharedindexsplit
  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.
  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.
  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.
  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.
  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.
  408    --------------------------------------------------------------------------
  410  #!/bin/sh
  411  sysconfdir="/usr/lib/courier-imap/etc"
  412  sbindir="/usr/lib/courier-imap/sbin"
  414  rm -rf $sysconfdir/shared.tmp
  415  mkdir $sysconfdir/shared.tmp || exit 1
  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
  423    --------------------------------------------------------------------------
  425  #!/bin/sh
  426  sysconfdir="/usr/lib/courier-imap/etc"
  427  sbindir="/usr/lib/courier-imap/sbin"
  429  rm -rf $sysconfdir/shared.tmp
  430  mkdir $sysconfdir/shared.tmp || exit 1
  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
  438    --------------------------------------------------------------------------
  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.
  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.
  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.
  459 Combining Courier-IMAP's and SqWebMail index files
  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.
  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.
  471    To make both servers use the same shared folder index, create a soft link:
  473  ln -s /usr/lib/courier-imap/etc/shared /usr/local/share/sqwebmail/shared
  475    It's important to create a soft link to the entire "shared" directory,
  476    otherwise index group files will not work.
  478 IMAP Access Control List and account groups
  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.
  490                   Filesystem permissions-based shared folders
  492 Terminology
  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.
  498 Technical Overview
  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.
  539 Functional Overview
  541    Generally speaking, shared folders are configured using a feature-enhanced
  542    maildirmake command as follows:
  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.
  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.
  582    To summarize:
  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.
  594    For more information on these options, see the maildirmake manual page
  595    that will be installed.
  597   More on additional options for the maildirmake command
  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.
  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.
  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.
  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:
  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.
  634    It's worth noting that it is perfectly permissible for folders in the same
  635    sharable maildir to have different access levels.
  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.
  643 Accessing shared folders
  645    The rest of the document consists of technical implementation notes.
  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.
  652   shared-maildirs
  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:
  659    name /path/to/shared/maildir
  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.
  668   shared-folders
  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:
  673    firmwide /home/bigcheese/Maildir-shared tech /home/gearhead/Maildir-shared
  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.
  680   shared
  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.
  686 Subscribing to a shared folder
  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.
  700 Unsubscribing
  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.
  706 Opening a shared folder
  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.
  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.
  735 References
  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