UPASFS(4) UPASFS(4)
NAME
upasfs - mail file server
SYNOPSIS
upas/fs [ -DSbdfilnps ][ -c cachtarg ][ -f mailbox ][ -m
mntpoint ]
DESCRIPTION
Fs is a user level file system that caches mailboxes and
presents them as a file system. A user normally starts fs
in his/her profile after starting plumber(4) and before
starting a window system, such as rio(1) or acme(1). The
file system is used by nedmail(1), acme(1)'s mail reader,
and imap4d and pop3 (both pop3(8)) to parse messages. Fs
also generates plumbing messages used by biff and faces(1)
to provide mail announcements.
The mailbox itself becomes a directory under /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 nau-
seam.
Each message and attachment directory contains the files:
body the message minus the RFC2822 style headers
cc the address(es) from the CC: header
date the date in the message, or if none, the time
of delivery
digest an SHA1 digest of the message contents
disposition inline or file
filename a name to use to file an attachment
flags persistant message flags as per IMAP
ffrom the parsed name of the sender
from the from address in the From: header, or if
none, the address on the envelope.
header the RFC822 headers
info described below, essentially a summary of the
header info
inreplyto contents of the in-reply-to: header
lines the number of lines in the message body
messageid the parsed RFC2822 MessageID
mimeheader the mime headers
raw the undecoded MIME message
rawbody the undecoded message body
rawheader the undecoded message header
references the parsed MessageIDs of each referenced mes-
sage, one per line
replyto the address to send any replies to.
Page 1 Plan 9 (printed 12/21/24)
UPASFS(4) UPASFS(4)
subject the contents of the subject line
to the address(es) from the To: line.
type the MIME content type
unixheader the envelope header from the mailbox
unixdate the date portion of the Unix From line.
unixdatesec the mdir filename for mdir messages. The por-
tion before the dot is always the date from
the Unix From line in seconds since epoch.
The info file contains the following information, one item
per line. Lists of addresses are single space separated.
sender address
recipient addresses
cc addresses
reply address
envelope date
subject
MIME content type
MIME disposition
filename
SHA1 digest
bcc addresses
in-reply-to: contents
RFC822 date
message senders
message id
number of lines in body
size of message
message flags
unixdatesec
name from From: header
Deleting message directories causes the message to be
removed from the mailbox.
The mailbox is scanned and the structure updated whenever
the mailbox changes. Message directories are not renum-
bered. The results of the scan are recorded in mailbox.idx.
The file /mail/fs/ctl is used to direct 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:
open path mboxname opens a new mailbox. path is the file
to open, and mboxname is the name that
appears under /mail/fs.
close mboxname close mboxname. The close takes affect
only after all files open under
/mail/fs/mboxname have been closed.
Page 2 Plan 9 (printed 12/21/24)
UPASFS(4) UPASFS(4)
create mboxname create a new maibox, mboxname. The
mailbox type must support creation.
rename [-t] old new rename the mailbox old to new. The 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 rename to convert folder types.
remove [-rt] mboxname
remove mboxname. The r flag removes any
subfolders while the t flag truncates,
rather than removes.
delete mboxname number ...
Delete the messages with the given num-
bers from mboxname.
flag mboxname flags number ...
flag the given messages.
The 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
a answered
D deleted
d draft
f flagged
r recent
s seen
S stored
Messages of the form [+-]flags may be written to the flags
file. Fs maintains the r flag. Mail readers are expected
to maintain other flags.
The options are:
-D Trace 9P protocol messages.
-S Log to console in addition to the standard
places.
-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 peo-
ple telnetting in who want mail announcements.
-c cachetarg attempt to keep the cache below cachetarg
bytes.
-d loud debugging.
-f file use file as the mailbox instead of the
default, /mail/box/username/mbox.
-i chatty index debugging.
Page 3 Plan 9 (printed 12/21/24)
UPASFS(4) UPASFS(4)
-l logging. Turn on logging via syslog (and to
the console with -S) to the file /sys/log/fs.
-m mntpt mount on mntpt rather than the default
/mail/fs.
-n Don't open a mailbox initially. Overridden by
-f.
-p turn off plumbing. Unless this is specified,
fs sends a message to the plumb port, seemail,
from source mailfs for each message received
or deleted. The message contains the
attributes sender=<contents of from file>,
filetype=mail, mailtype=deleted or new, and
length=<message length in bytes>. The con-
tents of the message is the full path name of
the directory representing the message.
-s causes fs to put itself in /srv with a name of
the form /srv/upasfs.user.
-m specifies a mount point other than /mail/fs.
Fs will exit once all references to its directory have dis-
appeared.
Fs interprets mailbox file names of the form
/proto/host/user to mean access an account on host using the
given protocol. Authentication is delegated to factotum(4).
The final /user may be omitted, in which case the user name
is gleaned from the key held by factotum. The following pro-
tocols are supported:
pop cleartext POP with password authentication
apop cleartext POP with challenge-response (APOP)
authentication
poptls TLS-encrypted POP with password authentication
apoptls TLS-encrypted POP with challenge-response (APOP)
authentication
imap cleartext IMAP with CRAM-MD5 or password authenti-
cation
imaps TLS-encrypted IMAP CRAM-MD5 or password authentica-
tion
The two IMAP protocols allow an optional fourth field speci-
fying a mailbox name, for example /imap/server/user/stored.
Poptls and apoptls connect to port 110 in plaintext and
start TLS using the POP STLS command. Imaps connects to
port 993 and starts TLS before initiating the IMAP conversa-
tion. There should probably be pops, apops, and imaptls
protocols as well. (Pops and apops would connect to port
995 and start TLS before initiating the POP conversation,
and imaptls would connect to port 143 in plaintext and start
TLS using the IMAP STARTTLS command. (That's the nice thing
about standards-there's so many to choose from.))
Page 4 Plan 9 (printed 12/21/24)
UPASFS(4) UPASFS(4)
FILES
/mail/box/* mail directories
/mail/box/*/mbox mailbox files /mail/box/*/mbox.idx
mailbox indicies
/mail/box/*/L.mbox mutual exclusion lock for altering
mbox (mbox format only)
SOURCE
/sys/src/cmd/upas/fs
SEE ALSO
aliasmail(8), faces(1), filter(1), mail(1), marshal(1),
mdir(6), mlmgr(1), nedmail(1), pop3(8), qer(8), rewrite(6),
send(8), upasfs(4),
Erik Quanstrom ``Scaling Upas'', Procedings of IWP9, Octo-
ber, 2008.
Page 5 Plan 9 (printed 12/21/24)