FILTER(1)                                               FILTER(1)

     NAME
          filter, list, deliver, token, vf -  filtering mail

     SYNOPSIS
          upas/filter [ -bh ] rcvr mailbox [ regexp file ] ...

          upas/list [ -d ] add|check patternfile addressfile ...

          upas/deliver recipient fromfile mbox

          upas/token key [ tokenfile ]

          upas/vf [ -r ] [ -s savefile ]

     DESCRIPTION
          A user may filter all incoming mail by creating a world
          readable/executable file /mail/box/username/pipeto.  If the
          file is a shell script, it can use the commands described
          here to implement a filter.

          Filter provides simple mail filtering.  The first two argu-
          ments are the recipient's address and mailbox, that is, the
          same arguments provided to pipeto.  The remaining arguments
          are all pairs of a regular expression and a file name.  With
          no flags, the sender's address is matched against each regu-
          lar expression starting with the first.  If the expression
          matches, then the message is delivered to the file whose
          name follows the expression.  The file must be world writ-
          able and should be append only.  A message that matches none
          of the expressions is delivered into the user's standard
          mail box.

          By default, filter matches each regular expression against
          the message's sender.  The -h flag causes filter to match
          against the entire header, and the -b flag causes filter to
          match against the entire message (header and body).

          For example, to delete any messages of precedence bulk,
          place in your pipeto file:

               /bin/upas/filter -h $1 $2 'Precedence: bulk' /dev/null

          Three other commands exist which, combined by an rc(1)
          script, allow you to build your own filter.

          List takes two verbs; check and add.  Check directs list to
          check each address contained in the addressfiles against a
          list of patterns in patternfile. Patterns come in four
          forms:

     FILTER(1)                                               FILTER(1)

          ~regular-expression  If any address matches the regular
                               expression, list returns successfully.

          =string.             If any address exactly matches string,
                               list returns successfully.

          !~regular-expression If any address matches the regular
                               expression and no other address matches
                               a non `!' rule, list returns error sta-
                               tus "!match".

          !=string             If any address exactly matches string
                               and no other address matches a non `!'
                               rule, list returns error status
                               "!match".

          If no addresses match a pattern, list returns "no match".

          The pattern file may also contain lines of the form

               #include filename

          to allow pattern files to include other pattern files.  All
          pattern matches are case insensitive.  List searches the
          pattern file (and its includes) in order.  The first match-
          ing pattern determines the action.

          List add directs list to add a pattern to patternfile for
          each address in the addressfiles that doesn't already match
          a pattern.

          Token, with only one argument, prints to standard output a
          unique token created from the current date and key. With two
          arguments, it checks token against tokens created over the
          last 10 days with key. If a match is found, it returns suc-
          cessfully.

          Deliver delivers into mail box mbox the message read from
          standard input.  It obeys standard mail file locking and
          logging conventions.

          /sys/src/cmd/upas/filterkit/pipeto.sample is a sample pipeto
          using the filter kit.

          A sample pipefrom,
          /sys/src/cmd/upas/filterkit/pipefrom.sample, is provided
          which adds all addresses of your outgoing mail to your pat-
          tern file.  You should copy it into a directory that nor-
          mally gets bound by your profile onto /bin.

          Vf (virus filter) takes a mail message as standard input and
          searches for executable MIME attachments, either rewriting

     FILTER(1)                                               FILTER(1)

          them to be non-executable or rejecting the message.  The
          behavior depends on the attachment's file name extension and
          MIME content type.  /sys/lib/mimetype contains the list of
          known extensions and MIME content types.  The fifth field of
          each line specifies the safety of a particular file type: y
          (yes), m (maybe; treated same as yes), n (no), p (previous),
          or r (reject).  Vf allows attachments with safety y or m to
          pass through unaltered.  Attachments with safety n both are
          wrapped in extra MIME headers and have .suspect appended to
          their file names, to avoid automatic execution by mail read-
          ers.  Attachments with safety r (currently, .bat, .com,
          .exe, and .scr, all Microsoft executable extensions) are
          taken as cause for the entire message to be rejected.  A
          safety of p (used for the x-gunzip mime type) causes the
          previous extension to be tested, so that x.tar.gz is treated
          the same as x.tar.

          If /mail/lib/validateattachment exists and is executable, vf
          runs it on all attachments with safety n (attachments it
          would normally sanitize).  If validateattachment's exit sta-
          tus contains the string `discard', vf rejects the entire
          message.  If the status contains the string `accept', vf
          does not sanitize the attachment.  Otherwise, vf sanitizes
          the attachment as before.  The standard validateattachment
          uses file(1) to determine the file type.  It accepts text
          and image files and discards messages containing executables
          or zip (see gzip(1)) archives of executables.

          The -r option causes vf not to sanitize MIME attachments,
          but instead to reject messages it determines to be viruses.
          The -s option causes vf to log all attachments of safety r
          in the mail box savefile.

     FILES
          /mail/box/*/pipeto            mail filter
          /sys/lib/mimetype             MIME content types
          /mail/lib/validateattachment  attachment checker

     SOURCE
          /sys/src/cmd/upas/send
          /sys/src/cmd/upas/filterkit
          /sys/src/cmd/upas/vf

     SEE ALSO
          aliasmail(8), faces(1), mail(1), marshal(1), mlmgr(1),
          nedmail(1), qer(8), rewrite(6), send(8), smtp(8), upasfs(4)