.TH s/qmail: setforward 1
.SH NAME
setforward \- create a forwarding database
.SH SYNOPSIS
.B setforward
.I cdb
.I tmp
.SH DESCRIPTION
.B 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
.BR fastforward .

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

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

The forwarding database format is portable across machines.
.SH "INSTRUCTION FORMAT"
A forwarding instruction contains a
.I target\fR,
a colon, a series of commands, and a semicolon.
Each command is a
.I recipient address\fR,
.I owner address\fR,
.I external mailing list\fR,
or
.I program\fR.
Commands are separated by commas.

For example,

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

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

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

.EX
   # this is a comment
.EE

.B 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.)
.SH "TARGETS"
When
.B fastforward
sees the incoming address
.IR user@host.dom ,
it tries three targets:
.IR user@host.dom ,
.IR @host.dom ,
and
.IR 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.
.SH "RECIPIENT ADDRESSES"
If a command begins with an ampersand,
.B setforward
takes the remaining bytes in the command as a recipient address:

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

.B 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,
.B fastforward
will recursively handle the instructions for that target.
Note that
.I @host.dom
and
.I user@
wildcards do not apply here;
they apply only to the incoming address.

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

.EX
   boss@yp.to: god@heaven.af.mil;
.EE
.SH "OWNER ADDRESSES"
If a command begins with a question mark,
.B setforward
takes the remaining bytes in the command as an owner address:

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

.B 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.)
.SH "EXTERNAL MAILING LISTS"
If a command begins with a dot or slash,
.B setforward
takes the entire command as the name of a binary mailing list file created by
.BR setmaillist :

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

.B fastforward
will read and obey the commands in that file.
The file must be world-readable
and accessible to
.BR fastforward .
.SH "PROGRAMS"
If a command begins with a vertical bar or exclamation point,
.B setforward
takes the rest of the command as the name of a program to run:

.EX
   dew@: |dew-monitor;
.EE

For a vertical bar,
.B fastforward
feeds the message
to that program.
An exclamation point works the same way except that
.B fastforward
inserts
.BR $UFLINE ,
.BR $RPLINE ,
and
.B $DTLINE
in front of the message.
.SH "DUPLICATES"
When
.B 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:

.EX
   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;
.EE

A message to
.B everybody@yp.to
will be sent to
.B 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.
.SH "SEE ALSO"
newaliases(1),
preline(1),
printforward(1),
setmaillist(1)