JNOS Commands Manual - Appendix C
Jump Table/Index
Appendix C
APPENDIX C
FORWARD.BBS
NOS mail docs -- G4AMJ/NQ0I and SM0RGV (Rev. 3)
Mail Forwarding
Slight mods for JNOS 1.11 by N5KNX (Rev. 3a).
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 minutiae 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 time-specs poll-flag
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
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. If you desire to force a connect to occur, even if
we have no traffic to transfer, then use the poll flag, P,
in addition to any time specs.
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, perhaps a digipeater route. An example connection
route for a simple ax25 connection on interface ax0 is:
ax25 ax0 g3dlh
A more complex one is:
ax25 ax0 g3dlh via k5arh uv-3 kb5ogn-1
JNOS can forward to an export file. To specify forwarding to a file,
use this syntax in the connect-line:
file
2.3. Connection commands
Connection commands may, optionally, follow the connection
route. These take the form of a single character command
followed by suitable argument strings. Supported commands
are:
.text text (with CR suffix) is sent to remote.
any search string is reset.
! eschew FBB compression
+text establish a search string.
@NN read a line with timeout of NN secs,
and fail unless it contains the search
text established with the + command.
* NN read and discard lines until a line matching desired
string is encountered or until NN secs has elapsed.
#comment_text comment text is ignored
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]
Another example, this time we use ax.25 protocol to connect to
a netrom node, k7uyx-1, and then connect to another netrom node:
ax25 ax0 k7uyx-1 <- initial connection to netrom node
.c rlimb <- ask for a netrom connect from this node
+Connected <- if we don't get this, things went wrong
@60 <- maximum one minute wait !
If the station is reached through digipeating, then the
digipeater callsigns should either be specified in the
connect line (described above) or be in the ax25 route to the
destination callsign. That is, if you wish to forward
traffic to w0ljf, implicitly using k2na as a digipeater, then
you 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. Occasionally, one might want to change this
behavior. 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
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
aliased 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.ampr.org
n5op@n5op jim@k0jtz n0esg@n0esg
g4bki g4bki@gb7bil.ampr.org
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
the SMTP gateway station defined by the 'smtp gateway'
command.
Note that it is reasonable, and sometimes desirable, 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 assigns
$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.
Note: 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, with one exception: if the message is
to be stored into a local area, and if the To: field ends
with @our_hostname, then this suffix is removed, and any
rightmost % symbol is changed to an @ symbol, to facilitate
forwarding to ax.25 networks.
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 "[JNOS-IHM$]" 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 received 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.
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 receives 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 possesses 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
certain mechanism by which the receiving station can reject the
attempted delivery of a bulletin, even if it already exists
on the recipient system. JNOS will generate a bid that will
match the bids that other JNOS systems generate from the same
message, but this convention is not universally followed.
(Note that another possible workaround is to deliver bulletins
to TCP/IP stations using TCP instead of SMTP. Alternatively,
one could use NNTP, as NNTP commands utilize 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:
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 ax1 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.wy.usa.na@ke7vs
*.ne.usa.na ag0n
*.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 example, 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.
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 wish 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
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, UNLESS the P (poll) flag is in
a forward.bbs time-spec field. Reverse forwarding can be
forced by specifying the BBS callsign in upper case, i.e.,
mb kick N5KNX
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 "[NOS-H$]") from a connected station, then an SF
command will forward the current message 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.
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 |
+--------------+ +-------------+ +------------+ +-------------+
| Apply Rewrite| | | No| Local |Yes | /spool/mail/|
| file address |--->| SMTP queue |<--| address? |---->| directory |
| | | | | | | |
+--------------+ +-------------+ +------------+ +-------------+
End of Appendix C
(Courtesy KBNorton Computer Services)