mdw@git.distorted.org.uk Git - fastforward/blob - setforward.1

   1 .TH setforward 1
   2 .SH NAME
   3 setforward \- create a forwarding database
   4 .SH SYNOPSIS
   5 .B setforward
   6 .I cdb
   7 .I tmp
   8 .SH DESCRIPTION
   9 .B setforward
  10 reads a table of forwarding instructions from its standard input.
  11 It converts the table into a forwarding database.
  12 The forwarding database can be used by
  13 .BR fastforward .
  14
  15 .B setforward
  16 writes the forwarding database to
  17 .IR tmp ;
  18 it then moves
  19 .I tmp
  20 to
  21 .IR cdb .
  22 .I tmp
  23 and
  24 .I cdb
  25 must be on the same filesystem.
  26
  27 If there is a problem creating
  28 .IR tmp ,
  29 .B setforward
  30 complains and leaves
  31 .I cdb
  32 alone.
  33
  34 The forwarding database format is portable across machines.
  35 .SH "INSTRUCTION FORMAT"
  36 A forwarding instruction contains a
  37 .I target\fR,
  38 a colon, a series of commands, and a semicolon.
  39 Each command is a
  40 .I recipient address\fR,
  41 .I owner address\fR,
  42 .I external mailing list\fR,
  43 or
  44 .I program\fR.
  45 Commands are separated by commas.
  46
  47 For example,
  48
  49 .EX
  50    root@yp.to: god@heaven.af.mil, staff@af.mil;
  51 .EE
  52
  53 says that mail for
  54 .B root@yp.to
  55 should be forwarded to the recipient addresses
  56 .B god@heaven.af.mil
  57 and
  58 .BR staff@af.mil .
  59
  60 When
  61 .B setforward
  62 sees # it ignores all text from # to the end of the line:
  63
  64 .EX
  65    # this is a comment
  66 .EE
  67
  68 .B setforward
  69 ignores all other line endings,
  70 so you can split a forwarding instruction across lines.
  71 It also ignores spaces and tabs.
  72 Exception:
  73 you can put a space (or tab or comma or whatever)
  74 into a target or command by putting a backslash in front of it.
  75 (However, NUL bytes are not permitted anywhere.)
  76 .SH "TARGETS"
  77 When
  78 .B fastforward
  79 sees the incoming address
  80 .IR user@host.dom ,
  81 it tries three targets:
  82 .IR user@host.dom ,
  83 .IR @host.dom ,
  84 and
  85 .IR user@ .
  86 It obeys the commands for the first target that it finds.
  87 Target names are interpreted without regard to case.
  88
  89 All the commands for a single target must be listed in a single instruction.
  90 Exception: an owner address can be listed in a separate instruction.
  91 .SH "RECIPIENT ADDRESSES"
  92 If a command begins with an ampersand,
  93 .B setforward
  94 takes the remaining bytes in the command as a recipient address:
  95
  96 .EX
  97    boss@yp.to: &god@heaven.af.mil;
  98 .EE
  99
 100 .B fastforward
 101 sends each incoming mail message
 102 to the recipient address.
 103 The recipient address must include a fully qualified domain name.
 104 It cannot be longer than 800 bytes.
 105
 106 If a recipient address is itself a target in the forwarding table,
 107 .B fastforward
 108 will recursively handle the instructions for that target.
 109 Note that
 110 .I @host.dom
 111 and
 112 .I user@
 113 wildcards do not apply here;
 114 they apply only to the incoming address.
 115
 116 If a command begins with a letter or number,
 117 .B setforward
 118 takes the entire command as a recipient address:
 119
 120 .EX
 121    boss@yp.to: god@heaven.af.mil;
 122 .EE
 123 .SH "OWNER ADDRESSES"
 124 If a command begins with a question mark,
 125 .B setforward
 126 takes the remaining bytes in the command as an owner address:
 127
 128 .EX
 129    sos@heaven.af.mil: ?owner-sos@heaven.af.mil;
 130 .EE
 131
 132 .B fastforward
 133 uses that address as the envelope sender for forwarded mail,
 134 so bounces will go back to that address.
 135 (Normally, if a message is forwarded to a bad address,
 136 it will bounce back to the original envelope sender.)
 137 .SH "EXTERNAL MAILING LISTS"
 138 If a command begins with a dot or slash,
 139 .B setforward
 140 takes the entire command as the name of a binary mailing list file created by
 141 .BR setmaillist :
 142
 143 .EX
 144    sos@heaven.af.mil: /etc/lists/sos.bin;
 145 .EE
 146
 147 .B fastforward
 148 will read and obey the commands in that file.
 149 The file must be world-readable
 150 and accessible to
 151 .BR fastforward .
 152 .SH "PROGRAMS"
 153 If a command begins with a vertical bar or exclamation point,
 154 .B setforward
 155 takes the rest of the command as the name of a program to run:
 156
 157 .EX
 158    dew@: |dew-monitor;
 159 .EE
 160
 161 For a vertical bar,
 162 .B fastforward
 163 feeds the message
 164 to that program.
 165 An exclamation point works the same way except that
 166 .B fastforward
 167 inserts
 168 .BR $UFLINE ,
 169 .BR $RPLINE ,
 170 and
 171 .B $DTLINE
 172 in front of the message.
 173 .SH "DUPLICATES"
 174 When
 175 .B fastforward
 176 is building the recipient list for a message,
 177 it keeps track of the recipient addresses and external mailing lists
 178 it has used.
 179 If the same command shows up again, it skips it.
 180 For example:
 181
 182 .EX
 183    everybody@yp.to: programmers@yp.to, testers@yp.to;
 184    programmers@yp.to: joe@yp.to, bob@yp.to;
 185    testers@yp.to: joe@yp.to, fred@yp.to;
 186 .EE
 187
 188 A message to
 189 .B everybody@yp.to
 190 will be sent to
 191 .B joe@yp.to
 192 only once.
 193 (This also means that addresses in an internal forwarding loop
 194 are discarded.)
 195
 196 Exception:
 197 If a target has an owner address,
 198 commands for that target are considered different
 199 from commands for ``outside'' targets.
 200 .SH "SEE ALSO"
 201 newaliases(1),
 202 preline(1),
 203 printforward(1),
 204 setmaillist(1)