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 3/28/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 3/28/24)

     UPASFS(4)                                               UPASFS(4)

          create mboxname     create a new mailbox, 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 3/28/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.

          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 3/28/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)
          Erik Quanstrom ``Scaling Upas'', Proceedings of IWP9, Octo-
          ber, 2008.

     Page 5                       Plan 9             (printed 3/28/24)