BBS Interface Specification
Working Draft
11/28/93
Introduction
Section 1 - Establishing connection
Section 2 - Forwarding
Section 3 - Reverse forwarding
Section 4 - Forwarding to old BBSs
Section 5 - Error Conditions
Section 6 - BNF Summary
Section 7 - Feature Letter Use
Current mailing list
BBS_authors@arasmith.com
bob@arasmith.com (Bob Arasmith, N0ARY)
hank_oredson@mentorg.com (Hank Oredson, W0RLI)
wd6cmu@netcom.com (Eric Williams, WD6CMU)
enge@almaden.ibm.com (Roy Engehausen, AA4RE)
71151.720@CompuServe.COM (Victor Poor, W5SMM)
blloyd@axion.bt.co.uk (Brian Lloyd, G1NNA)
map@hopper.cba.csuohio.edu (Mike Pechura, WA8BXN)
durham@w2xo.pgh.pa.us (James Durham, W2XO)
johan@ece.orst.edu (Johannes Reinalda, WG7J)
trentin@enac.dgac.fr (to J-P Roubelat, F6FBB)
sproul@sproul.com (Mark Sproul, KB2ICI)
mike@km6px.arasmith.com (Mike Stickney, KM6PX)
70007.1365@compuserve.com (Ed Juge, W5TOO)
73126.3260@compuserve.com (Craig McCartney, WA8DRZ)
bbr77@aol.com (Brian Riley, KA2BQE)
Via US Mail
Michael Jaggers, WB4TTZ
1377 Columbia Ave, Franklin, TN 37064
Introduction -
This document is meant to define the interaction between two BBSs
exchanging messages. It is not the goal of the document to specify
the interface of the future but merely represent what a BBS can be
expected to see at the current time.
It is hoped that this specification will be followed by another that
defines the base rules for all BBS programs to adopt. This should
eliminate the current problems with incompatibilities and overloaded
operators. If you create a BBS to this specification you should be
able to interconnect with virtually any BBS currently in use. Any
extensions you add will put you at risk, the subsequent spec is to
identify these areas.
In brief the following sequence of events takes place when the BBSs
connect for forwarding:
Master System Slave System
------------ --------------
{Connect}
[SID]
N9ZZZ >
[SID]
>
SB ARES @ ALLCA < W7ZZZ $ARES0108
OK
message subject
message routing headers
message body
Control-Z
>
SB WANT @ ALLUS < W8AAA $1029_N0XYZ
NO
>
F>
SP WA2ABC @ N2AAA < N9AAA
OK
message subject
message routing headers
message body
Control-Z
F>
{Disconnect}
This represents a simple example of connecting, establishing a common
protocol, forwarding and reverse forwarding. This document will look
more closely at each of these phases.
In the text the BBS initiating the connect will be referred to as the
MASTER and the remote BBS will be referred to as the SLAVE.
Each command and exchange will be presented in BNF (Backus-Naur Form)
which is a context-free grammar widely used to describe computer
language syntax.
All commands and fields are case insensitive.
Meta-syntactic information
[x] = Optional: zero or one x
(x y) = Grouping: treat multiple tokens as a single token
<> = Set
Characters:
NUL = <0x00>
CNTRL_C = <0x03>
TAB = <0x09>
CR = <0x0D>
LF = <0x0A>
CNTRL_Z = <0x1A>
SP = <0x20>
Character sets:
ALPHA = <'A'-'Z'>
DIGIT = <'0'-'9'>
ALNUM = ALPHA | DIGIT
ASCII = <0x20-0x7F>
SPACE = SP | TAB
8BIT = <0x01 - 0xff, except CR, LF, CTRL_Z>
Character sequences:
EOL = CR | CR LF
NUMBER = DIGIT | NUMBER DIGIT
WHITE = SPACE | WHITE SPACE
ASCII_STR = ASCII | ASCII_STR ASCII
ALNUM_STR = ALNUM | ALNUM_STR ALNUM
8BIT_STR = 8BIT | 8BIT_STR 8BIT
Throughout this document we will present a verbose translation of the
grammar highlighting any points that may not be obvious but could
have significant affect. There will also be examples illustrating what
can actually be expected.
Section 1 - Establishing connection
When connecting to a BBS the first line the BBS sends must be the
SID (System IDentifier). The SID is used to determine what features
are supported by BBS. The existence of the SID implies that the system
supports reverse forwarding and OK/NO message rejection. There still
exist old BBS codes which do not present a SID at connect. Refer to
Section 4 for information on forwarding to these old style BBS sytems.
SID sent by both MASTER and SLAVE
AUTHOR_ID = <ASCII_STR, except '[', ']' and '-'>
AUTHOR_DATA = <ASCII_STR, except '[' and ']'>
FEATURE = ALPHA [DIGIT]
FEATURE_LIST = FEATURE | FEATURE_LIST FEATURE
SID = "[" AUTHOR_ID "-" [AUTHOR_DATA "-"] FEATURE_LIST [$]"]" EOL
The AUTHOR_ID and FEATURE_SET must be present. If the optional
AUTHOR_DATA is present it must be separated from the other two
fields by a '-'. AUTHOR_DATA may contain the '-' character.
The AUTHOR_ID and AUTHOR_DATA are typically a portion of the authors
callsign or BBS name and version number, respectively.
Each FEATURE consists of a letter, denoting the feature and an
optional number, denoting the feature level. The absence of a
version number implies version zero.
If BID's are supported, '$' must be the last symbol in the FEATURE_SET.
The recommended minimal support is BID and Hierarchical location
identifiers. These are necessary for the proper operation of the network.
EXAMPLE
[ZFJ-2.3-H$]
The original prompt received from the SLAVE BBS may contain additional
information intended for users. As soon as the SID is received by the
SLAVE BBS it should respond with an abbreviated PROMPT, with the
ASCII_STR field being empty.
Section 2 - Forwarding
A message can either be rejected or accepted by the SLAVE. There are
many reasons that the SLAVE my choose to reject a message but the most
common will be duplicate bid, indicating the SLAVE already has the message.
Here is an overview of the exchange.
ACCEPT EXCHANGE:
MASTER SLAVE
------ -----
PROMPT
SEND_CMD
RESPONSE (OK)
MESSAGE
COMMENT
PROMPT
REJECT EXCHANGE:
MASTER SLAVE
------ -----
PROMPT
SEND_CMD
RESPONSE (NO)
PROMPT
The SLAVE indicates it's prepared to accept a command by issuing a PROMPT.
The PROMPT is also used as an an acknowledgement that the last message
has be received.
The MASTER initiates the message exchange by issuing a a SEND_CMD. This
command contains all the information necessary for the SLAVE to decide
whether to ACCE or REJECT the message. It contains message type,
destination, originator and possibly a bid.
COMMENT = <ASCII_STR, except '>'>
PROMPT = [COMMENT] ">" EOL
TYPE = 'B' | 'P' | 'T'
CALLSIGN = <ASCII_STR, except '@', '.', max length 6>
LOC = <ASCII_STR, except '@', '.', max length 6>
HLOC = LOC | <HLOC "." LOC, max length 31>
BBS = CALLSIGN ["." HLOC]
TO = CALLSIGN [WHITE "@" WHITE BBS]
FROM = CALLSIGN
BID = <ASCII_STR, max length 12>
SEND_CMD = "S" TYPE WHITE TO [WHITE "<" WHITE FROM] [WHITE "$" BID]
HLOC is the hierarchical location of the system. It is defined by
the document "INTERNATIONAL ROUTING DESIGNATORS", ARRL Networking
Conference Proceedings xxx.
The TO field commonly takes the following forms:
callsign @ BBS.hloc ; N6ZFJ @ N6QMY.CA.USA.NA
category @ distrib ; WANT @ ALLCA
category @ BBS.hloc ; WANT @ N6QMY.CA.USA.NA
category @ distib.hloc ; INFO @ ALLCA.CA.USA.NA
The first two are seen most often, but the other two forms are seen.
The first two forms are also normally associated with the
message type of PERSONAL and BULLETIN respectively.
White space is required on either side of the '@' and between the
'<' and the senders callsign. There cannot be white space between
the '$' and the BID.
EXAMPLE
SB WANT @ ALLSCV < N6ZFJ $2345_N6QMY
A "BID" (Bulletin IDentifier) is associated with each Bulletin,
and may be associated with any Personal message.
If a BID is not given explicitly when the message is entered into
the system, and the message type requires a BID, one is created
automatically from the message number and callsign of the system
into which the message was initially entered.
NOTE:
It is suggested that a generated BID have the form nnn_BBS,
where nnn is the message number at the originating BBS system,
and BBS is the callsign of the originating BBS system.
COMMON_BID = MSG_NUM "_" CALLSIGN
BBS codes are free to create whatever form they wish as long as the
length doesn't exceed 12 characters.
Messages to a distribution, whether they are bulletins or personal
messages, must have a BID. Personal messages to a specific user may
carry a BID if the user supplied one, but will not be given a default
BID. NTS message never carry a BID.
The SLAVE BBS determines from the SEND_CMD whether or not to accept
the message. The reasons for rejection is usually that the message
already exists on the SLAVE system (i.e. a duplicate BID), or possibly
a system related problem.
Sent by SLAVE in response to SEND_CMD (or by MASTER if in reverse
forward mode).
RESPONSE = ACCEPT | REJECT
ACCEPT = "OK" [ WHITE COMMENT ] EOL
REJECT = "N" [ "O" ] [ WHITE COMMENT ] EOL
NOTE:
The syntax of responses has grown in a random fashion. Many BBS programs
expect to see the entire words "OK" and "NO" while others simply look
at the first letter. It is suggested that new BBS codes should present the
words "NO" and "OK", but look for only the first letter. Doing so should
ensure compatibility with existing BBS codes.
EXAMPLE
Master: SB WANT @ ALLCAN < N6ZFJ $4567_N0ARY
Slave: NO duplicate bid
Slave: >
Master: SB WANT @ ALLCAN < N6ZFJ $4567_N0ARY
Slave: OK #32190
Master: message body
Master: Control-Z
Slave: Message being held for sysop review
Slave: >
It is required that the "OK" and "NO" strings be followed by white
space or EOL. Some BBS programs will fail to recognize them otherwise.
EXAMPLE
Master: SB WANT @ ALLCAN < N6ZFJ $4567_N0ARY
Slave: NO, already have it
Slave: >
This would fail with some existing BBS codes due to
the comma following the "NO" string.
If the SLAVE BBS responds with a REJECT condition the message should
not be sent and the MASTER should ignore any response from the SLAVE
until PROMPT is encountered. The MASTER can then submit a new SEND_CMD,
initiate reverse forwarding or disconnect.
Once the SLAVE has issued the ACCEPT response, the MASTER BBS
should immediately send the message subject, routing headers,
message body and EOMA. The SLAVE will acknowledge with PROMPT
once it receives an EOMA.
Message Routing Header
SUBJECT = <ASCII_STR, max length 79> EOL
YEAR = DIGIT DIGIT
MONTH = DIGIT DIGIT
DAY = DIGIT DIGIT
HOUR = DIGIT DIGIT
MINUTE = DIGIT DIGIT
STAMP = "R:" YEAR MONTH DAY "/" HOUR MINUTE ["Z"]
MSG_NUM = <NUMBER, range 1 - 65535 (0xFFFF)>
HEADER1 = STAMP WHITE MSG_NUM "@" BBS EOL
HEADER2 = STAMP WHITE "@:" BBS WHITE [ASCII_STR] "#:" MSG_NUM [ASCII_STR]
HEADER = HEADER1 | HEADER2
Message structure
HEADERS = HEADER | HEADERS HEADER
EOMA = CNTRL_Z EOL
EOMB = EOL "/EX" EOL
BODY = 8BIT_STR | BODY EOL 8BIT_STR
MESSAGE = SUBJECT [HEADERS] EOL [BODY] (EOMA | EOMB)
EXAMPLE
Example message
R:930108/1729 @:N6QMY.#NOCAL.CA.USA.NA Fremont #:1114 Z:94536
R:930108/1259 1530@KA6FUB.#NOCAL.CA.USA.NA
R:930107/1638z @:WD6CMU.#NOCAL.CA.USA.NA "OSKbox" #:10576 Z:94805
R:930107/1045 50724@WX3K.#NOCAL.CA.USA.NA
message body will go here, the blank line above separates the
body from the routing headers. When the body is through it should be
terminated as follows:
^Z
NOTE:
Both forms of the header described above are seen, and should be parsed.
In either case there may be comments found at the end of the header line,
or between the BBS and the MSG_NUM entries in HEADER2.
HEADER2 is derived from the header form used in early BBS codes.
it allows addtional information to be passed in the header and parsed
if desired. Some examples of these additional fields seen are:
Z:zipcode
O:orginator
$:bid
C:name_of_sysops_cat
NOTE:
The time stamp in the routing header must be in GMT. Some existing BBS
codes provide the time stamp in other than GMT, and may include a time
zone indicator after the time stamp. This should be considered in the
design of header parsers.
Each system that handles the message places it's routing header
at the top of the message headers before passing the message to
the next BBS. The headers must begin in column 1. A blank line
separates the routing headers from the body of the message.
The last (oldest) routing header shows the BBS where the message
originated. This header is the only source for this information.
The information about the originating BBS is used to create a
return address for reply messages.
Here are two examples of the same header, in the two different formats:
R:930101/0000 1530@KA6FUB.#NOCAL.CA.USA.NA
R:930101/0000 @:KA6FUB.#NOCAL.CA.USA.NA #:1530
These examples show the different syntax for the message number and
originating BBS address. All fields not shown in the examples are
optional at the discretion of the sysop.
Section 3 - Reverse forwarding
Once all messages have either been successfully forwarded from the MASTER
to the SLAVE, or been rejected by the SLAVE, the MASTER may accept
messages from the SLAVE. i.e. the MASTER and SLAVE exchange roles.
This is called "reverse forwarding".
ACCEPT EXCHANGE:
MASTER SLAVE
------ -----
PROMPT ">"
REV_FWD "F>"
SEND_CMD
RESPONSE "OK"
MESSAGE
COMMENT
REV_FWD "F>"
REJECT EXCHANGE:
MASTER SLAVE
------ -----
PROMPT ">"
REV_FWD "F>"
SEND_CMD
RESPONSE "NO"
REV_FWD "F>"
The MASTER indicates that it is ready to accept a message by answering
the SLAVE's PROMPT, ">", with a REV_FWD command, "F>". At that point the
SLAVE issues a SEND_CMD and the process continues as described in
section 2 but with the rolls of MASTER and SLAVE reversed. The only
difference is that the MASTER will always respond with REV_FWD in
place of PROMPT to indicate successful transfer.
REV_FWD = "F>" EOL
The reverse forwarding phase is optional and is under the control of
the MASTER. It can be terminated by any of the following:
SLAVE disconnects
SLAVE sends anything other than a legal SEND_CMD
MASTER disconnects
MASTER sends anything other than "F>".
Section 4 - Forwarding to old BBSs
If the SLAVE does not return a SID then it is assumed that it will
not support BIDs nor OK/NO message rejection.
The SLAVE indicates it is prepared to accept a command by issuing a
PROMPT. This PROMPT is also an acknowledgement that the last message
has been received.
The MASTER initiates the message exchange by issuing a SEND_CMD with no
HLOC or BID. The SLAVE has no way to reject the message so the MASTER
proceeds to send the message subject and body without expecting
acknowlegement from the SLAVE.
Since the SLAVE assumes a user is entering the message, it will display
prompts to lead the user through the message sending process, asking for
a subject, prompting for the message body, etc. The MASTER should
consider this text to be part of the PROMPT and ignore it.
As in Section 2, the MASTER waits until PROMPT is received. This is the
acknowledgement that the message has been recieved and the next message
can be sent.
When the MASTER has no additional messages to send it disconnects
from the SLAVE. Reverse forwarding is not supported in this situation.
Section 5 - Error Conditions
When an error of any nature is detected by either the MASTER or the SLAVE,
that station will disconnect at once, without issuing a PROMPT.
Section 6 - BNF Summary
Meta-syntactic information.
[x] = Optional Zero or one x.
(x y) = Grouping. Treat multiple tokens as single token.
<> = Set.
Characters of interest.
TAB = <0x09>
LF = <0x0a>
CR = <0x0d>
CNTRL_Z = <0x1a>
SP = <0x20>
Character sets of interest.
ALPHA = <'A' - 'Z', 'a' - 'z'>
DIGIT = <'0' - '9'>
ALNUM = ALPHA | DIGIT
ASCII = <0x20 - 0x7f>
SPACE = SP | TAB
8BIT = <0x01 - 0xff, except CR, LF, CTRL_Z>
Character sequences of interest.
EOL = CR | CR LF
NUMBER = DIGIT | NUMBER DIGIT
WHITE = SPACE | WHITE SPACE
ASCII_STR = ASCII | ASCII_STR ASCII
ALNUM_STR = ALNUM | ALNUM_STR ALNUM
8BIT_STR = 8BIT | 8BIT_STR 8BIT
System identifier syntax.
AUTHOR_ID = <ASCII_STR, except '[', ']', '-'>
AUTHOR_DATA = <ASCII_STR, except '[', ']'>
FEATURE = ALPHA [DIGIT]
FEATURE_LIST = FEATURE | FEATURE_LIST FEATURE
SID = "[" AUTHOR_ID ["-" AUTHOR_DATA] "-" FEATURE_LIST "]" EOL
System Prompt syntax.
COMMENT = <ASCII_STR, except '>'>
PROMPT = [COMMENT] ">" EOL
Send Command syntax.
TYPE = 'B' | 'P' | 'T'
CALLSIGN = <ASCII_STR, except '@', '.', ' ', max length 6>
LOC = <ASCII_STR, except '@', '.', ' ', max length 6>
HLOC = <LOC | HLOC "." LOC, max length 31>
BBS = CALLSIGN ["." HLOC]
TO = CALLSIGN [("@" | WHITE "@" WHITE) BBS]
FROM = CALLSIGN
BID = <ASCII_STR, except ' ', max length 12>
SEND = "S" TYPE WHITE TO [WHITE "<" WHITE FROM] [WHITE "$" [BID]]
Message syntax.
SUBJECT = <ASCII_STR, max length 79> EOL
YEAR = DIGIT DIGIT
MONTH = DIGIT DIGIT
DAY = DIGIT DIGIT
HOUR = DIGIT DIGIT
MINUTE = DIGIT DIGIT
STAMP = "R:" YEAR MONTH DAY "/" HOUR MINUTE
MSG_NUM = <NUMBER, range 1 - 65535>
HEADER1 = STAMP WHITE MSG_NUM "@" BBS EOL
HEADER2 = STAMP WHITE "@:" BBS WHITE [ASCII_STR] "#:" MSG_NUM [ASCII_STR]
HEADER = HEADER1 | HEADER2
HEADERS = HEADER | HEADERS HEADER
BODY = 8BIT_STR | BODY EOL 8BIT_STR
EOMA = CTRL_Z EOL
EOMB = EOL "/EX" EOL
MESSAGE = SUBJECT [HEADERS] EOL [BODY] (EOMA | EOMB)
Standard message identification syntax.
MSG_ID = MSG_NUM "_" CALLSIGN
Section 7 - Feature Letter Use
Feature $:
Supports BIDs.
This feature must be supported.
Feature A:
F6FBB - Acknowledge for personal messages.
Feature B:
F6FBB - Binary messages supported.
Feature C:
Obsolete: Supports automatic distribution of current date / time.
(W0RLI, K0ZXF)
Feature F:
F6FBB - Batch forwarding protocol.
Feature H:
Supports Hierarchical Location designators.
This feature must be supported.
Feature I:
Some transport mechanisms do not identify the calling station in the
protocol as AX25 does. To handle this situation, a "null command"
is defined as a line beginning with ';'. This allows the sending station
to send callsigns to satisfy the regulations for station identification.
EXAMPLE
; W5SMM de W0RLI
The receiving station must ignore such lines.
Feature L:
G1nna - Compression.
Feature M:
For AA4RE systems:
Basic level ("M0")
MID = message identifier
Every message has a MID.
The MID looks like a "generated" BID (example 12345_AA4RE).
The "M" letter in the SID indicates that a MID is to be transmitted
with messages that have no BID.
Processing:
If a send command is received by a BBS with a MID, the program
should determine if it is a duplicate. If it is, the program
should respond with the usual "NO" as if it was matching a BID.
Feature R:
AA4RE - Extended reject responses.
OK
Yes, send to me. Note that no number is required. This may
help eliminate phantom message numbers.
NO
This is a real dupe
REJECT
I can't handle this
LATER
Send to me later ...
The LATER is useful when you are already receiving a bulletin on one
connect and someone else tries to send you the same bulletin.
REJECTed messages should be called to the attention of the SYSOP
to see why the reject occurs.
The difference between NO and REJECT is whether or not SYSOP attention
is needed.
Abreviations are alloed: 1 Letter only ... O N L R
There must be a blank after the word or letter. This one is fine:
N Already have it.
This one is not correct:
REJECT, Something wrong
The comma is not allowed.
Feature S:
AA4RE - Extended "S" commands.
Feature X:
W0RLI - Supports ihave/iwant compressed batch forwarding.
A standard for Data compression during the forwarding
of messages in the Amateur Radio BBS Network.
o ihave/iwant variable batch size protocol
o Feature letter X, commands SS, SX, SY.
o lzh compression
----------------------------------------------------------------------------
Command Definitions and BNF description.
----------------------------------------------------------------------------
N = INTEGER, size 32 bits.
protocol = TBD
batch_size = N
file_size = N
msg_count = <0 - 25>
cksum = <file checksum>
id = BID | MID CR
ids = id | ids id
byte = <0x00 - 0xff)
bytes = byte | bytes byte
ihave = "SX " msg_count [" " protocol] [" " batch_size] CR [ids]
iwant = "SY " msg_count CR [ids]
isend = "SS " file_size [" " cksum] CR bytes
For ihave:
Protocol and batch_size not used in initial implementation.
Default protocol is: lzh compressed export/import file.
For iwant:
SY means want only these.
Note that the SS command must terminate with CR, without LF.
The optional checksum is computed by summing all the bytes
in the file as unsigned integers. Example code:
{
int byte;
unsigned int sum;
sum = 0;
for (all bytes in file) sum += byte;
}
RFC-822 header fields used are:
To:
From:
Subject:
Message-ID:
X-msgtype:
X-BID:
----------------------------------------------------------------------------
The basic interchange (example):
----------------------------------------------------------------------------
bn are BIDs (or MIDs if the message has no BID).
m: is master, s: is slave.
m: SX 5
m: b1
m: b2
m: b3
m: b4
m: b5
s: SY 3
s: b1
s: b3
s: b5
m: SS 26545
m: <sends 26545 byte file>
In the case of any error, the station noticing the error must disconnect.
----------------------------------------------------------------------------
With more detail of one implementation (MB/SERVER processing)
----------------------------------------------------------------------------
Maximum batch size defined globally (default), and per link.
Ability to turn compression on/off (add/drop feature X in SID).
>From sending side:
MB:
Scan messages to find a batch just larger than max batch size.
Keep record numbers and cc: id in list.
Send ihave.
Receive iwant.
Mark all messages in ihave and not in iwant as forwarded (dup bid).
Pass iwant list to SERVER in file.
Wait for server acknowledge.
SERVER:
Create export file.
Compress export file.
Signal MB that compressed file ready to send.
MB:
Send isend, send the file.
Receive prompt.
Mark all messages in iwant as forwarded.
>From receiving side:
MB:
Receive ihave.
Check bids in ihave.
For all non-dup bids, make iwant list.
Send iwant.
Receive compressed file.
Signal SERVER import file available.
Send prompt.
SERVER:
Decompress file, import messages.
Section 8 - Import / Export files.
Import/Export files may contain any number of messages.
Each message is terminated by EOMB
RFC-822 header use in import/export files.
The standard RFC-822 keywords which must be supported are:
To:
From:
Subject:
Message-ID:
cc:
Extension keywords which must be supported are:
X-msgtype: (W0RLI)
X-BBS-Msg-Type: (JNOS)
X-BID: (W0RLI)
X-BBS-Hold: (JNOS)
X-Forwarded-To: (JNOS)
END OF SPEC
Ritorna a Software Radioamatoriale by
IW3FQG