| 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) |