[Raw Msg Headers][Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: $HOME/maildir
On Wed, 11 Nov 1998, mea@nic.funet.fi wrote:
> > Dnia wto, lis 10, 1998 o 10:56:32 +0200, mea@nic.funet.fi naskrobał(a):
> Hmm... Nationalized automatic texts ?
Yes.
> > > How should the storage file name be derived from the username,
> > > and/or $HOME value ?
>
> Say for a user named "misiek", the home directory is denotable
> as "~misiek" (in good UNIX shell tradition).
>
> If the MAILBOX variable contains some magic value beside current
> MAILBOX=/var/spool/mail
> (which means "store to this directory into a file which name
> is derived from user's username": e.g. /var/spool/mail/misiek )
>
> Storing there a magic string:
> MAILBOX=~/somepath
> would store to thus named *file* which exists in user's home
> directory ( ~misiek/somepath )
>
> Storing there a string:
> MAILBOX=~/somedir/
> would store to file:
> ~misiek/somedir/inbox
> ???
Not quite. MAILBOX=~/something. If "something" is file then would store
to this file (in standard format) but if "something" is directory then
would store to this dir. in maildir format (http://pobox.com/~djb/maildir.html)
Also should be DEFFORMAT={mailbox,maildir}. If user have no existing
"something" file or directory zmailer should create it depending on DEFFORMAT
(if DEFFORMAT=mailbox it creates file called "something"; if DEFFORMAT=Maildir
it creates maildir called "something").
> I have also thought of having a user-specific .zmailerrc,
> which could control local channel deliveries, and perhaps
> store things like what name and address the user wants to
> use in outbound email. (This is not the same as doing router
> rewrites based on some generic mapping rules.)
Also in qmail there is .qmail file and user can put into these file i.e.:
(4) An mbox line begins with a slash or dot, and does not
end with a slash:
/home/djb/Mailbox.sos
qmail-local takes the entire line as a filename. It
appends the mail message to that file.
(5) A maildir line begins with a slash or dot, and ends
with a slash:
/home/djb/Maildir/
qmail-local takes the entire line as the name of a
directory in maildir format. It reliably stores the
incoming message in that directory.
> /Matti Aarnio <mea@nic.funet.fi>
--
-< Arkadiusz Miśkiewicz >------------------------< Cron on IRC >-
http://www.misiek.eu.org mailto:misiek@zsz2.starachowice.pl
SysAdm ZSZ2 http://www.zsz2.starachowice.pl
.TH dot-qmail 5
.SH NAME
dot-qmail \- control the delivery of mail messages
.SH DESCRIPTION
Normally the
.B qmail-local
program delivers each incoming message to your system mailbox,
.IR homedir\fB/Mailbox ,
where
.I homedir
is your home directory.
It can instead
write the mail to a different file or directory,
forward it to another address,
distribute it to a mailing list,
or even execute programs,
all under your control.
.SH "THE QMAIL FILE"
To change
.BR qmail-local 's
behavior, set up a
.B .qmail
file in your home directory.
.B .qmail
contains one or more lines.
Each line is a delivery instruction.
.B qmail-local
follows each instruction in turn.
There are five types of delivery instructions:
(1) comment; (2) program; (3) forward; (4) mbox; (5) maildir.
.TP 5
(1)
A comment line begins with a number sign:
.EX
# this is a comment
.EE
.B qmail-local
ignores the line.
.TP 5
(2)
A program line begins with a vertical bar:
.EX
|/usr/ucb/vacation djb
.EE
.B qmail-local
takes the rest of the line as a command to supply to
.BR sh .
See
.B qmail-command(8)
for further information.
.TP 5
(3)
A forward line begins with an ampersand:
.EX
&me@new.job.com
.EE
.B qmail-local
takes the rest of the line as a mail address;
it uses
.B qmail-queue
to forward the message to that address.
The address must contain a fully qualified domain name;
it must not contain extra spaces, angle brackets, or comments:
.EX
# the following examples are WRONG
.br
&me@new
.br
&<me@new.job.com>
.br
& me@new.job.com
.br
&me@new.job.com (New Address)
.EE
If the address begins with a letter or number,
you may leave out the ampersand:
.EX
me@new.job.com
.EE
Note that
.B qmail-local
omits its new
.B Return-Path
line when forwarding messages.
.TP 5
(4)
An
.I mbox
line begins with a slash or dot,
and does not end with a slash:
.EX
/home/djb/Mailbox.sos
.EE
.B qmail-local
takes the entire line as a filename.
It appends the mail message to that file,
using
.BR flock -style
file locking if possible.
.B qmail-local
stores the mail message in
.I mbox
format, as described in
.BR mbox(5) .
.B WARNING:
On many systems,
anyone who can read a file can
.B flock
it, and thus hold up
.BR qmail-local 's
delivery forever.
Do not deliver mail to a publicly accessible file!
If
.B qmail-local
is able to lock the file, but has trouble writing to it
(because, for example, the disk is full),
it will truncate the file back to its original length.
However, it cannot prevent mailbox corruption if the system
crashes during delivery.
.TP 5
(5)
A
.I maildir
line begins with a slash or dot,
and ends with a slash:
.EX
/home/djb/Maildir/
.EE
.B qmail-local
takes the entire line as the name of a directory in
.I maildir
format.
It reliably stores the incoming message in that directory.
See
.B maildir(5)
for more details.
.PP
If
.B .qmail
has the execute bit set,
it must not contain any
program lines,
.I mbox
lines,
or
.I maildir
lines.
If
.B qmail-local
sees any such lines,
it will stop and indicate a temporary failure.
If
.B .qmail
is completely empty (0 bytes long), or does not exist,
.B qmail-local
follows the
.I aliasempty
instructions set by your system administrator;
normally
.I aliasempty
is
.BR ./Mailbox ,
so
.B qmail-local
appends the mail message to
.B Mailbox
in
.I mbox
format.
.B .qmail
may contain extra spaces and tabs at the end of a line.
Blank lines are allowed, but not for the first line of
.BR .qmail .
If
.B .qmail
is world-writable or group-writable,
.B qmail-local
stops and indicates a temporary failure.
.SH "SAFE QMAIL EDITING"
Incoming messages can arrive at any moment.
If you want to safely edit your
.B .qmail
file, first set the sticky bit on your home directory:
.EX
chmod +t $HOME
.EE
.B qmail-local
will temporarily defer delivery of any message to you
if your home directory is sticky
(or group-writable or other-writable,
which should never happen).
Make sure to
.EX
chmod -t $HOME
.EE
when you are done!
It's a good idea to test your new
.B .qmail
file as follows:
.EX
qmail-local -n $USER $HOME $USER '' '' '' ''
.EE
.SH "EXTENSION ADDRESSES"
In the
.B qmail
system,
you control all local addresses of the form
.IR user\fB-\fIanything ,
as well as the address
.I user
itself,
where
.I user
is your account name.
Delivery to
.I user\fB-\fIanything
is controlled by the file
.IR homedir/\fB.qmail\-\fIanything .
(These rules may be changed by the system administrator;
see
.BR qmail-users (5).)
The
.B alias
user controls all other addresses.
Delivery to
.I local
is controlled by the file
.IR homedir/\fB.qmail\-\fIlocal ,
where
.I homedir
is
.BR alias 's
home directory.
In the following description,
.B qmail-local
is handling a message addressed to
.IR local@domain ,
where
.I local
is controlled by
.BR .qmail\-\fIext .
Here is what it does.
If
.B .qmail\-\fIext
is completely empty,
.B qmail-local
follows the
.I aliasempty
instructions set by your system administrator.
If
.B .qmail\-\fIext
doesn't exist,
.B qmail-local
will try some default
.B .qmail
files.
For example,
if
.I ext
is
.BR foo-bar ,
.B qmail-local
will try first
.BR .qmail-foo-bar ,
then
.BR .qmail-foo-default ,
and finally
.BR .qmail-default .
If none of these exist,
.B qmail-local
will bounce the message.
(Exception: for the basic
.I user
address,
.B qmail-local
treats a nonexistent
.B .qmail
the same as an empty
.BR .qmail .)
.B WARNING:
For security,
.B qmail-local
replaces any dots in
.I ext
with colons before checking
.BR .qmail\-\fIext .
For convenience,
.B qmail-local
converts any uppercase letters in
.I ext
to lowercase.
When
.B qmail-local
forwards a message as instructed in
.B .qmail\-\fIext
(or
.BR .qmail-default ),
it checks whether
.B .qmail\-\fIext\fB-owner\fP
exists.
If so,
it uses
.I local\fB-owner@\fIdomain
as the envelope sender for the forwarded message.
Otherwise it retains the envelope sender of the original message.
Exception:
.B qmail-local
always retains the original envelope sender
if it is the empty address or
.BR #@[] ,
i.e., if this is a bounce message.
.B qmail-local
also supports
.B variable envelope return paths
(VERPs):
if
.B .qmail\-\fIext\fB-owner\fP
and
.B .qmail\-\fIext\fB-owner-default\fP
both exist, it uses
.I local\fB\-owner\-@\fIdomain\fB-@[]
as the envelope sender.
This will cause a recipient
.I recip\fB@\fIreciphost
to see an envelope sender of
.IR local\fB\-owner\-\fIrecip\fB=\fIreciphost\fB@\fIdomain .
.SH "ERROR HANDLING"
If a delivery instruction fails,
.B qmail-local
stops immediately and reports failure.
.B qmail-local
handles forwarding after all other instructions,
so any error in another type of delivery will prevent all forwarding.
If a program returns exit code 99,
.B qmail-local
ignores all succeeding lines in
.BR .qmail ,
but it still pays attention to previous forward lines.
To set up independent instructions,
where a temporary or permanent failure in one instruction
does not affect the others,
move each instruction into a separate
.B .qmail\-\fIext
file, and set up a central
.B .qmail
file that forwards to all of the
.BR .qmail\-\fIext s.
Note that
.B qmail-local
can handle any number of forward lines simultaneously.
.SH "SEE ALSO"
envelopes(5),
maildir(5),
mbox(5),
qmail-users(5),
qmail-local(8),
qmail-command(8),
qmail-queue(8),
qmail-lspawn(8)
.TH maildir 5
.SH "NAME"
maildir \- directory for incoming mail messages
.SH "INTRODUCTION"
.I maildir
is a structure for
directories of incoming mail messages.
It solves the reliability problems that plague
.I mbox
files and
.I mh
folders.
.SH "RELIABILITY ISSUES"
A machine may crash while it is delivering a message.
For both
.I mbox
files and
.I mh
folders this means that the message will be silently truncated.
Even worse: for
.I mbox
format, if the message is truncated in the middle of a line,
it will be silently joined to the next message.
The mail transport agent will try again later to deliver the message,
but it is unacceptable that a corrupted message should show up at all.
In
.IR maildir ,
every message is guaranteed complete upon delivery.
A machine may have two programs simultaneously delivering mail
to the same user.
The
.I mbox
and
.I mh
formats require the programs to update a single central file.
If the programs do not use some locking mechanism,
the central file will be corrupted.
There are several
.I mbox
and
.I mh
locking mechanisms,
none of which work portably and reliably.
In contrast, in
.IR maildir ,
no locks are ever necessary.
Different delivery processes never touch the same file.
A user may try to delete messages from his mailbox at the same
moment that the machine delivers a new message.
For
.I mbox
and
.I mh
formats, the user's mail-reading program must know
what locking mechanism the mail-delivery programs use.
In contrast, in
.IR maildir ,
any delivered message
can be safely updated or deleted by a mail-reading program.
Many sites use Sun's
.B Network F\fPa\fBil\fPur\fBe System
(NFS),
presumably because the operating system vendor does not offer
anything else.
NFS exacerbates all of the above problems.
Some NFS implementations don't provide
.B any
reliable locking mechanism.
With
.I mbox
and
.I mh
formats,
if two machines deliver mail to the same user,
or if a user reads mail anywhere except the delivery machine,
the user's mail is at risk.
.I maildir
works without trouble over NFS.
.SH "THE MAILDIR STRUCTURE"
A directory in
.I maildir
format has three subdirectories,
all on the same filesystem:
.BR tmp ,
.BR new ,
and
.BR cur .
Each file in
.B new
is a newly delivered mail message.
The modification time of the file is the delivery date of the message.
The message is delivered
.I without
an extra UUCP-style
.B From_
line,
.I without
any
.B >From
quoting,
and
.I without
an extra blank line at the end.
The message is normally in RFC 822 format,
starting with a
.B Return-Path
line and a
.B Delivered-To
line,
but it could contain arbitrary binary data.
It might not even end with a newline.
Files in
.B cur
are just like files in
.BR new .
The big difference is that files in
.B cur
are no longer new mail:
they have been seen by the user's mail-reading program.
.SH "HOW A MESSAGE IS DELIVERED"
The
.B tmp
directory is used to ensure reliable delivery,
as discussed here.
A program delivers a mail message in six steps.
First, it
.B chdir()\fPs
to the
.I maildir
directory.
Second, it
.B stat()s
the name
.BR tmp/\fItime.pid.host ,
where
.I time
is the number of seconds since the beginning of 1970 GMT,
.I pid
is the program's process ID,
and
.I host
is the host name.
Third, if
.B stat()
returned anything other than ENOENT,
the program sleeps for two seconds, updates
.IR time ,
and tries the
.B stat()
again, a limited number of times.
Fourth, the program
creates
.BR tmp/\fItime.pid.host .
Fifth, the program
.I NFS-writes
the message to the file.
Sixth, the program
.BR link() s
the file to
.BR new/\fItime.pid.host .
At that instant the message has been successfully delivered.
The delivery program is required to start a 24-hour timer before
creating
.BR tmp/\fItime.pid.host ,
and to abort the delivery
if the timer expires.
Upon error, timeout, or normal completion,
the delivery program may attempt to
.B unlink()
.BR tmp/\fItime.pid.host .
.I NFS-writing
means
(1) as usual, checking the number of bytes returned from each
.B write()
call;
(2) calling
.B fsync()
and checking its return value;
(3) calling
.B close()
and checking its return value.
(Standard NFS implementations handle
.B fsync()
incorrectly
but make up for it by abusing
.BR close() .)
.SH "HOW A MESSAGE IS READ"
A mail reader operates as follows.
It looks through the
.B new
directory for new messages.
Say there is a new message,
.BR new/\fIunique .
The reader may freely display the contents of
.BR new/\fIunique ,
delete
.BR new/\fIunique ,
or rename
.B new/\fIunique
as
.BR cur/\fIunique:info .
See
.B http://pobox.com/~djb/maildir.html
for the meaning of
.IR info .
The reader is also expected to look through the
.B tmp
directory and to clean up any old files found there.
A file in
.B tmp
may be safely removed if it
has not been accessed in 36 hours.
It is a good idea for readers to skip all filenames in
.B new
and
.B cur
starting with a dot.
Other than this, readers should not attempt to parse filenames.
.SH "ENVIRONMENT VARIABLES"
Mail readers supporting
.I maildir
use the
.B MAILDIR
environment variable
as the name of the user's primary mail directory.
.SH "SEE ALSO"
mbox(5),
qmail-local(8)