NOS mail docs -- G4AMJ/NQ0I and SM0RGV (Rev. 3) 1. Introduction This section of the NOS docs deals with the intricacies of mail forwarding. You should read and understand this documentation thoroughly before attempting to forward mail through your NOS box to the AX.25 BBS world, otherwise you might grossly misconfigure your system and be the unhappy recipient of flames from BBS sysops. This section does NOT deal with the minutae of the mailbox and its various commands; it assumes that you understand concepts such as user areas (both public and private) and how to list and send mail. If you need help with these, please look elsewhere in the NOS docs. Apart from the usual domain.txt and other files necessary for ordinary functionality of NOS, three files are important in the mail forwarding process. These are : /spool/forward.bbs, /alias and /spool/rewrite. The contents of these will now be addressed individually. 2. /spool/forward.bbs This file describes the actions taken by NOS in forwarding to AX.25 BBSes. The file contains a series of forwarding records, each record being separated by a line containing two or more hyphens. The template for a forwarding record is: BBS callsign Connection route Connection commands List of areas to be forwarded ------------ 2.1. BBS callsign This is simply the ordinary call of the remote BBS. A typical (but not random!) entry might be simply the line: sm0rgv The callsign may be followed, on the same line, by a comma separated list of valid intervals when forwarding is to take place. Each valid interval is a four digit number: the first two digits are the beginning hour of the valid interval, the - 2 - last two digits are the final hour of the valid interval. For example, if the first line of a forwarding record looks like: sm0rgv 0006,1414 then forwarding to sm0rgv will take place only during hours numbered 00, 01, 02, 03, 04, 05, 06 and 14. Ticks of the mbox timer outside of these times will not cause mail to be forwarded to sm0rgv. The default interval for forwarding is 0023. 2.2. Connection route This is the method by which communication is to be established with the remote BBS. The first token on the line is the type of protocol to be used. This is one of ax25, netrom or tcp. Following this is whatever further information the chosen protocol requires to make the connection. An example connection route for a simple ax25 connection on interface ax0 is: ax25 ax0 g3dlh 2.3. Connection commands Connection commands may, optionally, follow the connection route. These take the form of a full stop (period), followed by the command which will be transmitted once the connection defined in the first line of the connection route is established. For example, suppose that we wish to establish a netrom connection with sm0rgv-2, through the netrom node #sth67. Then the connection route and connection command portion of the record would look like: netrom #sth67 .c sm0rgv-2 [ Please note that the full stop would be placed at the beginning of the line; I have placed it here indented by one column simply so that gateways which handle this message do not complain at having a line beginning with a full stop; this convention is followed throughout this documentation] If the station is reached through digipeating, then the digipeater callsigns should be in the ax25 route to the destination callsign. That is, if you wish to forward traffic to w0ljf, using k2na as a digipeater, then you - 3 - should have the line: ax25 route add w0ljf k2na in your autoexec file. 2.4. List of areas to be forwarded This is a list, one per line, of entries in the /spool/mail directory which will be forwarded to the remote BBS. An entry of the form: callsign will cause the file /spool/mail/callsign.txt to be scanned for unread messages. Any such messages are sent to the remote BBS and deleted from the file. One can also forward user areas using this mechanism. To do this, simply place a line containing the name of the area in the record. So, to forward amsat bulletins to the BBS, one would have a line: amsat This will search the /spool/mail/amsat.txt file; any messages contained therein which have not been forwarded to the BBS in question will be forwarded. They will NOT be deleted. The determining factor as to whether or not entries are deleted is that if the filename is present in the /spool/areas file, then there is NO deletion, otherwise there is. Please note that ONLY FILES IN /spool/mail are checked. In particular, the outbound SMTP mail queue is NOT checked. 2.5. Changing the recipient address Normally, NOS uses the information in the To: header line to determine the parameters used by the "S" command during BBS forwarding. As the To: header is unchanged by all /alias and /spool/rewrite machinations, the mail will be sent to the BBS addressed precisely as the originator of the message typed it. Occasionally, one might want to change this behaviour. In this case, a line of the form: area newaddress in the list of areas to be forwarded will replace the originally typed destination with the string newaddress - 4 - instead. 3. /alias The alias file is used to map LOCAL names to other names, which may be either local or remote; additionally, from a single input message, the alias file permits one to produce multiple output messages. Thus, typical uses for the /alias file are: converting one local name to another, converting a local name to a remote name, and exploding a mail message so that it is passed on to several recipients. The format of a record in the alias file is very simple: aliasname recipient1 recipient2 recipient3 or recipient4 ... recipientN There is no separation between records in the /alias file other than a newline. The aliasname is a local username; that is, it does not contain an "@" symbol. When the alias file is processed, if the destination of the message matches precisely the aliasname, then the mail is redirected to ALL of the alieased recipients. Scanning of the /alias file is performed by the SMTP server. The SMTP timer (which controls the SMTP client) is kicked whenever the mailbox or SMTP server queues something for delivery by SMTP. Mail transport within a single NOS system is performed through the SMTP client/server mechanism. The result of these facts is that as soon as a piece of mail is entered to the mailbox, the SMTP client is kicked and attempts to deliver the mail (which has already been scanned by the rewrite mechanism - see below). If the mail is local to the NOS system (i.e. no "@" sign in the address), then the /alias file will be scanned and the name mappings take place. A few lines in the /alias file might look something like: bdale bdale@n3eua local fred@k0yum bdale@n3eua bill@ai0c.co.usa.na n5op@n5op jim@k0jtz n0esg@n0esg g4bki g4bki@gb7bil.2712.gbr.eu The system must know how to deliver traffic to each of the individual addresses in the style in which they are entered in the /alias file. If the system does not know how to deliver one of the new addresses, then it will send it to - 5 - the SMTP gateway station defined by the 'smtp gateway' command. Note that it is reasonable, and sometimes desireable, to have alias records of the form: area area dest1 dest2 ... As the /alias file is scanned only once (see below), this does not result in an infinite recursion. 4. /spool/rewrite The rewrite file is used to perform a one-to-one mapping between destination addresses as received by NOS and destination addresses as actually used by NOS. Each record within the rewrite file comprises a single line, containing either two or three entries separated by spaces. The first field is the template field; if a destination address matches the template, it is replaced by the second field. The third field, which is optional, is the single letter "r", which, if present, tells NOS to rescan the rewrite file, using the new destination address to attempt to match against the templates. A template may contain asterisks. These stand for a match of any number of characters (including zero). In the second field, the character "$", followed by a single digit in the range 1 to 9, represents the string that matched the respective asterisk in the template. By way of example, suppose that there is a line in the rewrite file which looks like: *@* $1%$2@g1emm.ampr.org Then, any traffic reaching the system through the mailbox or the SMTP server, but which is supposed to go to a remote system, will be redirected to go through g1emm.ampr.org. Suppose that a user logs on, and sends a message to n0gbe@nq0i. Then the rewrite file attempts to match "n0gbe@nq0i" against the entry *@*. It matches, and assignes $1 the value n0gbe, and $2 the value nq0i. The mail file as written to the disk will no longer be to n0gbe@nq0i, but, rather, to n0gbe%nq0i@g1emm.ampr.org. [The nomenclature station1%station2@station3 means the final destination is station1@station2, and this traffic is to be routed through the gateway station3.] As soon as a template match is found, the conversion is performed and scanning is stopped, unless the third "r" field is present, in which case scanning restarts from the top of the file. - 6 - N.B. It is a good idea to have a line of the form: *@*.ampr.org $1@$2.ampr.org at the beginning of your rewrite file. This will cause all amprnet traffic to be caught early in the rewrite scan, and no further scanning (and, hence, no unexpected substitutions) will take place. 5. Scanning procedure The two files which are used to determine the disposition of traffic are scanned under slightly different circumstances. Note that neither the /alias nor the /spool/rewrite scan makes any actual changes to the contents of the traffic. In particular, the To: field remains exactly as it was first entered into the system. There are four possible entry routes for traffic into the system: SMTP, through the mailbox by a user, through the mailbox by a BBS, and via an external program (like BM) or creation of the files manually. NOS determines if a piece of traffic was entered into the system by a BBS by looking for a BBS system ID (like the "[NET-H$]" block issued by NOS) on the incoming connection prior to messages being uploaded. 5.1. Traffic received by SMTP server 1. The rewrite file is scanned and any changes applied (unless the traffic was recieved through the local mailbox; in that case, this step does not occur); 2. If the traffic appears to be local then the alias file is scanned and any changes or explosions applied. 3. Any copies local to the system are delivered; copies for remote delivery are placed in the SMTP queue. 5.2. Traffic received by mailbox from user 1. The rewrite file is scanned and any changes applied; 2. The traffic is passed to the SMTP client. 5.3. Traffic received by mailbox from BBS 1. The rewrite file is scanned and any changes applied; 2. The traffic is passed to the SMTP client. - 7 - 5.4. Traffic entered by external mechanism 1. No scanning occurs; 2. The traffic is passed to the SMTP client. 6. Headers Appropriate RFC-822 headers are added to all incoming traffic. Traffic entering through the mailbox recieves a full complement of RFC-822 headers; traffic coming through the SMTP server has only a "Received:" header applied. On forwarding to a BBS, if an item of traffic contains BBS R: headers, the RFC-822 header is converted to an appropriate R: line at the time that NOS forwards the message. (This change only occurs for BBS forwarding; forwarding by SMTP retains the RFC-822 headers.) 7. Bulletin Identifiers (BIDs) The AX.25 BBS system has evolved a reasonably efficient way of reducing overhead when forwarding bulletins. When a bulletin is originated on a BBS, it is given a unique bulletin identifier (BID). This BID should (theoretically) travel with the bulletin, and should never be changed during the distribution of the bulletin. Each system keeps track of all received BIDs. If a forwarding station wishes to forward a bulletin to a BBS, then the receiving station checks its local list of known BIDs and informs the transmitting station if it already posesses the bulletin in question. The NOS mailbox conforms to this protocol. Received BIDs are stored in the file /spool/history, and are encoded in the Message-ID: header line of the message by NOS. Messages forwarded from areas listed in the /areas file will have their BID (re)generated from the Message-ID: line. Note that ALL messages from public areas are forwarded with a BID, whether or not the message was produced with the "SB" command. Like other BBSes, NOS will inform a transmitting station not to transmit a bulletin if it is one that NOS already has locally; likewise, it understands similar messages from other stations to which it tries to forward. Note that the BID mechanism is not a part of the SMTP world. If you are forwarding bulletins through SMTP, there is no mechanism by which the receiving station can reject the attempted delivery of a bulletin, even if it already exists on the recipient system. (Note that a possible workaround is to deliver bulletins to TCP/IP stations using TCP instead of SMTP. Alternatively, one could use NNTP, as NNTP commands - 8 - utilise the Message-ID: line, from which the BID is derived.) The BID is preserved no matter which mechanism is used to deliver the bulletin. 8. Traffic in practice Now, the big question is, how does one set up these various files to perform intelligent manipulation of mail? A number of examples follow. Note that, often, there is more than one way to accomplish an objective. The following are merely examples (and not necessarily the most efficient method possible for any given case). The format used will be: typed destination -> intended destination followed by the necessary entries in the alias (/alias), rewrite (/spool/rewrite) and forwarding (/spool/forward.bbs) files. 8.1. Using familiar names - SMTP destination bdale -> bdale@n3eua.ampr.org alias: bdale bdale@n3eua.ampr.org rewrite: forward: 8.2. Exploding local mail sysops -> nq0i, n5op@n5op.ampr.org alias: sysops nq0i n5op@n5op@ampr.org rewrite: forward: 8.3. Using familiar names - BBS forwarding g4bki -> g4bki@gb7bil.2712.gbr.eu, to be forwarded by ai0c alias: rewrite: forward: - 9 - ai0c ax25 ax1 ai0c g4bki g4bki@gb7bil.2712.gbr.eu ai0c 8.4. Handling incoming bulletins by subject tcpip@* -> nq0i, tcpip, bdale@n3eua.ampr.org, ai0c@ai0c [a BBS] alias: tcpip nq0i tcpip bdale@n3eua.ampr.org ai0c rewrite: tcpip@* tcpip forward: ai0c ax25 ai0c ai0c Let's walk through the above example. An incoming item comes in addressed to TCPIP@ALLUS. A scan is made through the rewrite file, and a match is found. The item is redirected to tcpip. The alias file is scanned; a total of four copies of the item exist after this, three in local areas tcpip, nq0i and ai0c, and one on the SMTP queue (for bdale@n3eua.ampr.org). When the mailbox timer next ticks, the mail in the local ai0c area will be forwarded on the ax1 interface to ai0c. 8.5. Routing based on Hierarchical addressing Wyoming -> KE7VS (SMTP) Nebraska -> AG0N (BBS over the NETROM, NETROM ID WNBBS) Europe -> W0LJF (BBS over AX.25) alias: rewrite: *.noam $1.na r *.us $1.usa.na r *.usa $1.usa.na r *.ne $1.ne.usa.na r *.wy $1.wy.usa.na r *@*.*.wy.usa.na $1%$2.$3.wy.usa.na@ke7vs *@*.wy.usa.na $1%$2.wy.usa.na@ke7vs *.ne.usa.na ag0n - 10 - *.eu w0ljf forward: ag0n netrom ax0 wnbbs ag0n ---------- w0ljf ax25 ax1 w0ljf w0ljf ---------- Why is the example rewrite file apparently so complicated? This is to handle poorly constructed hierarchical addresses in a reasonable way. A full U.S. hierarchical address has the form: callsign@BBS.#localid.state.usa.na. Many states have no #localid field. In the example rewrite file above, the first three lines convert non-standard, but frequently used, U.S. designators to the more standard format. It is common for users not to use a full hierarchical address if the destination is relatively local. For eample, a user might easily use only .wy instead of the full .wy.usa.na if he is geographically close to Wyoming. The second grouping of two lines handles this problem. Note the third, "r", field in all the entries so far. The remainder of the file handles properly formatted hierarchical addresses. The two Wyoming entries handle the cases with and without a #localid field. Differentiation between these cases is not necessary for BBS forwarding. 8.6. General bulletin handling The details of bulletin handling will vary somewhat from place to place, as there are several distinct styles of bulletin handling currently in use in the AX.25 BBS world. In general, it is necessary to arrange one's system so that it accepts bulletins from BBSes, forwards them to one or more stations, and also handles intelligently bulletins input by users into NOS. Suppose that we sish to handle bulletins @JUNK. We are to deposit them locally in the junk area, and also forward to BBS g4bki. We also know that we generally receive @JUNK bulletins from g4amj, a local BBS which handles much bulletin traffic. alias: rewrite: *@junk junk - 11 - forward: g4bki ax25 ax1 g4bki g4bki junk ---------- g4amj ax25 ax1 g4amj g4amj junk ---------- All incoming @JUNK traffic is written to the junk area (which should be an explicit entry in the /spool/areas file). Each tick of the mailbox timer, NOS scans the junk area for traffic not forwarded to g4bki or g4amj and attempts to deliver unforwarded bulletins. Usually, g4amj will respond with a "Have it" message and the bulletin will not be forwarded. Any bulletins @JUNK deposited locally by users will automatically be sent to both g4bki and g4amj. 9. Questions and Answers Q. Under what circumstances does NOS request reverse forwarding from a BBS? A. NOS requests a reverse forward after completing any forwards of its own to the BBS. If no traffic was queued for a given BBS, then no connection is attempted, so no reverse forward request is issued. Q. What kinds of message types does the NOS mbox support? A. Basically, NOS supports all two letter commands starting with an "S". If the mailbox has not received an SID banner (the "[NET-H$]") from a connected station, then an SF command will send a followup to the address specified on the command line. The SR command will send a reply to the current message. One can also issue the command "SR ", where is the number of the message to which you want to generate a reply. All other variations cause an X-BBS-Msg-Type: header to be added to the message. When a message with such a line is forwarded to a BBS, it is sent to the BBS with the appropriate message type as the second letter in the "S" command to the BBS. If NOS has received a valid SID, then ALL S commands are handled by the X-BBS-Msg-Type: mechanism outlined above. - 12 - 10. Logic map of the mailbox ============== AX.25 === NET/ROM === Ethernet === Loopback ================= | | | | | | | | +--------------+ +--------------+ +--------------+ +--------------+ | | | | | | | | | Mailbox | | SMTP client | | SMTP server | | BBS Forward | | | | | | | | | +--------------+ +--------------+ +--------------+ +--------------+ | ^ | ^ | | | | v | v | +--------------+ +--------------+ +--------------+ +--------------+ | | | | | | | | | Add RFC822 | | Use MX or A | | Add Received | | Add own R: | | header suite | | type records | | line | +>| line | | | | | | | | | | +--------------+ +--------------+ +--------------+ | +--------------+ | ^ | | ^ | | | | | v | v | | +--------------+ +--------------+ +--------------+ | +--------------+ | | | | | | | | | | Get Rewrite | | Use optional | | Apply Rewrite| | | Strip RFC822 | | file address | | SMTP gateway | | file address | | | header suite | | | | | | | | | | +--------------+ +--------------+ +--------------+ | +--------------+ | ^ | | ^ | | | | | Yes v | v | | +--------------+ | +--------------+ | +--------------+ | | No | | | | | | | Local addr? |-------+ | | Alias file | +-| Any R: lines?| | | | | | | No | | +--------------+ | | +--------------+ +--------------+ | | | | | | ^ | Yes | | | | | | v | | v v v | +--------------+ v | +--------------+ +--------------+ | | +--------------+ | | | | | Apply Rewrite| | | No | Local |Yes | /spool/mail/ | | file address |--->| SMTP queue |<---| address? |--->| directory | | | | | | | | | +--------------+ +--------------+ +--------------+ +--------------+