Contents
TNOS FORWARD.BBS File Format

Brian A. Lantz, brian@lantz.com

v0.06, 7 August, 1996

Contents

Abstract

THE FORWARD.BBS FILE

COMMENTS

BBS ENTRY DEFINITIONS

FILE DIRECTIVES

BBS ATTRIBUTES


Abstract

This is a description of the FORWARD.BBS File Format used by TNOS. It has been made as flexible as possible to provide the individual SYSOP with as many tools to effectively handle traffic as possible. This specification is updated as the work progresses, so it is a dynamically changing document. This document is NOT meant to deal with forwarding in an exhaustive manner, nor is it meant to be a HOW-TO on forwarding. It's sole purpose is to document the file format for the FORWARD.BBS file. This document, part of the TNOS Documentation Project (TDP), reflects a complete description this file format for TNOS Release 2.11a1 and later.


THE FORWARD.BBS FILE

The FORWARD.BBS file is used to control outgoing forwarding sessions on a TNOS system. TNOS will only start outgoing forwarding sessions with PBBSs having entries in this file.

 (1)

The file is a simple ASCII file. Each line can be either a comment,  a BBS entry definition, a file directive, or a BBS attribute. Any other lines can (and probably will) cause you grief, and unexpected results.


COMMENTS

Any blank lines, or lines beginning with a '#' or ';' are ignored and  treated as comments. Comments can be located anywhere within the file.

You should use comments to document anything in the file that may NOTbe obvious to you. All comments are ignored by the forward file parser.


BBS ENTRY DEFINITIONS

Each entry for a BBS is made up of a name in square brackets (the entry definition), followed by any needed attributes for that BBS. While any name can be used for a BBS, it is better to use the callsign of the BBS for this.

An entry ends when either a line starting with a '-' is found, a new entry definition is found, or at the end of the file.

A sample of two BBS entry definitions, would be:

        [k0zxf]

        ......          (attributes go here)

        ......

        [w4dph]

        .......         (and here)

        .......


FILE DIRECTIVES

There are several file directives that can be used within the FORWARD.BBS file. Directives are special commands that can alter the normal processing of the file.

File Inclusion Directive

Conditional Processing Directives


BBS ATTRIBUTES

Each BBS in the FORWARD.BBS file has certain attributes associated with it. Almost ALL of them have defaults which as assigned to a BBS as the parsing of its entry begins. Any defined attributes will override the default attributes for that BBS.

Syntax for Attributes

Simple Attributes

Compound Attributes


File Inclusion Directive

At any time within the forward.bbs file, you can include the contents of another file, by using the 'include' directive. This allows you to compose a file with common information, and include it easily at several places. Then you only have one place to make any changes at, and less chances of having incorrect information in a section due to forgetting to update several places in the file.

 (1)

Once the included file is completed, the original file will continue being processed from the place where the 'include' directive was found. You CANNOT 'include' a file WITHIN an included file, though.

An example of including a common file of area names from within a BBS's AREA attribute would look like:

        AREAS = {

         k0zxf

         include /nos/etc/public.areas

        }


Conditional Processing Directives

There are several directives that allow you to have conditional statements in the FORWARD.BBS file. These conditional directives allow you to have a greater deal of flexibility, in that they permit you to set different attributes based on the number of connect attempts, the time of day, and the 'forward mode' setting.

Use of Conditionals

Supported Conditionals


Syntax for Attributes

All BBS Attributes are of the format 'KEYWORD = parameters'. There can be any amount of whitespace before the KEYWORD, and surrounding the '='. The parameters do not start till the first non-whitespace character after the '='. If more than one of an certain Attribute is processed, then only the last is used.


Simple Attributes

Most of the available attributes are simple attributes. Simple attributes are attributes which either set a boolean value (yes or no), a numeric value, or a string. Only one value is set for each simple attribute.

Currently supported simple attributes include:

ALTTIME = xxx

sets the default delay time (in minutes) to be used for any Alternate BBS routings that do not specify a time. The default for this attribute is '720' minutes (12 hours).

BULLETINS = [YES | NO  ]

sets whether or not bulletin messages are  are to be forwarded. This can be used to restrict bulletins being forwarded only during certain hours or only by certain connect methods, or only in certain forwarding modes, etc. Bulletins are messages in areas defined in the 'etc/areas' file. The default for this attribute is 'YES'. (1)

CLOCKOFFSET = xx

determines how to adjust your local time before sending it, when setting a remote TNC's clock. This is only used in connection with the CLOCKSET Attribute. If the remote station does NOT have a 'C' in their SID, then this attribute is ignored. Use a '1' to add one hour to localtime, a '-1' to subtract one hour, etc. The default for this attribute is '0'.

CLOCKSET = [YES | NO  ]

determines whether or not you will send a command to the remote TNC to set their clock, if they request it. Many TNC's (like PacComm's) Mailboxes send out a 'C' in their SID, which says, 'set my clock'. TNOS will do this on forwarding sessions, if this Attribute is 'YES'. If the remote station does NOT have a 'C' in their SID, then this attribute is ignored. The default  for this attribute is 'YES'.

CONNECT = constr

sets the connection string 'constr' to be used in setting up the connection for forwarding. This can be one of the follow:

o	 ax25 <ifc> callsign [optional digis]
  for an ax25 connection (with optional digis).

o	 connect <ifc> callsign [optional digis]
  for an alternate way of specifying an ax25 connection (with optional digis).

o	 netrom <nodename>
  for a netrom connection

o	 telnet <hostname>
  for a telnet connection

o	 export
  for an export file based on the BBS name

o	 incoming
  for BBSs that only have incoming connects. This should NOT be used with conditionals for 'TRY'

*IF* a valid connect is NOT found (either due to omission or conditional processing), the BBS will not be processed. There is NOdefault for this attribute.

FBBSIZE = xx

sets the maximum size for the FBB data proposal to queue for sending. Normally, with the default for this attribute being '0', there will be up to 5 messages sent during the negotiation (assuming you have at least 5 to send). If this attribute is non-zero, then after added a message to the negotiation, a check is made to see if the total size of the negotiation is now larger than the 'FBBSIZE', and if so, no more messages will be added to the negotiation block. This means that the 'actual maximum' size of your block *could* be:

                        ('FBBSIZE' - 1) + ('SIZE' - 1)

This is *IF* the negotiation packet was at least one byte less than the 'FBBSIZE' attribute, and the next message was one byte less than the 'SIZE' attribute.
  For example, if the 'SIZE' attribute is 6K, and the 'FBBSIZE' attribute is 6K, and message 1 is 2K, message 2 is 2K, and message 3 is 5K, then it will not attempt to add a 4th message to the negotiation, as it already has a negotiation size of 9K.

LIMITTIME = xxx

sets the maximum forwarding session time (in minutes) to be used on forwarding sessions. The default for this attribute is the value set by the 'forward limittime' command. (2)

LIMITTYPE = type

This allows you to limit the forwarding protocol type used with this BBS. Values for 'type' are:

o	FBB for FBB compressed forwarding

o	FBB-NONCOMPRESSED for FBB non-compressed forwarding

o	X-FWD for W0RLI X-compressed forwarding

o	MBL or RLI for non-FBB forwarding.

This only sets the BEST protocol available, (in the order listed above from best to worst), and any lesser protocol CAN be used. The default for this attribute is 'FBB', or any available protocol, with no limitation. (3)

MINIDLE = xxx

sets the minimum idle time (in seconds) to be used between outbound forwarding sessions. The default for this attribute is the value set by the 'forward minidle' command. (4)

PERSONALS = [YES | NO  ]

sets whether or not personal messages are  are to be forwarded. This can be used to restrict personal messages being forwarded to only during certain hours or only by certain connect methods, or only in certain forwarding modes, etc. Personal messages are messages in areas NOT defined in the 'etc/areas' file. The default for this attribute is 'YES'. (5)

POLL = [YES | NO  ]

determines whether to poll the BBS, even if no outbound data is waiting. The default for this attribute is 'NO'.

REVINCOMING = [YES | NO  ]

determines whether or not reverse forwarding will be asked for to the remote BBS, after sending any outbound data. This MUST be set to 'YES' if POLL is 'YES'. Also, this Attribute has NO EFFECT, if you are using FBB-style forwarding with this BBS. The default for this attribute is 'YES'.

SIZE = xxx

sets the maximum message size allowed, in bytes. The default for this attribute is '0', which means any size message will be allowed.

SUBCHANNEL = xx

sets the BBS to use subchannel number 'xx'. The default for this attribute is no subchannel (-1). Valid subchannel numbers start with 0.

TRIES = xx

sets the maximum number of different connection methods defined for this BBS, with conditional processing. This is read and used to re-process the BBS for as many times as needed. The default for this attribute is '1'.


Compound Attributes

There are two attributes that do not define simple variables, but instead define attribute lists. There are currently only two compound attributes.

The SCRIPT Attribute

Supported SCRIPT Commands

The AREAS Attribute

Format of the AREAS Attribute

The AREAS Attribute's 'ALT' Parameter


Use of Conditionals

The IF conditional directive allows you to test certain conditions, and (if they match a desired value) allow you to act differently based on this condition. You can also reverse the condition, with the use of the ELSE conditional directive. Each IF directive must end with a ENDIF directive. The ELIF directive is a shortcut for ELSE followed by a second IF, and eliminates an ENDIF in the process.

The use of 'if-else-elif-endif' to conditionally process the file is  allowed anywhere in the file, except WITHIN an attribute (like AREAS or SCRIPT). You can nest  conditional processing within other conditional processing up to 20  levels deep. Both of the following styles are supported:

        if xxxxxx               if aaaaaaa

         attributeA              attribute1

         if yyyyyy              elif bbbbbbb

          attributeB             attribute2

         else                   elif ccccccc

          attributeC             attribute3

         endif                  else

        else                     attribute4

         attributeD             endif

        endif

While conditions are *NOT* allowed within a SCRIPT Attribute and an AREAS Attribute, multiple SCRIPT/AREAS Attributes can be in a BBS's entry,  with some being contained completely WITHIN conditional processing. Multiple SCRIPT/AREAS  Attributes are appended in the order found.


Supported Conditionals

The following are the presently supported conditions that can be tested with conditional directives:

if TIME = hhmm-hhmm

checks to see if the current time is within the time range given.

if TRY = xx

checks to see if the connection attempt matches the number 'xx'. This can be used to set up multiple connection methods. The first attempt is 'TRY = 1'.

if MODE = xx

checks to see if the forwarding mode matches the number 'xx'. This can be used to set up different forwarding profiles, such as for emergencies, etc. (2)

** Note: when a message from a specific area is to be placed in a BBS's  forwarding queue, it ALWAYS processes that BBS's entry with 'TRY = 1' and  the time set to the current time.


The SCRIPT Attribute

The SCRIPT attribute has several script commands available to help make a successful forwarding connection. A SCRIPT attribute is optional. There is NO default for this attribute. This is not needed for most people, but can be quite useful for traversing NODES, logging into telnets, etc. The SCRIPT attribute CANNOT have conditional processing WITHIN the attribute, but it is acceptable to have several SCRIPT attributes that are totally contained WITHIN conditional processing.  Multiple SCRIPT attributes (if defined) are appended in the order found.

The format of the SCRIPT Attribute is:

        SCRIPT = {

          command

          command

        }


Supported SCRIPT Commands

Each SCRIPT atribute can have many commands in its definition, enabling you to set up as detailed of a connection script as you require.

Current available commands that can be used within a SCRIPT attribute are:

SEND string

sends the specified 'string' to the BBS

WAIT nnn string

waits up to 'nnn' seconds for the remote BBS to send the string 'string'.

SID [sidstr  ]

this 'fools' TNOS into believing it just received the SID 'sidstr', and gets it to process that SID. TNOS will reply with IT'S SID, *to* the remote BBS. This is not needed, usually.


The AREAS Attribute

The AREAS attribute is used to define which areas are to be sent to the BBS being defined. Only messages within these areas will be sent. While this is an OPTIONAL attribute, a BBS defined without an AREAS attribute does not serve much of a purpose.

The AREAS attribute has several options available for each area defined. The AREAS Attribute CANNOT have conditional processingWITHIN the Attribute, it is acceptable to have several AREAS attributes that are totally contained WITHINconditional processing. Multiple AREAS attributes (if defined) are appended in the order found.


Format of the AREAS Attribute

The format of the AREAS Attribute is:

        AREAS = {

          areaname [rewrite] [ALT[=bbsname[,time]]]

          areaname [rewrite] [ALT[=bbsname[,time]]]

        }

The areaname is required on each line. There can be any amount of  whitespace preceeding the areaname, and surrounding the optional rewrite  address. The 'rewrite' address is an address that all mail send from this  area can have 'forced' upon it, changing the original 'To:' address to  this rewrite address.


The AREAS Attribute's 'ALT' Parameter

The ALT parameter of an AREAS line can have one of three forms:

ALT

marks this BBS to be an Alternate BBS for this area. New mail does not automatically get added to this BBSs forwarding queue  until it has reached it's alternate time  from the original BBS. At that time, it is removed from the original BBS, and placed into the Alternate BBSs queue.

ALT=bbsname

marks this area to have 'bbsname' as an Alternate BBS, and have it's alternate time be this BBSs 'ALTTIME' Attribute's value. When the alternate time has passed and a  message still remains on the BBS, it will be added to 'bbsname's forwarding queue.

ALT=bbsname,time

same as above, except the alternate time is overridden with 'time'

There can be any number of 'ALT=' parameters on an area line, but the 'ALT'  and 'ALT=' parameters are mutually exclusive.


The format of the FORWARD.BBS file changed in TNOSRelease 2.00 from the way that JNOS uses it. There is a utility, cnvfwd, that will convert a JNOS FORWARD.BBS file, or a TNOS 1.xx forward file.


The file inclusion directive was added in TNOS 2.02pl2, and can be found in any release after that release.


The MODE conditional directive was added inTNOS 2.02pl1, and can be found in any release after that release.


The BULLETINS attribute was added inTNOS 2.02pl2, and can be found in any release after that release.


The LIMITTIME attribute was added inTNOS 2.11al, and can be found in any release after that release.


The LIMITTYPE attribute was added inTNOS 2.02pl2, and can be found in any release after that release.


The MINIDLE attribute was added inTNOS 2.11al, and can be found in any release after that release.


The PERSONALS attribute was added inTNOS 2.02pl2, and can be found in any release after that release.