NAME

       setforward - create a forwarding database

SYNOPSIS

       setforward cdb tmp

DESCRIPTION

       setforward  reads a table of forwarding instructions from its standard input.  It converts
       the table into a forwarding database.  The forwarding database can be used by fastforward.

       setforward writes the forwarding database to tmp; it then moves tmp to cdb.  tmp  and  cdb
       must be on the same filesystem.

       If there is a problem creating tmp, setforward complains and leaves cdb alone.

       The forwarding database format is portable across machines.

INSTRUCTION FORMAT

       A  forwarding  instruction  contains  a  target,  a  colon,  a  series  of commands, and a
       semicolon.  Each command is a recipient address, owner address, external mailing list,  or
       program.  Commands are separated by commas.

       For example,

          root@yp.to: god@heaven.af.mil, staff@af.mil;

       says   that   mail   for  root@yp.to  should  be  forwarded  to  the  recipient  addresses
       god@heaven.af.mil and staff@af.mil.

       When setforward sees # it ignores all text from # to the end of the line:

          # this is a comment

       setforward ignores all other line endings, so  you  can  split  a  forwarding  instruction
       across lines.  It also ignores spaces and tabs.  Exception: you can put a space (or tab or
       comma or whatever) into a target or command  by  putting  a  backslash  in  front  of  it.
       (However, NUL bytes are not permitted anywhere.)

TARGETS

       When  fastforward  sees  the  incoming  address  user@host.dom,  it  tries  three targets:
       user@host.dom, @host.dom, and user@.  It obeys the commands for the first target  that  it
       finds.  Target names are interpreted without regard to case.

       All  the  commands for a single target must be listed in a single instruction.  Exception:
       an owner address can be listed in a separate instruction.

RECIPIENT ADDRESSES

       If a command begins with an ampersand, setforward takes the remaining bytes in the command
       as a recipient address:

          boss@yp.to: &god@heaven.af.mil;

       fastforward  sends  each  incoming  mail  message to the recipient address.  The recipient
       address must include a fully qualified domain name.  It cannot be longer than 800 bytes.

       If a recipient address is itself a  target  in  the  forwarding  table,  fastforward  will
       recursively  handle  the  instructions  for  that  target.   Note that @host.dom and user@
       wildcards do not apply here; they apply only to the incoming address.

       If a command begins with a letter or number, setforward takes  the  entire  command  as  a
       recipient address:

          boss@yp.to: god@heaven.af.mil;

OWNER ADDRESSES

       If  a  command  begins  with  a question mark, setforward takes the remaining bytes in the
       command as an owner address:

          sos@heaven.af.mil: ?owner-sos@heaven.af.mil;

       fastforward uses that address as the envelope sender for forwarded mail, so  bounces  will
       go  back  to that address.  (Normally, if a message is forwarded to a bad address, it will
       bounce back to the original envelope sender.)

EXTERNAL MAILING LISTS

       If a command begins with a dot or slash, setforward takes the entire command as  the  name
       of a binary mailing list file created by setmaillist:

          sos@heaven.af.mil: /etc/lists/sos.bin;

       fastforward will read and obey the commands in that file.  The file must be world-readable
       and accessible to fastforward.

PROGRAMS

       If a command begins with a vertical bar or exclamation point, setforward takes the rest of
       the command as the name of a program to run:

          dew@: |dew-monitor;

       For  a  vertical bar, fastforward feeds the message to that program.  An exclamation point
       works the same way except that fastforward inserts $UFLINE, $RPLINE, and $DTLINE in  front
       of the message.

DUPLICATES

       When  fastforward  is  building  the  recipient  list for a message, it keeps track of the
       recipient addresses and external mailing lists it has used.  If the same command shows  up
       again, it skips it.  For example:

          everybody@yp.to: programmers@yp.to, testers@yp.to;
          programmers@yp.to: joe@yp.to, bob@yp.to;
          testers@yp.to: joe@yp.to, fred@yp.to;

       A  message  to everybody@yp.to will be sent to joe@yp.to only once.  (This also means that
       addresses in an internal forwarding loop are discarded.)

       Exception: If a target has an owner address,  commands  for  that  target  are  considered
       different from commands for ``outside'' targets.

SEE ALSO

       newaliases(1), preline(1), printforward(1), setmaillist(1)

                                                                                    setforward(1)