Synchronet QWK Network Extensions

Imported from the old SYNCQNET.DOC file, dated 03/23/95, on July-19-2012:

This document is intended for developers of QWK off-line readers or mail doors for non-Synchronet BBS packages.

Synchronet multi-node BBS software has never had a QWK door written for it, because it has had extensive internal QWK off-line reader and network support since version 1 (1992). Since QWK networking is such an integrated component of Synchronet, it is extremely easy to setup and maintain in comparison to other network technologies (Fido, PostLink, Internet, etc.) which are also internally supported, but not as easy to setup for novice sysops.

Through our own extensions to the QWKnet pseudo-standard, we have filled many of the gaps that left QWK behind when it came to more advanced network needs (most notably, routed NetMail).

Not all of the information in this document will be relevant to your development, but we would much rather give too much information, than not enough. If other BBS program/mail-door authors choose not to implement this standard, it WON'T be because we didn't supply enough information!

Our QWKnet extensions are an evolving entity and we're definitely open to suggestions for future enhancements/compatibility issues. We encourage other developers to contact us directly for questions or notification of compatibility or intended compatibility between their product and ours.

Synchronet has an entirely separate message area specifically designed for local E-mail and NetMail. This “e-mail” message area is always conference number 0 in a QWK or REP packet. All non-zero conferences are sub-boards (AKA “Echoes”, “SIGs”, “Forums”, “Conferences”, etc).

QWK IDs (AKA BBSID) consist of between two and eight valid DOS characters and the first character must be alphabetic. QWK IDs must not contain the '@' character. It is extremely beneficial if all QWK IDs are unique in a given network of systems. QWK IDs that do not match this format may work for basic QWKnet functions, but many features may not work. QWK IDs are always considered case insensitive. The strings “SYSOP” and “NETMAIL” are not valid QWK IDs.

A QWKnet node on a Synchronet BBS must be created specifically for QWK networking. This is done by using the node's QWK ID as the user name on the BBS and the sysop must give the account the 'Q' restriction. This restriction allows the uploaded REP packets to come from any user name (AKA Net Status) and automatically eliminates non-QWK networked sub-boards from the QWK packets. The 'Q' restriction causes the QWK menu to immediately come up at logon (rather than the normal “user” logon procedure), taglines are added to locally created messages being exported to REP packets, as well as other behavior differences from normal “user” accounts. Synchronet creates a NETFLAGS.DAT file for 'Q' restricted accounts that haven't disabled CONTROL files in the QWK packets, though Synchronet itself does not ever use the NETFLAGS.DAT - it's created for compatibility with non-Synchronet QWKnet nodes.

When calling a Synchronet BBS for QWK packets, conference numbers will start at 0 (for E-mail) and then jump to 1001 or 2001 or a similar number. The thousands and more significant places represent the message Group number and the less significant places represent the Sub-board number within that group. Conference numbers are not necessarily consecutive, though they are (at this time) always sequential. The CONTROL.DAT file will contain a list of all the conferences (and numbers) the current account has access to. Here is an example CONTROL.DAT:

Vertrauen
Fullerton, CA
714-529-9525
Digital Man, Sysop
0000,VERT
02-28-1995,03:22:02
Tmbbs

0
0
88
0
E-mail
1001
Notices
1002
General
1003
Software
1004
Hardware
1005
Progrmming
1006
R.F.I.M.
1007
Opinion
2001
DOVE-Net
2002
Ads
2003
Entertain
2004
Debate
2005
Computers
2006
Programmin
2007
Synchronet
2008
SBBS Sysop
2009
Domain Ent
2010
SyncData
3001
FidoNet
3002
Musicians
3003
prog rock
3004
Monte Pyth
3005
Gaming
3006
Flight-Sim
HELLO
BBSNEWS
GOODBYE

When a Synchronet system calls a QWKnet hub, it can use any conference number scheme the hub system is using (max conference number 65535), but NetMail is always assumed to be sent and received from conference number 0.

When calling a Synchronet BBS, the following control messages are supported when included in an uploaded REP packet:

Subj: DROP [conf#] Note: Drop current conference (or specified conference #) from future packets

Subj: ADD [ptr | -msgs | mm/dd/yy] Note: Add current conference to future packets and optionally set message ptr

Subj: ADD [YOURS] [ptr | -msgs | mm/dd/yy] Note: Add current conference to future packets and optionally set message ptr

    If "YOURS" is specified, only mail addressed to you will be packed for
    this conference. Not applicable for QWKnet node accounts.

Subj: YOURS [ptr | -msgs | mm/dd/yy] Note: Same as “ADD YOURS”

Subj: RESET [ptr | -msgs | mm/dd/yy] Note: Set message pointer for current conference, - indicates offset from last

Subj: RESETALL [ptr | -msgs | mm/dd/yy] Note: Set message pointers for all conferences

Subj: FREQ <filename> Note: File Request from file transfer database (not attachments)

Subj: FILES [ON | OFF | mm/dd/yy] Note: Include files list in packet and/or specify new-scan date

Subj: ATTACH [ON | OFF] Note: Include file attachments in packet automatically (e-mail only)

Subj: MAIL [ALL | ON | OFF] Note: Include private mail-box (ALL includes previously read mail)

Subj: DELMAIL [ON | OFF] Note: Automatically delete mail-box after successful packet download

Subj: CTRL-A [KEEP | EXPAND | STRIP] Note: Ctrl-A color/attribute codes - leave-in, expand to ANSI, or remove

Subj: NDX [ON | OFF] Note: Include index (.NDX) files (not necessary for Synchronet QWKnet)

Subj: CONTROL [ON | OFF] Note: Include control files (DOOR.ID, CONTROL.DAT, NETFLAGS.DAT, etc)

Subj: VIA [ON | OFF] Note: Include messge path (@VIA) line in messages

Subj: TZ [ON | OFF] Note: Include time zone (@TZ) line in messages

Example DOOR.ID created by Synchronet v2.11:

DOOR = Synchronet
VERSION = 2.11
SYSTEM = Synchronet v2.11
CONTROLNAME = SBBS
CONTROLTYPE = ADD
CONTROLTYPE = DROP
CONTROLTYPE = YOURS
CONTROLTYPE = RESET
CONTROLTYPE = RESETALL
CONTROLTYPE = FILES
CONTROLTYPE = ATTACH
CONTROLTYPE = OWN
CONTROLTYPE = MAIL
CONTROLTYPE = DELMAIL
CONTROLTYPE = CTRL-A
CONTROLTYPE = FREQ
CONTROLTYPE = NDX
CONTROLTYPE = TZ
CONTROLTYPE = VIA
CONTROLTYPE = CONTROL
MIXEDCASE = YES

Any non-QWK related files included in a QWKnet REP packet uploaded to a Synchronet BBS (or QWK packets received from a QWKnet hub) will be automatically moved into the DATA\QNET\<QWKID.IN> directory (where QWKID is the QWK ID of the node or hub that sent the file) and the sysop will be notified of the received file.

If a Synchronet sysop wishes to send a QWKnet node or hub a file, he need only create the directory DATA\QNET\<QWKID.OUT> (where QWKID is the QWK ID of the destination node) and copy the file(s) into this directory. The next time this node calls and downloads a REP packet (or a QWK is packed for the hub), this file will be archived in the packet automatically and then deleted from the .OUT directory. This is NOT the same as FREQing (File Requesting) a file. It is just a simple means of transferring files between QWKnet nodes and hubs.

When downloading a QWKnet packet from a Synchronet BBS, any e-mail (conf #0) waiting for the QWKnet node account will be automatically included in the packet. If the TO: name is the node's QWK ID or the word “SYSOP” (not case sensitive), the NetMail should be assumed to be intended for the Sysop. Otherwise if the TO: name is not “NETMAIL” (not case sensitive), then it is a single hop NetMail message intended for a user on the node's system going by the TO: name. The same holds true for REP packets sent to hubs containing messages in conf #0.

Messages sent to “NETMAIL” (not case sensitive) in conference number 0 are intended for another system that the current system unpacking the packet must forward the message to. The destination user name and address will be on the VERY first line of the message text in the following format: “name@addr” Where “name” is the full user name (25 chars max) and “addr” is EITHER the destination node's QWK ID or the complete routing address. Complete routing addresses are stored as: “NEXTID/.../DESTID”, where NEXTID is the QWK ID of next system in the link and DESTID is the inteded destination's QWK ID. The “...” portion of the above routed address designates a variable number of QWK IDs to pass through before reaching the DESTID.

Synchronet, automatically expands QWK ID's to complete routing addresses whenever possible (when the path is known), so expect to find the complete routing address more often than just the destination QWK ID.

When a system discovers a routed NetMail message in a QWK or REP packet it needs to determine if the next hop is the destination node, and if so, change the TO: field to the destination user name and eliminate the “user@addr” line from the message.

If the next hop is not the destination node, it needs to leave the TO: field as “NETMAIL” and remove itself and the next hop from the “addr” portion of the “user@addr” line before creating the QWK or REP packet for the next hop. After exporting the NetMail message successfully to QWK or REP, it should be deleted.

So, you're probably asking yourself, how does Synchronet know how to expand a QWK ID into a complete routing address? Well, the @VIA: line is the key. Every mail message (EchoMail and NetMail) that has passed through at least one system to reach the current system will contain a special first line in the body text: “@VIA: QWKID/.../ORGID” Where QWKID is the ID of the system that sent the message to the system that created the QWK or REP packet being unpacked and ORGID is the originating system's QWK ID.

Mail that originates on a node or hub will not contain an @VIA: line when exported to nodes or hub that are directly connected to it. Only when THOSE systems then export the message again, is the @VIA: line added.

Synchronet parses the @VIA: line (if it exists) to automatically maintain a dynamic “route map” (filename DATA\QNET\ROUTE.DAT). Each line contains information about a QWKnet system that is not directly connected. The format (though not necessarily relevant to other BBS packages) is: “MM/DD/YY DESTID:QWKID/QWKID/QWKID/...” Where MM/DD/YY is the date the entry was last updated in the route file, DESTID is the QWK ID of the system which we are defining the routing, and QWKID/QWKID etc. are the QWK IDs of the systems necessary to reach DESTID.

Synchronet updates entries for existing DESTID, so if the routing changes, the route file changes automatically. Old entries (indicating no mail traffic from DESTID in X number of days) are automatically deleted. Synchronet uses 90 days as maximum age to keep old route entries.

Synchronet comes with a utility (QWKNODES.EXE) that can be used to manually scan the existing message bases and create a ROUTE.DAT file (mentioned above), a USERS.DAT file (for automatically looking up user names on other systems), and a NODES.DAT file (not currently used by Synchronet, mainly for human consumption - finding a QWKnode near you!). The format of the USERS.DAT file is each line: “username DESTID MM/DD/YY (QWKID/.../DESTID)” Where username is the user's full name, DESTID is the QWK ID of the system the user is on (or last posted from), MM/DD/YY is the date the message was imported, and QWKID/.../ is the path to the DESTID (if not direct connection). The only parts Synchronet uses at this time are username and DESTID (ROUTE.DAT is used to expand to complete routing address if necessary).

When importing mail with an @VIA: line, Synchronet also checks to make sure that the current system's QWK ID is not present in the list of QWK IDs. If it is present, then the message is assumed to be an erroneous dupe loop and is ignored (not imported). This is called “circular path detection” and is caused by systems that accidentally hub off of more than one system in the same QWK network causing a message “loop”.

@VIA: lines can be disabled on a Synchronet hub by sending a message to “SBBS” with a title of “VIA OFF”.

Synchronet automatically disables @VIA: lines for hubs when “Ctrl-A Codes” are not set to “Leave-in” (this is done by the Synchronet sysop in SCFG), assuming this indicates the hub BBS is not a Synchronet system. So, if you're receiving @VIA: codes from a Synchronet BBS that is a node (not a hub) off of your system, expect to receive Synchronet Ctrl-A codes too! :) Synchronet Ctrl-A codes are ANSI equivalents (using a more simple escape sequence) defined as:

(All attribute codes are be preceded by a Ctrl-A character - ASCII 1)

	Foreground  Background
Black	    K		0
Red	    R		1
Green	    G		2
Yellow	    Y		3
Blue	    B		4
Magenta     M		5
Cyan	    C		6
White	    W		7

High	    H	High Intensity
Blink	    I	Blinking
Normal      N   No Special Attributes
Pause       P   Insert a Pause Prompt into message
CLS         L   Insert a Form Feed into message

Another missing element of the QWK format is time zone information. Synchronet offers time zone information in QWK messages by adding an @TZ: line before the message body (below “name@addr” and “@VIA:” lines if they exist). The time zone specified is of the originating system. The format is: “@TZ: xxxx” Where xxxx are four hex digits (16-bit signed value). The value of the hex digits is defined in the SMB (Synchronet Message Base) specification, but for your convenience, we have included it here:

	If the zone is in the range -720 to +720, it represents the
	number of minutes east or west of UT. Values in this range
	should only be used for time zones not otherwise represented
	here.

	If the zone is greater than 720 or less than -720, then the
	following bits have special meaning:

	(1<<12) 	// Non-US time zone	(east of UT)
	(1<<13) 	// Non-US time zone	(west of UT)
	(1<<14) 	// U.S. time zone
	(1<<15) 	// Daylight savings

	The lower 12 bits (0 through 11) contain the number of minutes
	east or west of UT (not accounting for daylight savings).

	If the time zone is one specified in the U.S. Uniform Time Act,
	the following values represent the zone:

	AST 0x40F0	// Atlantic		(-04:00)
	EST 0x412C	// Eastern		(-05:00)
	CST 0x4168	// Central		(-06:00)
	MST 0x41A4	// Mountain		(-07:00)
	PST 0x41E0	// Pacific		(-08:00)
	YST 0x421C	// Yukon		(-09:00)
	HST 0x4258	// Hawaii/Alaska	(-10:00)
	BST 0x4294	// Bering		(-11:00)

	With bit 15 set, the following values represent the same zone
	with the presence of daylight savings:

	ADT 0xC0F0	// Atlantic		(-03:00)
	EDT 0xC12C	// Eastern		(-04:00)
	CDT 0xC168	// Central		(-05:00)
	MDT 0xC1A4	// Mountain		(-06:00)
	PDT 0xC1E0	// Pacific		(-07:00)
	YDT 0xC21C	// Yukon		(-08:00)
	HDT 0xC258	// Hawaii/Alaska	(-09:00)
	BDT 0xC294	// Bering		(-10:00)

	The following non-standard time zone specifications may also be
	used:

	MID 0x2294	// Midway		(-11:00)
	VAN 0x21E0	// Vancouver		(-08:00)
	EDM 0x21A4	// Edmonton		(-07:00)
	WIN 0x2168	// Winnipeg		(-06:00)
	BOG 0x212C	// Bogota		(-05:00)
	CAR 0x20F0	// Caracas		(-04:00)
	RIO 0x20B4	// Rio de Janeiro	(-03:00)
	FER 0x2078	// Fernando de Noronha	(-02:00)
	AZO 0x203C	// Azores		(-01:00)
	LON 0x1000	// London		(+00:00)
	BER 0x103C	// Berlin		(+01:00)
	ATH 0x1078	// Athens		(+02:00)
	MOS 0x10B4	// Moscow		(+03:00)
	DUB 0x10F0	// Dubai		(+04:00)
	KAB 0x110E	// Kabul		(+04:30)
	KAR 0x112C	// Karachi		(+05:00)
	BOM 0x114A	// Bombay		(+05:30)
	KAT 0x1159	// Kathmandu		(+05:45)
	DHA 0x1168	// Dhaka		(+06:00)
	BAN 0x11A4	// Bangkok		(+07:00)
	HON 0x11E0	// Hong Kong		(+08:00)
	TOK 0x121C	// Tokyo		(+09:00)
	SYD 0x1258	// Sydney		(+10:00)
	NOU 0x1294	// Noumea		(+11:00)
	WEL 0x12D0	// Wellington		(+12:00)

Examples are usually helpful at understanding concepts, so we are going to use a real-life Synchronet extended QWK network (DOVE-Net) to demonstrate how the above extensions work.

First, the network topology (abbreviated for this example):

	   +----------------+---------VERT----------------------+
	   |		    |	       |			|
  +------PHOUSE-----+	  DOMAIN    NITEMOVE	       +------CENTURY------+
  |	   |	    |		       |	       |	|	   |
CIRCLE7  FANTAIR  KRYSTAL      +------TLOC------+    TALONBBS  VSS_BBS	PHOENIX
			       |		|
			     BLAZING	   WILDHARE

The ROUTE.DAT on VERT (master hub) for the above (in case you were curious):

03/22/95 CIRCLE7:PHOUSE
03/22/95 TLOC:NITEMOVE
03/22/95 FANTAIR:PHOUSE
03/20/95 TALONBBS:CENTURY
03/17/95 BLAZING:NITEMOVE/TLOC
03/19/95 KRYSTAL:PHOUSE
03/19/95 VSS_BBS:CENTURY
03/20/95 PHOENIX:CENTURY
03/20/95 WILDHARE:NITEMOVE/TLOC

Larger Sample

Mail originating on VERT would NOT contain an @VIA: line when sent to the following systems: PHOUSE, DOMAIN, NITEMOVE, and CENTURY. Mail originating on VERT would contain “@VIA: VERT” when sent to the systems: CIRCLE7, FANTAIR, KRYSTAL, TLOC, TALONBBS, VSS_BBS, and PHOENIX. Mail originating on VERT would contain “@VIA: NITEMOVE/VERT” went sent to the following systems: BLAZING and WILDHARE.

Mail originating on BLAZING would contain the following @VIA: lines when sent to the following systems:

TLOC:	   <none>
WILDHARE:  "@VIA: BLAZING"
NITEMOVE:  "@VIA: BLAZING"
VERT:	   "@VIA: TLOC/BLAZING"
DOMAIN:    "@VIA: NITEMOVE/TLOC/BLAZING"
PHOUSE:    "@VIA: NITEMOVE/TLOC/BLAZING"
CIRCLE7:   "@VIA: VERT/NITEMOVE/TLOC/BLAZING"
FANTAIR:   "@VIA: VERT/NITEMOVE/TLOC/BLAZING"
KRYSTAL:   "@VIA: VERT/NITEMOVE/TLOC/BLAZING"
CENTURY:   "@VIA: NITEMOVE/TLOC/BLAZING"
TALONBBS:  "@VIA: VERT/NITEMOVE/TLOC/BLAZING"
VSS_BBS:   "@VIA: VERT/NITEMOVE/TLOC/BLAZING"
PHOENIX:   "@VIA: VERT/NITEMOVE/TLOC/BLAZING"

Each of the above systems needs to have its own way of storing the QWK ID of the system the message last came from, so it can build the entire return address. Luckily, all of the above are Synchronet systems, which stores the complete route address in the SMB format message header. Different BBS packages will need different ways of storing the originating QWK ID or (preferrably) the complete route address (built from the above VIA path with the last hop QWK prepended to the address).

Using the above example, VERT would store the QWKnet address of mail originating from WILDHARE as “NITEMOVE/TLOC/WILDHARE”. Synchronet does not actually store addresses in its local message bases using @VIA:. This is only used for extended the QWK format (which doesn't have a storage area for network addresses). The @VIA: portion of the message body is added and removed automatically from each message imported from or exported to QWK format (if applicable).

If the BBS software or mail door uses a route map, (similar to the ROUTE.DAT that Synchronet uses), it should be able to insert routing information on the fly.

If for example, a user on VERT sent NetMail to a user on WILDHARE, Synchronet would look in the ROUTE.DAT and find an entry for WILDHARE and automatically expand the address from “user@WILDHARE” to “user@NITEMOVE/TLOC/WILDHARE”. If a user on VERT were to send NetMail to “user@WILDHARE/BIGBBS”, Synchronet would not even look for BIGBBS in the ROUTE.DAT (it only looks for the first hop in the routing), so it would still route the message properly to WILDHARE by changing the address to NITEMOVE/TLOC/WILDHARE/BIGBBS.

Each system that receives NetMail should compare the destination QWK ID to all the QWKnet nodes it feeds and the hubs it calls. If a match is found, it should ignore the routing information and send it directly (overriding the specified routing). Example, a user on TALONBBS sends NetMail to “user@CENTURY/VERT/PHOUSE/NITEMOVE” (an incorrect route, but valid as far as CENTURY knows) - it is possible that PHOUSE now feeds NITEMOVE and CENTURY does not yet know about it, so it leaves the route address intact and passes the message on to VERT. VERT sees that it feeds NITEMOVE directly, so it sends the mail directly (removing the routing information).

Using the above example network topology, if a user were to send NetMail from BLAZING to a user on CIRCLE7:

REP sent from BLAZING to TLOC:
Conf #0 - To: NETMAIL
	  1stLine: username@NITEMOVE/VERT/PHOUSE/CIRCLE7

REP sent from TLOC to NITEMOVE:
Conf #0 - To: NETMAIL
	  1stLine: username@VERT/PHOUSE/CIRCLE7
	  2ndLine: @VIA: BLAZING

REP sent from NITEMOVE to VERT:
Conf #0 - To: NETMAIL
	  1stLine: username@PHOUSE/CIRCLE7
	  2ndLine: @VIA: TLOC/BLAZING

QWK sent from VERT to PHOUSE:
Conf #0 - To: NETMAIL
	  1stLine: username@CIRCLE7
	  2ndLine: @VIA: NITEMOVE/TLOC/BLAZING

QWK sent from PHOUSE to CIRCLE7:
Conf #0 - To: username
	  1stLine: @VIA: VERT/NITEMOVE/TLOC/BLAZING

• QWK
• DOVE-Net
• Reference Library