Courier-IMAP

# Courier-IMAP version 3 Beta

Contents of this NEWS file:

> Introduction
> Shared folders and access control lists
> The new Courier-IMAP installation script (version 2)
> Upgrading from Courier-IMAP 1.2.3 and earlier

### Introduction

This is a beta build of the next major release of the Courier-IMAP server. Extensive testing of this beta release is strongly desired. Even if you do not have an immediate use for any major features in the new release, such as virtual shared folders and access control lists, there have been major internal changes to the code to accomodate all the new stuff. Beta testing should concentrate on the following areas:

- Interoperability with IMAP clients that make use of access control lists
- Virtual shared folders, with various kinds of authenticatiom back-ends: PostgreSQL, LDAP, MySQL
- Memory leaks in either the IMAP server, or the authentication daemons
- Impact of new shared folder and ACL functionality on other IMAP aspects: namely quotas, and concurrent access

Starting with Courier-IMAP 3, the default configuration enables metadata dot-locking. In previous version metadata dot-locking (`IMAP_USELOCKS` setting in the imapd configuration file) is disabled by default. Dot-locking was, and still is optional. When enabled, its value-added functionality is elimination of certain non-critical race conditions with concurrent access. Dot-locking is now enabled by default due to its proven record of "mostly harmless", and that it now provides added benefit with ACLs and shared folders. However, when upgrading from an earlier version, the existing configuration setting is left in place; only new installation of Courier-IMAP will default to enabled dot-locking.

### Shared folders and access control lists

New to Courier-IMAP 3 are the ACL (access control list) IMAP extension, and ACL-based virtual shared folders. Courier-IMAP 3 implements both the existing ACL specification, RFC 2086, as well as an experimental implementation of the second draft revision of the ACL specification. Virtual shared folders is a different implementation of shared folders that supplements an older implementation in Courier-IMAP 2, and earlier. The older, POSIX permission-based shared folders are still implemented and supported. Here's a summary of the differences between the two shared folder mechanisms:

> POSIX-based shared folders | ACL shared folders
> --- | ---
> May be used with system accounts only1 | May be used with virtual accounts only; cannot be used on systems that have end-user login shell access: bypassing ACLs and accessing the folders directly is trivial
> Access rights based on traditional POSIX filesystem permissions | Access rights based on IMAP access control lists
> Sharable folders must be set up manually, using the "maildirmake" command | A site-specific process must be installed to compile an index of all virtual mailboxes; afterwords, individual users may create and manage shared folders themselves

> > 1 This is because access rights are governed by filesystem permissions. POSIX shared folders may also be used with virtual accounts, but it will not be possible to grant read-only access to shared folders, and everyone will be able to delete messages from shared folders (instead of only the creator of each message)

After installation, read the "maildiracl" manual page for a brief overview of access control lists.

Read "maildir/README.sharedfolders.html" for information on configuring virtual shared folders

### The new Courier-IMAP installation script (version 2).

Packagers: you can now create a master package of Courier-IMAP, with the base package providing basic system authentication, and additional add-on packages that add LDAP and MySQL authentication ability.

Additionally, starting with version 1.3, configuration files can be upgraded automatically, see below.

Here's how.

1. Build Courier-IMAP on a machine that has OpenLDAP and MySQL development libraries. Choose the default option to build the authdaemon module.
2. Run make install.
3. Package everything that gets installed, EXCEPT for authdaemon.ldap and authdaemon.mysql, into the base package.
4. Package authdaemon.ldap into the ldap subpackage.
5. Package authdaemon.mysql into the mysql subpackage.
6. The base package is installable on ANY system, it does not need MySQL or OpenLDAP. The subpackages are installable only on those system that have the necessary runtime OpenLDAP and MySQL libraries.

That's it.

### Upgrading from Courier-IMAP 1.2.3 and earlier

Courier-IMAP 1.3.0 introduced a new configuration file format that allows configuration files to be automatically upgraded. Additionally, several existing configuration files have been renamed in order for their names to be consistent with the Courier build:

    Courier-IMAP < 1.3  Courier-IMAP 1.3.0
    --------            ---------
    imapd.config        imapd
    imapd-ssl.config    imapd-ssl
    pop3d.config        pop3d
    pop3d-ssl.config    pop3d-ssl

A new step has been added to the installation document: "make install-configure" to be performed after "make install". "make install-configure" will install the new configuration files, but preserve the existing configuration, provided that it's compatible.

The output of "make install-configure" should be saved. It will list each configuration setting, and its eventual disposition.

See INSTALL for more information.

Make install-configure should only be used when installing Courier-IMAP by hand. To create an installable package, do not run "make install-configure" during the build, instead:

- After running make install, obtain the list of all $sysconfdir/*.dist files. The configuration files that are installed by 'make install' are named 'filename.dist', instead of 'filename' (well, filename.config) as was the case previously.
- Add the sysconftool script to the installation package. 'make install' does not automatically install the 'sysconftool' script anywhere, because 'make install-configure' runs it directly from the source directory. You want to include the tiny sysconftool script in the installed package.
- When the package is installed, the post-installation script must run sysconftool, and provide the filename list $sysconfdir/*.dist as its arguments. sysconftool takes each filename.dist and copies it to filename. Additionally, if there is an existing filename, its configuration settings are automatically preserved. Additionally, the previous filename is automatically backed up as filename.bak, by sysconftool.

As a rough example, you need to do something like this during packaging:

    ls $sysconfdir/*.dist >$datadir/courier-imap/configlist
    cp sysconftool >$datadir/courier-imap/sysconftool

Then, your package installation script runs the following after the package is installed:

    $datadir/courier-imap/sysconftool `cat $datadir/courier-imap/configlist`