.\" .\" .\" .\" This manpage has been automatically generated by docbook2man .\" from a DocBook document. This tool can be found at: .\" .\" Please send any bug reports, improvements, comments, patches, .\" etc. to Steve Cheng . .TH "MAILDIRMAKE" "1" "17 January 2002" "Double Precision, Inc." "" .SH NAME maildirmake \- create maildirs and maildir folders .SH SYNOPSIS \fBmaildirmake\fR [ \fBoptions\fR\fI ...\fR] \fB\fImaildir\fB\fR .SH "DESCRIPTION" .PP The \fBmaildirmake\fR command creates maildirs, and maildir folders. This documentation describes the \fBmaildirmake\fR command from the Courier mail server, which creates an extended form of maildirs that implements additional extensions beyond the basic maildir properties that were first implemented in the Qmail mail server. .PP A "Maildir" is a directory that holds mail messages, one message per file. But not just any directory will do - a Maildir must have a specific structure that enables mail access without requiring any kind of locking, and have specific access permissions. The \fBmaildirmake\fR command is a convenient way to create a new Maildir, or a new folder within an existing Maildir, with the correct permission and structure. .SH "OPTIONS" .TP \fB-S\fR create a "sharable" maildir. A sharable maildir has slightly different permissions which allows creation of publicly-shared folders. .TP \fB-f \fIfolder\fB\fR do not create a maildir, but create a folder in an existing maildir. .TP \fB-s \fImode\fB\fR create a publicly accessible folder in an existing sharable maildir. First, use the \fB-S\fR option to create a sharable maildir. Then, run \fBmaildirmake\fR again with the \fB-s\fR option to create publicly accessible folders. \fImode\fR is a comma-separated list of the following keywords: read - readonly folder, only you can write messages to this folder; write - anyone can read and write messages to this folder; group - only allow members of your own system group to access messages in this folder (instead of everyone). .TP \fB--add \fIname\fB=\fIpathname\fB, --del \fIname\fB\fR create or delete the directories and links needed to access shared folders. See below for more information. .SS "FOLDERS" .PP This \fBmaildirmake\fR command supports enhanced maildirs that contain folders. .PP By itself, \fBmaildirmake\fR makes a new subdirectory \fImaildir\fR, and creates all the necessary structures. The \fB-f\fR option creates a new "folder" within an existing \fImaildir\fR. \fImaildir\fR must already exist, and the \fBmaildirmake\fR command will create a new folder in the maildir. .PP Folders are simply subdirectories inside the main maildir whose names start with a period, and which are themselves maildirs. For example, the command "\fBmaildirmake -f Drafts mail/Maildir\fR" creates \fImail/Maildir/.Drafts\fR, that has the usual \fItmp\fR, \fInew\fR and \fIcur\fR. You MUST use the \fB-f\fR option, instead of specifying \fImail/Maildir/.Drafts\fR directly, in order to correctly initialize certain enhanced maildir features. .PP Folders cannot be created directly within other folders. Running \fBmaildirmake -f Urgent mail/Maildir/.Drafts\fR will not work. Instead, the period character is designated as a hierarchy separator, run \fBmaildirmake -f Drafts.Urgent mail/Maildir\fR instead. This creates \fImail/Maildir/.Drafts.Urgent\fR, and all mail software that supports enhanced maildirs will interpret it as a subfolder Urgent of the Drafts folder. .SS "SHARED FOLDERS" .PP This is another extension to the Maildir format that allows folders to be shared between multiple clients. First, you need to create a collection of sharable folders, as a separate maildir: .sp .RS .PP .nf \fBmaildirmake -S /usr/local/share/maildirs/notices\fR .fi .RE .PP Then, create individuals folders that will be accessed in shared mode: .sp .RS .PP .nf \fBmaildirmake -s write -f Weekly /usr/local/share/maildirs/notices\fR .fi .RE .PP In this example, the "Weekly" folder is created, with read/write access to everyone. Multiple folders can be created in the same maildir, with different access permissions. Everyone can create a sharable maildir. The access privileges for individual folders are set by the \fB-s\fR option, and are implemented using traditional filesystem permissions. .PP Use the \fB--add\fR and \fB--del\fR options to add a sharable maildir to an existing maildir. Client software that implements this extension will now know where to find sharable folders: .sp .RS .PP .nf \fBmaildirmake --add notices=/usr/local/share/maildirs/notices $HOME/Maildir\fR .fi .RE .PP \fI$HOME/Maildir\fR is your main maildir. The argument to \fB-add\fR is \fInick\fR=\fIpath\fR. \fInick\fR is a nickname for this collection of sharable folders, and \fIpath\fR is the location of the sharable maildir. All folders in the sharable maildir that you have access to -- such as "Weekly", in this case, will now be accessible. Multiple sharable maildirs can be added, by giving each one a unique \fInick\fR. .PP The \fB--del\fR option "disconnects" the sharable maildir from the main maildir. .SS "GLOBAL SHARED FOLDERS" .PP Normally \fB-add\fR command must be run for every maildir which needs to access the sharable maildir. Alternatively the file \fI/usr/local/share/sqwebmail/maildirshared\fR can be created, to specify a default set of sharable maildirs. Each line in this file takes the following format: .sp .RS .PP .nf \fInick\fR\fIpath\fR .fi .RE .PP \fInick\fR is a short nickname for the sharable maildir, is a single tab character, \fIpath\fR is the pathname to the sharable maildir. .SS "ACCESSING SHARED FOLDERS" .PP You may have read or write access to a shared folder. If you have write access, you can add messages to the shared folder. You can also delete messages that you've added. .PP Anyone can create a sharable maildir, so if the sharable maildir is actually created by you, can can delete any message, not just your own. .SS "MAILDIR STRUCTURE" .PP The rest of this manual page describes the technical implementation of Maildirs. The first implementation and definition of Maildirs was in Dan Bernstein's Qmail mail server, and it described a single, flat, mail repository. The Courier mail server adds additional features such as folders and voluntary mail quotas. This document describes the enhanced Maildir implementation without identifying the specific enhancements to the original Maildir implementation. See http://www.qmail.org/man/man5/maildir.html for the original specifications of Maildirs. .PP Maildirs offer several improvements over traditional mailbox files. Unlike mailbox files, no locking is necessary in order to deliver new messages to maildirs, or to read mail in maildirs. Multiple agents can deliver new mail to maildirs, in parallel, and read mail from maildirs. Locking is often problematic with certain network file system. Maildirs require no locking, and can be implemented on top of almost any file system. .PP A maildir is an ordinary subdirectory, with group and world access permissions revoked, of course. A maildir contains three subdirectories: \fItmp\fR, \fInew\fR, and \fIcur\fR. Folders are additional subdirectories whose names begin with a period: such as \fI.Drafts\fR or \fI.Sent\fR. Each folder itself contains the same three subdirectories, \fItmp\fR, \fInew\fR, and \fIcur\fR, and can be thought of as a maildir in of itself, except that it itself cannot contain nested folder subdirectories, as explained above. .PP A folder subdirectory also contains an extra, zero-length file named \fImaildirfolder\fR, whose purpose is to simply inform any mail delivery agent that it really is delivering to a folder, and that the mail delivery agent should look in the parent directory for any required housekeeping information. Software that uses maildirs may also create additional files besides the \fItmp\fR, \fInew\fR, and \fIcur\fR subdirectories -- in the main maildir or a folder "submaildir" -- for its own use. .PP E-mail messages are stored in separate, individual files as defined below, one E-mail message per file. The \fItmp\fR subdirectory temporarily stores E-mail messages that are in the process of being delivered to this maildir. \fItmp\fR may also store other kinds of temporary files, as long as they follow the same filename naming convention for creating new files in \fItmp\fR. The \fInew\fR subdirectory stores messages that have been delivered to this maildir, but have not yet been seen by any mail application. The \fIcur\fR subdirectory stores messages that have already been seen by mail applications. .SS "DELIVERING NEW MAIL TO MAILDIRS" .PP The following process is used to deliver mail to a maildir: .PP A new unique filename is created using one of two possible forms: "time.pid.host", or "time.pid_unique.host". "time" is the current system time, in seconds. "pid" is the process number of the process that is delivering this message to the maildir. "host" is the name of the machine where the mail is being delivered. In the event that the same process will create multiple messages, it should append a unique suffix to the process id, preferrably an underscore, followed by an increasing counter. This applies whether messages created by a process are all in the same, or different, maildirs. This protocol allows multiple processes running on multiple machines on the same network to simultaneously create new messages without stomping on each other. .PP The filename created in the previous step is checked for existence by executing the \fBstat\fR(2) system call, against the \fItmp\fR subdirectory. If the result of the \fBstat\fR(2) system call is ANYTHING OTHER than the system error ENOENT, the process must sleep for two seconds, then go back and create a new unique filename. This is an extra step to insure that each new message has a completely unique filename. .PP Other applications that wish to use \fItmp\fR for temporary storage should observe the same protocol (but see READING MAIL FROM MAILDIRS below, because old files in \fItmp\fR will be eventually deleted). .PP If the \fBstat\fR(2) system call returned ENOENT, the process may procede to create the file in the \fItmp\fR subdirectory, and save the entire message in the new file. The message saved MUST NOT have the traditional "From_" line that is used to separate individual messages in the traditional mailbox files. The message also MUST NOT have any "From_" lines in the contents of the message prefixed by the ">" character, as messages in traditional mailbox files are. .PP Saving the message means to reliably save it in a file. The number of bytes returned by the \fBwrite\fR(2) system call must be checked, in order to make sure that the complete message has been written out. .PP After the message is saved, the file is closed and is then immediately moved/renamed into the \fInew\fR subdirectory. The name of the file should be the same name it had in the \fItmp\fR subdirectory. .PP It is HIGHLY RECOMMENDED that software that creates messages in maildirs should also append the suffix ",S=nnn" to the name of the file when it is moved into the \fInew\fR subdirectory, where "nnn" represents the size of the message, in bytes. This optimizes the voluntary maildir quota enhancement, as it permits the size of all the mail stored in the maildir to be added up without issuing the \fBstat\fR(2) system call for each individual message (which can be quite a performance drain with certain network filesystems). .SS "READING MAIL FROM MAILDIRS" .PP Applications that read mail from maildirs should do it in the following order: .PP When opening a maildir or a maildir folder, read the \fItmp\fR subdirectory and delete anything in there that's at least 36 hours old. .PP Look for new messages in the \fInew\fR subdirectory. For each new message found, \fInew/filename\fR, rename it as \fIcur/filename:2,info\fR. Here, \fIinfo\fR represents the state of the message, and it consists of zero or more boolean flags chosen from the following: D - this is a 'draft' message, R - this message has been replied to, S - this message has been viewed (seen), T - this message has been marked to be deleted (trashed), but is not yet removed (messages are removed from maildirs simply by deleting their file), F - this message has been marked by the user, for some purpose. These flags must be stored in alphabetic order. New messages contain only the :2, suffix, with no flags, indicating that the messages haven't been seen, replied, marked, or deleted. .PP Maildirs may have maximum size quotas defined, but these quotas are purely voluntary. If you need to implement mandatory quotas, you should use any quota facilities provided by the underlying filesystem that is used to store the maildirs. The maildir quota enhancement is designed to be used in certain situations where filesystem-based quotas cannot be used for some reason. The implementation is designed to avoid the use of any locking. As such, at certain times the calculated quota may be imprecise, and certain anomalous situations may result in the maildir actually going over the stated quota. One such situation would be when applications create messages without updating the quota estimate for the maildir. Eventually it will be precisely recalculated, but wherever possible new messages should be created in compliance with the voluntary quota protocol. .PP The voluntary quota protocol involves some additional procedures that must be followed when creating or deleting messages within a given maildir or its subfolders. The \fBdeliverquota\fR(8) command is a tiny application that delivers a single message to a maildir using the voluntary quota protocol, and hopefully it can be used as a measure of last resort. Alternatively, applications can use the \fIlibmaildir.a\fR library to handle all the low-level dirty details for them. The voluntary quota enhancement is described in the \fBmaildirquota\fR(7). .SH "SEE ALSO" .PP \fBmaildrop\fR(1), \fBmaildirquota\fR(7), \fBdeliverquota\fR(8), \fBmaildropfilter\fR(7), http://www.qmail.org/man/man5/maildir.html.