.TH UPASFS 4
.SH NAME
upasfs \- mail file server
.SH SYNOPSIS
.B upas/fs
[
.B -DSbdfilnps
][
.B -c
.I cachtarg
][
.B -f
.I mailbox
][
.B -m
.I mntpoint
]
.SH DESCRIPTION
.PP
.I Fs
is a user level file system that caches mailboxes and presents them as a file
system.
A user normally starts
.I fs
in his/her profile after starting
.IR plumber (4)
and before starting
a window system, such as
.IR rio (1)
or
.IR acme (1).
The file system is used by
.IR nedmail (1),
.IR acme (1)'s
mail reader, and
.I imap4d
and
.I pop3
(both
.IR pop3 (8))
to parse messages.
.I Fs
also generates plumbing messages used by
.IR biff
and
.IR faces (1)
to provide mail announcements.
.PP
The mailbox itself becomes a directory under
.BR /mail/fs .
Each message in the mailbox becomes a numbered directory in the
mailbox directory, and each attachment becomes a numbered directory
in the message directory.  Since an attachment may itself be a mail message,
this structure can recurse ad nauseam.
.PP
Each message and attachment directory contains the files:
.TP 1.4i
.B body
.PD 0
the message minus the RFC2822 style headers
.TP
.B cc
the address(es) from the CC: header
.TP
.B date
the date in the message, or if none, the time of delivery
.TP
.B digest
an SHA1 digest of the message contents
.TP
.B disposition
.B inline
or
.B file
.TP
.B filename
a name to use to file an attachment
.TP
.B flags
persistant message flags as per IMAP
.TP
.B ffrom
the parsed name of the sender
.TP
.B from
the from address in the From: header, or if none,
the address on the envelope.
.TP
.B header
the RFC822 headers
.TP
.B info
described below, essentially a summary of the header info
.TP
.B inreplyto
contents of the
.B in-reply-to:
header
.TP
.B lines
the number of lines in the message body
.TP
.B messageid
the parsed RFC2822 MessageID
.TP
.B mimeheader
the mime headers
.TP
.B raw
the undecoded MIME message
.TP
.B rawbody
the undecoded message body
.TP
.B rawheader
the undecoded message header
.TP
.B references
the parsed MessageIDs of each referenced message,
one per line
.TP
.B replyto
the address to send any replies to.
.TP
.B subject
the contents of the subject line
.TP
.B to
the address(es) from the To: line.
.TP
.B type
the MIME content type
.TP
.B unixheader
the envelope header from the mailbox
.TP
.B unixdate
the date portion of the Unix From line.
.TP
.B unixdatesec
the mdir filename for mdir messages.  The portion
before the dot is always the date from the Unix From
line in seconds since epoch.
.PD
.PP
The
.B info
file contains the following information, one item per line.  Lists
of addresses are single space separated.
.IP
.TP 2i
.I "sender address
.PD 0
.TP
.I "recipient addresses
.TP
.I "cc addresses
.TP
.I "reply address
.TP
.I "envelope date
.TP
.I "subject
.TP
.I "MIME content type
.TP
.I "MIME disposition
.TP
.I filename
.TP
.I "SHA1 digest
.TP
.I "bcc addresses
.TP
.I "in-reply-to: contents
.TP
.I "RFC822 date
.TP
.I "message senders
.TP
.I "message id
.TP
.I "number of lines in body
.TP
.I "size of message
.TP
.I "message flags
.TP
.I unixdatesec
.TP
.I name from From: header
.PD
.PP
Deleting message directories causes the message to be removed from
the mailbox.
.PP
The mailbox is scanned and the structure updated
whenever the mailbox changes.  Message directories are
not renumbered. The results of the scan are
recorded in
.IR mailbox ".idx".
.PP
The file
.B /mail/fs/ctl
is used to direct
.I fs
to open, close, rename, create or remove new mailboxes,
and also to
delete or flag groups of messages atomically.
The messages that can be written to this file are:
.TP 2i
.PD 0
.B "open \fIpath mboxname\fP
opens a new mailbox.
.I path
is the file to open, and
.I mboxname
is the name that appears under
.BR /mail/fs .
.TP
.B "close \fImboxname\fP
close
.IR mboxname .
The close takes affect only after all files open under
.BI /mail/fs/ mboxname
have been closed.
.TP
.B "create \fImboxname\fP
create a new maibox,
.BR mboxname .
The mailbox type must support creation.
.TP
.B "rename [-t] \fIold new\fP
rename the mailbox
.I old
to 
.IR new .
The
.I t
flag truncates rather than removes the old
mailbox.
The renaming takes effect immedately.  While mailboxes
of any type may be renamed, it is not possible to use
.B rename
to convert folder types.
.TP
.B "remove [-rt] \fImboxname\fP
remove
.BR mboxname .
The
.I r
flag removes any subfolders while
the
.I t
flag truncates, rather than removes.
.TP
.B "delete \fImboxname number ...\fP
Delete the messages with the given numbers from
.IR mboxname.
.TP
.B "flag \fImboxname flags number ...\fP
flag the given messages.
.PD
.PP
The
.B flags
file records persistant message flags.  These
flags are a superset of the standard IMAP message
flags. Flags are stored in order.  Unset flags
are represented by a
`-' while set flags are represented by the following
ordered characters
.TF "D
.TP
.B a
answered
.TP
.B D
deleted
.TP
.B d
draft
.TP
.B f
flagged
.TP
.B r
recent
.TP
.B s
seen
.TP
.B S
stored
.PD
.PP
Messages of the form
.BI "[+-]" flags
may be written to the
.B flags
file.
Fs maintains the
.I r
flag.  Mail readers are expected
to maintain other flags.
.PP
The options are:
.TF "-c cachetarg
.TP
.B -D
Trace 9P protocol messages.
.TP
.B -S
Log to console in addition to the standard places.
.TP
.B -b
stands for biffing.  Each time new mail
is received, a message is printed to standard
output containing the sender address, subject,
and number of bytes.  It is intended for
people telnetting in who want mail announcements.
.TP
.B -c \fIcachetarg\fP
attempt to keep the cache below
.I cachetarg
bytes.
.TP
.B -d
loud debugging.
.TP
.B -f \fIfile\fP
use
.I file
as the mailbox instead of the default,
.BI /mail/box/ username /mbox.
.PD 0
.TP
.B -i
chatty index debugging.
.TP
.B -l
logging.  Turn on logging via syslog
(and to the console with -\fIS\fP) to
the file
.BR /sys/log/fs .
.TP
.B -m \fImntpt\fP
mount on
.I mntpt
rather than the default
.BR /mail/fs .
.TP
.B -n
Don't open a mailbox initially.  Overridden by -f.
.TP
.B -p
turn off plumbing.  Unless this is specified,
.I fs
sends a message to the plumb port,
.BR seemail ,
from source
.B mailfs
for each message received or deleted.
The message contains the attributes
.IR sender = "<contents of from file>" ,
.IR filetype =mail,
.IR mailtype = "deleted or new" ,
and
.IR length = "<message length in bytes>" .
The contents of the message is the full path
name of the directory representing the message.
.TP
.B -s
causes
.I fs
to put itself in
.B /srv
with a name of the form
.BR /srv/upasfs.\fIuser\fP .
.PD
.PP
.I Fs
will exit once all references to its directory
have disappeared.
.PP
.I Fs
interprets mailbox file names of the form
.BI / proto / host / user
to mean access an account on
.I host
using the given protocol.
Authentication is delegated to
.IR factotum (4).
The final
.BI / user
may be omitted, in which case
the user name is gleaned from the key held by
.IR factotum .
The following protocols are supported:
.PP
.TF apoptls
.TP
.B pop
cleartext POP with password authentication
.TP
.B apop
cleartext POP with challenge-response (APOP) authentication
.TP
.B poptls
TLS-encrypted POP with password authentication
.TP
.B apoptls
TLS-encrypted POP with challenge-response (APOP) authentication
.TP
.B imap
cleartext IMAP with CRAM-MD5 or password authentication
.TP
.B imaps
TLS-encrypted IMAP CRAM-MD5 or password authentication
.PD
.PP
The two IMAP protocols allow an optional fourth field
specifying a mailbox name, for example
.BR /imap/server/user/stored .
.PP
.B Poptls
and
.B apoptls
connect to port 110 in plaintext and start TLS using the POP
STLS command.
.B Imaps
connects to port 993 and starts TLS before initiating the IMAP conversation.
There should probably be
.BR pops ,
.BR apops ,
and
.B imaptls
protocols as well.
.RB ( Pops
and
.B apops
would connect to port 995 and start TLS before initiating the POP conversation,
and
.B imaptls
would connect to port 143 in plaintext and start TLS using the IMAP
STARTTLS command.
(That's the nice thing about standards\(emthere's so many to choose from.))
.SH FILES
.TF /mail/box/*/dead.letter
.TP
.B /mail/box/*
mail directories
.TP
.B /mail/box/*/mbox
mailbox files
.B /mail/box/*/\fImbox\fP.idx
mailbox indicies
.TP
.B /mail/box/*/L.mbox
mutual exclusion lock for altering mbox (mbox format only)
.SH SOURCE
.TP
.B /sys/src/cmd/upas/fs
.SH "SEE ALSO"
.IR aliasmail (8),
.IR faces (1),
.IR filter (1),
.IR mail (1),
.IR marshal (1),
.IR mdir (6),
.IR mlmgr (1),
.IR nedmail (1),
.IR pop3 (8),
.IR qer (8),
.IR rewrite (6),
.IR send (8),
.IR upasfs (4),
.br
Erik Quanstrom
``Scaling Upas'',
Procedings of IWP9,
October, 2008.