# Shared folders

This document describes how shared folders are implemented by Courier-IMAP, and SqWebMail, within the framework of the Maildir mail store format. Having the ability to implement shared folders was badly needed for some time. And finally, there's a way to do it!

## Terminology

- Sharable Maildir - a maildir that contains folders that can be shared.
- Sharable folder - one or more folders in a sharable Maildir that can be shared.

## Technical Overview

- They are a somewhat logical extension of the base Maildir format.
- Older versions of Courier-IMAP and SqWebMail will completely ignore shared folders.
- Messages in shared folders do not count towards any individual maildir quotas (see `README.maildirquota.html`).
- Shared folders are implemented as additional, Maildir-based folders. The messages will be soft links to the messages in the sharable folder. Soft links will be used instead of hard links in order to be able to have a folder containing large messages, and then be able to reclaim space immediately when the messages are purged, instead of waiting for everyone to sync up and delete their hard link. The flip side is that you can expect the usual sorts of errors and increased confusion if someone attempts to read a message that has just been removed, but their client (Courier-IMAP or SqWebMail) doesn't know that yet. That's unavoidable. You'll probably have to set some kind of a policy in order to keep the expected insanity to a minimum.
- Sharable folders are subscribed to by creating a separate maildir-type directory within the main Maildir. It's created in a separate subdirectory that is ignored by other Maildir clients.
- The new directory will contains soft links to the messages in the sharable folder. "Synchronization" code will be used to synchronize the contents of the sharable folder, and the copy of it in the regular Maildir. Once links to the messages are created, they can be manipulated like regular messages in a Maildir. This procedure will be transparently performed by Courier-IMAP or SqWebMail behind the scenes.
- Access to shared folders is controlled by a combination of an explicit configuration, plus regular filesystem permissions. If account owners have shell access to the server, they can create shared folders, and link their mailbox to other accounts' shared folders. Then, the actual access is controlled by regular filesystem permissions. The owner of the shared folder will use the regular filesystem permission to give read and/or write access to either everyone else, or everyone else who uses the same system group ID. Read access allows people to read messages from a shared folder. Write access allows people to add and delete messages in the shared. The owner of the shared folder can remove any message, everyone else will be able to remove only their own messages.

## Functional Overview

Generally speaking, shared folders are configured using a feature-enhanced `maildirmake` command as follows:

- `make install` will install a `maildirmake` command that has a bunch of funny options. The modified `maildirmake` command is installed into Courier-IMAP's or SqWebMail's installation directory.
- Somebody, maybe you, will use some of these options to create a maildir with modified permissions. The same somebody will run `maildirmake` again, with a few other options, to create folders in that maildir, also with modified permissions. Those permissions allows global read (and optionally write) access to those folders.
- Do NOT use this maildir as the primary mailbox, INBOX, for an account. Instead, you must create this maildir separately, perhaps as $HOME/Maildir-shared, then set it up as one of your sharable maildirs (see below), and access it in shared mode. Because you own it, you have unlimited read/write access to it. The previously mentioned options will select whether or not access permissions are given to everyone else, and they do not apply to you.
- Everyone else will run `maildirmake` with even more funny options. Those options install a link from their own maildir to a maildir that contains sharable folders. A given maildir may contain links to more than one sharable maildir. As long as their system user/group permissions allow them to access messages, they can SUBSCRIBE via their IMAP client to the folder, or use the SUBSCRIBE function in SqWebmail.
- If people do not have shell access, the system administrator will have to run `maildirmake` on their behalf, in order to create the links to the sharable maildirs.
- People with write access can add messages to a sharable folder. Messages from a sharable folder can be removed only by the owner of the shared folder, or by the owner of each message.
- This sharable maildir implementation cannot use maildir soft-quotas. There cannot be a soft-quota installed in a sharable maildir. If you need quota support, you will have to use filesystem-based quotas. There are some sticky issues with updating quotas on a sharable maildir.

Also, note that anyone, not just the superuser, can create a sharable maildir in their account, and invite anyone else to access it, as long as their system user/group permissions allow them access.

To summarize:

- Use the -S option to `maildirmake` to create a maildir that can contain sharable folders.
- Use the -s and -f options to `maildirmake` to create sharable folders. The same sharable maildir may contain multiple sharable folders with different access permissions, as selected by the -s option.
- Use the `--add` option to install a link from a regular maildir to a sharable maildir. Afterwards, IMAP clients will be able to subscribe to folders in the sharable maildir.
- Use the `--del` option to remove a link.

For more information on these options, see the `maildirmake` manual page that will be installed.

## More on additional options for the `maildirmake` command

The '-S' option to `maildirmake` to create a maildir that will contain shared folders. The -S option gives group and world read permissions on the maildir itself (where group/world permissions are normally not set for a regular maildir). This allows access to any folders in the shared maildir, and that's why you should not use this Maildir directly as your primary mailbox.

The "new" and "cur" subdirectories will not be used or shared, although they will still be created. Both SqWebMail and Courier-IMAP create their auxiliary files in the main Maildir with the group and world permissions turned off, so this maildir can, theoretically, still be used as the primary INBOX, but I don't recommend that.

The -S option is not limited to the system administrator. In fact, anyone can use the -S option, to create shared maildirs that they maintain.

Shared folders are created like any other folder, using the `-f` option to `maildirmake`. However, that normally creates a folder that is not sharable, because it will not have any group or world permissions. Therefore, `maildirmake` will take the following options to create a sharable folder:

- `-s read` will create a "moderated" folder. The folder will have group and world read permissions, letting anyone read messages, but only the owner of the sharable Maildir can add messages to the sharable folder.
- `-s write` will create an "unmoderated" folder. The folder will have group and world read/write permissions, letting anyone read and add messages to the folder. The folder will be created with the sticky bit set, like the `/tmp` directory, preventing people from removing someone else's messages.
- `-s read,group/-s write,group` append a comma and the word "group" to modify the semantics of moderated and unmoderated folders only on the group level, not the group and world level, as far as permissions go. This restricts sharing the folder only to members of the same system group as the owner of the sharable maildir.

It's worth noting that it is perfectly permissible for folders in the same sharable maildir to have different access levels.

Also, this is driven entirely by filesystem permissions, so theoretically it's possible to create a folder that has write permissions for the group, and read permissions for everyone else. However, I'm too lazy to actually do it. Feel free to patch `maildirmake` to add this functionality, then send me the patch.

## Accessing shared folders

The rest of the document consists of technical implementation notes.

Accessing a collection of shared folders is implemented by a new file that is installed in the primary maildir (usually $HOME/Maildir), and a new subdirectory hierarchy underneath the primary maildir, which are hereby declared.

### `shared-maildirs`

This file must be created by the administrator or by the maildir owner, manually. This file lists all available sharable maildirs that this maildir can access in shared mode (confused yet?). This file contains one or more lines of the following format:

`name /path/to/shared/maildir`

"name" is an arbitrary name that's given to this collection of shared folders. The name may not contain slashes, periods, or spaces. This is followed by a pathname to the maildir containing shared folders. Note that this is NOT the sharable folder itself, but the maildir that contains one or more sharable folders. The maildir client will be able to selectively subscribe to any sharable folder in that maildir.

### `shared-folders`

This subdirectory forms the root of all the shared folders that are subscribed to. Let's say that `shared-maildirs` has the following contents:

`firmwide /home/bigcheese/Maildir-shared`
`tech /home/gearhead/Maildir-shared`

Subscribing to folders 'golf' and 'boat' in bigcheese's shared Maildir, and to the folder 'maintenance' in gearhead's shared Maildir involves creating the following subdirectories: `shared-folders/firmwide/.golf`, `shared-folders/firmwide/.boat`, and `shared-folders/tech/.maintenance`.

### `shared`

This is a soft link that's automatically created in `shared-folder/name`. It is a soft link that points to the sharable maildir, which contains the sharable folders.

## Subscribing to a shared folder

- Read `shared-maildirs`.
- Read the `shared-folders` hierarchy to determine which folders are already subscribed to.
- Read the folders in each maildir listed in `shared-folders`, and ignore the ones that are already subscribed to. Make sure to stat() each folder to make sure that you can read it.
- If necessary, create `shared-folders/name`, and create the `shared-folders/name/shared` soft link.
- Create `shared-folders/name/.foldername`, then create the standard `tmp`, `new`, and `cur` subdirectories. All the directories are created without any group or world permissions.

## Unsubscribing

- Delete everything in `shared-folders/name/.foldername`.
- If this is there are no more subscribed folders in this sharable maildir, delete `shared-folders/name` for good measure as well.

## Opening a shared folder

The process of "opening" a shared folder involves basically "syncing" the contents of `shared-folder/name/.foldername` with the contents of the sharable folder in the original sharable maildir.

- Do the usual processing on the `tmp subdirectory`.
- Read the contents of `shared-folder/name/shared/.foldername/new`. If you find anything in there, rename it to `.../cur`, ignoring any errors from the rename. The sharable maildir owner can arrange for mail to be delivered directly to this folder, and the first one to open it will put the message into `cur`.
- Read the contents of `shared-folder/name/shared/.foldername/cur`. Call this directory "A", for short.
- Read the contents of `shared-folder/name/shared/.foldername/cur`. Call this directory "B", for short.
- `stat()` A and B to see if they live on different devices.
- Remove all messages in B that do not exist in A. You want to compare the filenames up to the : character.
- Create soft links from messages that exist in A and do not exist in B. The name in B should not have any flags after the :, so it shows up as a new message.
- You can now do whatever you normally do with a maildir. Note that `new` is completely ignored, though. Moving messages IN and OUT of the shared folder involves copying the message as if it were a new message. Copying the message INTO the shared folder means copying the message into the underlying sharable folder's tmp/cur directory, and it will show up after the next sync.