TNOS FORWARD.BBS File Format Brian A. Lantz, brian@lantz.com v0.08, 25 May, 1997 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 dynami- cally changing document. This document is NOT meant to deal with for- warding 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 Pro- ject (TDP), reflects a complete description this file format for TNOS Release 2.22 and later. ______________________________________________________________________ Table of Contents: 1. THE FORWARD.BBS FILE 2. COMMENTS 3. BBS ENTRY DEFINITIONS 4. FILE DIRECTIVES 4.1. File Inclusion Directive 4.2. Conditional Processing Directives 4.2.1. Use of Conditionals 4.2.2. Supported Conditionals 5. BBS ATTRIBUTES 5.1. Syntax for Attributes 5.2. Simple Attributes 5.3. Compound Attributes 5.3.1. The SCRIPT Attribute 5.3.2. Supported SCRIPT Commands 5.3.3. The AREAS Attribute 5.3.3.1. Format of the AREAS Attribute 5.3.4. The AREAS Attribute's 'ALT' Parameter ______________________________________________________________________ 1. 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. (-- 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 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. 2. 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 NOT be obvious to you. All comments are ignored by the forward file parser. 3. 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) ....... 4. 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. 4.1. 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. (-- The file inclusion directive was added in TNOS 2.02pl2, and can be found in any release after that release.--) 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 } 4.2. 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. 4.2.1. 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. 4.2.2. 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'. (-- 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.--) 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. (-- The MODE conditional directive was added in TNOS 2.02pl1, and can be found in any release after that release.--) if DAYOFWEEK = xx (or: if DAYOFWEEK = xx-yy) checks to see if the current day of the week is acceptable. If the first form of this conditional is used, it must be the given day of the week. If the second form is used, then the current day of the week must be within the range specified. The values are numeric. Sunday is 0, and Saturday is 6. (-- The DAYOFWEEK conditional directive was added in TNOS 2.20, and can be found in any release after that release.--) 5. 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. 5.1. 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. 5.2. 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). ALWAYSUPDATE = [YES | NO] determines whether or not the 'laston' time will always be updated on connection. If this is set to 'NO' then the 'laston' value is only updated when a value SID has been exchanged between the two PBBSs (or TNCs). This should normally be set to 'NO', and should only be needed if you are communicating with an extremely dumb TNC's messaging system, which does NOT use SID's on startup. The default for this attribute is 'NO'. (-- The ALWAYSUPDATE attribute was added in TNOS 2.22, and can be found in any release after that release.--) 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'. (-- The BULLETINS attribute was added in TNOS 2.02pl2, and can be found in any release after that release.--) 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 callsign [optional digis] for an ax25 connection (with optional digis). o connect callsign [optional digis] for an alternate way of specifying an ax25 connection (with optional digis). o netrom for a netrom connection o telnet 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 NO default for this attribute. DUMBPMS = [YES | NO] indicates that this 'PBBS' is actually a TNC with a dumb PMS (dumb meaning that it does NOT send a 'SID' upon connection). This should ONLY be used if (indeed) this is a dumb PMS, since it disables some code which prevents the possibility of duplicate messages entering your TNOS. Before using this attribute, use the 'forward trace' command, to ensure that the SID is not being sent by the TNC. If it IS being sent, but TNOS is not seeing it, then you have a flawed SCRIPT section, which is eating the needed SID. This should normally be set to 'NO', and should only be needed if you are communicating with an extremely dumb TNC's messaging system, which does NOT use SID's on startup. The default for this attribute is 'NO'. (-- The ALWAYSUPDATE attribute was added in TNOS 2.22pl2, and can be found in any release after that release.--) 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 nego- tiation, 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. (-- The LIMITTIME attribute was added in TNOS 2.11al, and can be found in any release after that release.--) 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. (-- The LIMITTYPE attribute was added in TNOS 2.02pl2, and can be found in any release after that release.--) 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. (-- The MINIDLE attribute was added in TNOS 2.11al, and can be found in any release after that release.--) 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'. (-- The PERSONALS attribute was added in TNOS 2.02pl2, and can be found in any release after that release.--) 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'. 5.3. Compound Attributes There are two attributes that do not define simple variables, but instead define attribute lists. There are currently only two compound attributes. 5.3.1. 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 } 5.3.2. 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. 5.3.3. 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 processing WITHIN the Attribute, it is acceptable to have several AREAS attributes that are totally contained WITHIN conditional processing. Multiple AREAS attributes (if defined) are appended in the order found. 5.3.3.1. 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. 5.3.4. 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.