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 nauseam.

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 message, one per line  

replyto

the address to send any replies to.  

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 portion 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 renumbered. 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.  

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 numbers 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 people 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.  

-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 contents 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 disappeared.

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 protocols 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 authentication  

imaps

TLS-encrypted IMAP CRAM-MD5 or password authentication  

The two IMAP protocols allow an optional fourth field specifying 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 conversation. 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 standardsthere’s so many to choose from.))

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, October, 2008.