BinkleyTerm ST 3.00 - User Guide **** * * * ******* TM * * * * * * * * * ** * * * *** * * * *** * ** *** ** **** * ** * * * * * * * * * * * ** * * * * * * * * *** * **** * * * **** * * * * * * * * * * * * * * * * * * * * * **** * * * * * * **** **** * **** * * * * * Version 3.00 ST - User Guide * November 30th 1991 *** A Freely Available FidoNet Compatible Electronic Mail Interface and Dumb Terminal Package Software Written by Vince Perriello and Bob Hartman Atari-ST version by STeven Green. User Guide written by STeVeN Green Based on Documentation Written by Alan D. Applegate Documentation Recompiled by Robert Elsinga This document Copyright (C) 1991, Steven Green. Portions of the documentation (C) 1988,1989 Bit Bucket Software, Co. Software Copyright (C) 1988,1989,1990,1991 Bit Bucket Software, Co. A Delaware Corporation All Rights Reserved Portions of the software (C) 1990,1991 Steven Green Terms and Conditions Contained Separately Bit Bucket Software, Co. 427-3 Amherst St., Suite 232 Nashua, NH 03063 "BinkleyTerm" and "Freely Available" are trademarks of Bit Bucket Software, Co. User Guide - Page 1 BinkleyTerm ST 3.00 - User Guide Contents 1. General Information........................................... 4 1.1 How to use this manual? 4 1.2 Acknowledgements 4 1.3 Background 4 1.4 Forward 5 1.5 Introduction 6 1.6 Hardware and Software Requirements 7 1.6.1 Memory Requirements 1.6.2 Modem Requirements 2. Operation as a Terminal Communications Program................ 9 2.1 Terminal Mode Overview 9 2.2 Installation 9 3. Operation as an automated Electronic Mailer...................10 3.1 Unattended Mode Overview 10 3.2 Installation 11 3.3 The BinkleyTerm Concept 12 3.4 How BinkleyTerm handles mail 12 3.5 The Concept of Cost 15 3.6 Windowed Interface 15 3.6.1 Current Settings 3.6.2 Today at a Glance 3.6.3 Pending Outbound Mail 3.6.4 Recent Activity 3.6.5 Transfer Status 3.7 Controlling BinkleyTerm with Batch Files 17 3.7.1 Errorlevels 3.7.2 What errorlevels BinkleyTerm Produces 3.7.3 A bit more about errorlevels 3.7.4 Shell commands 3.7.5 Environment Variables 3.8 Configuration File 22 3.9 Nodelist 22 3.10 Fidouser.lst 23 3.11 Multiple Zones and Domains 23 3.12 Point Systems 24 3.13 Security 25 3.13.1 Prot 3.13.2 Known 3.13.3 Default 3.13.4 Session Passwording 3.13.5 Secured Inbound File Areas 3.13.6 Controlling File Requests 3.13.7 Response File Templates 3.14 BBS Interface 30 3.14.1 BBS Exit 3.14.2 BBS Spawn 3.14.3 BBS Batch 3.14.4 What this really means? User Guide - Page 2 BinkleyTerm ST 3.00 - User Guide 3.15 External Mail Programs 32 3.16 User Selected BBS Functionality 33 3.17 File Requests 34 3.17.1 Update Requests 3.17.2 Request Response Files 3.18 Function Requests 38 3.18.1 $ Function Requests 3.18.2 + Function Requests 3.18.2 Function Requests Notes 4. Utilities to use with BinkleyTerm-ST..........................41 4.1 Mail Processing 41 4.2 BinkleyTerm shells 42 4.3 CLI/Shells 42 4.4 BBS Software and Utilities 42 4.5 Nodelist Processing 43 4.6 Other Utilities 43 5. BinkleyTerm Support and Problem Solving.......................44 5.1 Trouble Shooting 44 5.1.1 Baud Rate Locking Trouble 5.1.2 Outward Dial aborting 5.1.3 False Call Collision Reports 5.1.4 BinkleyTerm Will Not Recognize Node Addresses 5.1.5 Zone Support Does Not Operate Correctly 6. Glossary......................................................47 User Guide - Page 3 BinkleyTerm ST 3.00 - User Guide 1. General Information 1.1 How to use this Manual? The documentation for BinkleyTerm is supplied in two parts: - The User's Guide (BT_USER.DOC) explains how to install BinkleyTerm. It also describes basic operational procedures. New users may find some concepts or terminology unfamiliar; a glossary is provided towards the end of the User's Guide. - The Reference guide (BT_REF.DOC) is an alphabetically arranged manual listing all configuration commands and other information that may be of interest to experienced users and new users alike. For inquiries, questions or comments regarding BinkleyTerm, please refer to the User's Guide section "BinkleyTerm Support". Some portions of the User's Guide are from the original BinkleyTerm 2.30 User's Guide and are Copyright (C) Bit Bucket Software, Co. and Alan D. Applegate. 1.2 Acknowledgements Many trademarks, registered trademarks and references to other people's copyrighted works are referred to in this document. It would be very lengthy and tedious to list them all. Failure to identify a particular trademark in this document is not intended in any way to be a claim of rights to the trademark. Please note that throughout this documentation, the mention of any particular software package or system should not be construed as an endorsement of any kind on the part of the authors. 1.3 Background BinkleyTerm-ST began life in Spring 1990, as a faithful port from the PC version of BinkleyTerm 2.40. It was well received within the ST community and became one of the top two popular FidoNet compatible mailers for the ST ("The Box" of course being the other one). Users soon started suggesting new features that they would like to see, many of which have been implemented. Some of these features include the EMSI protocol, file requesting limits by time, multiple point and zone addressing, etc. There are still many more to be implemented in future versions. As a result the Atari version is now quite a bit different from the PC version and some of its new features are yet to be seen in the latest PC version (2.50). User Guide - Page 4 BinkleyTerm ST 3.00 - User Guide 1.4 Forward There is no question that BinkleyTerm-ST is an extremely powerful communications tool. We have also made no secret of the fact that BinkleyTerm-ST is an extremely complex communications tool. A set of documentation the size of an unabridged dictionary (about 150mm thick or so) would still not address every possible use of BinkleyTerm- ST in every possible environment. BinkleyTerm-ST will work on several models of computer and hundred's of different modems. In addition BinkleyTerm is designed with an open architecture, so it can be used with several BBS packages, nodelist processors, mail processors, editors and so on. BinkleyTerm "ports" have been made for entirely different platforms such as the PC, Amiga, Archimedes, Vax, etc. You begin to get the scope of what's involved. This documentation attempts to cover fairly broad generalities in configuring and operating BinkleyTerm. It cannot and will not cover all possibilities or circumstances. Hopefully it will serve as a starting point - a ground level from which you may grow and expand. Further, this documentation describes only the Atari ST version 3.00 of BinkleyTerm, earlier versions and those on other hardware platforms are different and use different configuration options. Most of the enjoyment of the electronic mail hobby comes from trying new things - tweaking the system. Although BinkleyTerm is a dependable, powerful program that is not especially difficult to get going, it does provide ample opportunity to experiment and have fun. Still, if you're looking for something that will meld itself into your computer in just a few minutes and work without modification forever more, BinkleyTerm should probably not be your first choice. In exchange for a little complexity, we give you power and an incredible amount of configurability and compatibility. If you become frustrated with BinkleyTerm, call on others in your area who are using it and ask them to help you out. Of course, you will eventually become an expert yourself! Enjoy it, and delight in the wonder of technology. Alan D. Applegate Vice President, Bit Bucket Software, Co. (With minor editing by STeVeN Green) User Guide - Page 5 BinkleyTerm ST 3.00 - User Guide 1.5 Introduction BinkleyTerm-ST is an advanced, state-of the-art telecommunications tool. It is primarily designed for the semi-automated sending and receiving of electronic mail and files within FidoNet compatible electronic mail networks. When used as a mailer, BinkleyTerm is designed to communicate with any FidoNet compatible mail interface or BBS package. The program uses standard FidoNet protocol, as well as certain modified protocols supported by programs such as SEAdog, Opus-CBCS, D'Bridge and FrontDoor. It also offers easy to use event scheduling, single keystroke spawning to other programs, support for high speed modems, advanced session recovery, inbound call collision detection, and much more. When used as a dumb terminal, BinkleyTerm offers a rich selection of file transfer protocols for exchanging files with a host system. The program also offers keyboard macros, optional VT-100 emulation, echoing of on-line session to a text file or printer, support for baud rates of 300 to 38,400 (with hardware patch to an ST) and more. BinkleyTerm can be used as a dumb terminal program exclusively, as a mail interface for a Point system, or as a front end mail interface for an electronic bulletin board system (BBS). Mail interface and dumb terminal operations can be switched in and out with a minimum of effort providing dual functionality. BinkleyTerm endeavours to provide you with the widest possible variety of advanced features, combined with solid and efficient operation. User Guide - Page 6 BinkleyTerm ST 3.00 - User Guide 1.6 Hardware and Software Requirements - An Atari ST/STe/TT/MegaSTe with at least 300K of free RAM (a 1 Meg machine (e.g. 1040ST) is really recommended to make full use of it). - TOS 1.0 or greater - An auto-dial, auto-answer modem; Hayes compatibility is recommended (see section 1.7 "Modem requirements" below). - A single sided disk drive (terminal mode) - A double sided disk drive (for point systems that don't need a nodelist) - A Hard disk for Nodes and point systems that use a nodelist. The bigger the better!!! - Basic knowledge of computer based telecommunications. - Various utility programs depending on your application, these will be described later. 1.6.1 Memory requirements BinkleyTerm requires approximately 200K of RAM in any operational mode. When used in unattended (mailer) mode additional memory sufficient to hold the nodelist index file (usually NODELIST.IDX) is required. A minimum of a 1 Meg machine is recommended if you are using BinkleyTerm from within a BBS program such as ///Turbo Board, or if you wish to spawn out to other programs from within BinkleyTerm. When used as a front-end mailer for a BBS system such as QuickBBS-ST, it is highly recommended that the 'BBS Batch' method of accessing your BBS be implemented for the most efficient use of memory. Please refer to the applicable sections of the documentation for further information. 1.6.2 Modem Requirements A modem that is generally "Hayes compatible" is required for BinkleyTerm operation. Most popular modems meet this requirement. Since you configure the various modem commands, it does not need to be 100% Hayes "AT" command set compatible, but it does need to use the "AT" style of issuing modem commands. Most modems are capable of returning VERBAL (full words) or NUMERIC (numbers only) response codes; the modem must be configured for VERBAL codes only (typically "AT V1" on most Hayes compatible modems). BinkleyTerm has been programmed to respond to the following modem response strings: NO ANSWER, BUSY, RING, VOICE, NO DIAL TONE, NO DIALTONE, ERROR, NO CARRIER, DIAL TONE and DIALLING. Also the following are recognised but ignored: RING, RINGING and RING RESPONSE. With the exception of the CONNECT response, any other data provided by the modem after a given response string is ignored. For example, "NO CARRIER DETECTED" would be handled the same way as "NO CARRIER". User Guide - Page 7 BinkleyTerm ST 3.00 - User Guide Since BinkleyTerm uses the CONNECT string to determine connection baud rates, the modem should be capable of sending such strings. Generally, CONNECT is a default, and indicates a 300 baud connection. Other possible connections are CONNECT 1200 for a 1200 baud connection, etc. BinkleyTerm also recognises the responses CONNECT 1275 and V23.CONNECT for split-speed modems. In addition extra information such as /Arq, /Hst, /V32, /V42/ etc, are recognised for use with the modemtrans feature (see the reference guide). To obtain the correct responses from a Hayes compatible modem, you would typically use the AT X command, e.g. "AT X4". If you are experiencing modem difficulties then try some of the following configuration file statements: SlowModem, SameRing, NoCollide. Also try changing the 'answer' statement. Refer to the reference guide to see what these do. You're best chance though of sorting it out is to locate someone else using the same type of modem with BinkleyTerm and ask for help. User Guide - Page 8 BinkleyTerm ST 3.00 - User Guide 2. Operation as a Terminal Communications Program 2.1 Terminal Mode Overview This section describes the installation and operation of BinkleyTerm in Terminal mode. BinkleyTerm's Terminal mode offers functionality similar to other programs such as Uniterm, Flash, Dterm, etc. You can use your computer and modem to call out to on-line services and electronic Bulletin Board Services (BBS). BinkleyTerm offers a wide selection of file transfer protocols for exchanging files with remote systems (uploading and downloading), including Xmodem, Ymodem and Zmodem. This includes Zmodem auto-detect and Zmodem error-recovery. 2.2 Installation - Create a new folder on your hard disk or format a blank disk. - Copy the following files into the folder or onto the disk: BT.TTP BINKLEY.CFG BINKLEY.LNG - Using a text editor (e.g. Tempus or MicroEmacs) or word processor in ASCII mode (e.g. 1st Word), edit BINKLEY.CFG to reflect the way your system is setup. Refer to the comments included in the provided BINKLEY.CFG and the Reference Guide. In particular you should make sure that the "Unattended" line is deleted or commented out. You may also need to create a DOWNLOAD directory depending on what you set the "DownLoad" line to in BINKLEY.CFG. - Double click on BT.TTP and press return at the TTP dialogue box. - Press the Help key for a brief help screen. User Guide - Page 9 BinkleyTerm ST 3.00 - User Guide 3. Operation as an automated Electronic Mailer 3.1 Unattended Mode Overview This section describes the installation and use of BinkleyTerm in Unattended mode. This mode is used when BinkleyTerm is to function as a front-end mail interface, whether in a BBS or "Point" environment. The glossary provides information on BBS and Point systems. BinkleyTerm, in this operational mode, provides functionality similar to that provided by The Box, and by programs such as FrontDoor and D'Bridge on the PC, and by Trapdoor on the Amiga, and other FidoNet compatible mailers. BinkleyTerm answers the telephone, and exchanges mail with other compatible mail interface packages, or in the case of a human caller, passes control to a BBS system. User Guide - Page 10 BinkleyTerm ST 3.00 - User Guide 3.2 Installation Due to the complexity and widely varying setups, only a generalised broad installation procedure is given here. For more information you will need to read the reference guide and maybe ask for help from other systems running BinkleyTerm. The use of a BinkleyTerm shell program such as BTS (Part of the ACS package) or Avalon will simplify the installation. You should refer to the instructions included with these utilities. These utilities and others that can be used with BinkleyTerm will be described later in this User Guide. - Create a new folder on your hard disk or format a blank disk. - Copy all the files from this distribution into the new folder or disk. - Using a text editor (e.g. Tempus, MicroEmacs or STedi) or a word processor in ASCII mode (e.g. 1st Word), edit the file BINKLEY.CFG. Refer to the comments in the provided BINKLEY.CFG and to the reference guide for guidance. - Create any folders that you have specified in BINKLEY.CFG, these will include: Netfile Hold DownLoad Nodelist - Obtain and setup any necessary utilities for packing and unpacking mail. Install them as explained in the instructions with these packages. - Obtain a current nodelist and process it (e.g. with ParselST). This is not required if you are a point system and have setup BINKLEY.CFG correctly. - Edit BINKLEY.EVT according to how you wish your system to run. (Refer to the reference guide for information). - Set up any batch files or shell programs to control how BinkleyTerm is to work. - Start your system. Test a remote call if possible. - Pressing the Help key will display a brief help file of commands available in unattended mode. Setting up can be quite a complex procedure, it is best if you read all the documentation thoroughly, obtain some example configuration files from someone else with a similar setup, don't be afraid to experiment and set it up a bit at a time. User Guide - Page 11 BinkleyTerm ST 3.00 - User Guide 3.3 The BinkleyTerm Concept It is important to remember that BinkleyTerm is a mailer program with a completely open architecture. As such, BinkleyTerm can be operated with a tremendous variety of BBS systems, mail packing and unpacking programs, and accessories. BinkleyTerm will answer the telephone and respond to another mail program. Mail will be placed in an incoming files area. If the caller is human, control is passed entirely to the BBS program, if one is installed. It is the responsibility of third-party software to unpack the mail received, and add it to your message base. On the outward side, BinkleyTerm uses an outbound holding area to hold outward mail. It is the responsibility of third-party packing software to pack new messages into the required format, and place them in the outbound area. BinkleyTerm neither packs nor unpacks mail. Allowing this functionality to be provided by other software allows BinkleyTerm to be compatible with practically any BBS software, regardless of message base structure. Some of the other utilities that can be used with BinkleyTerm will be described later on in this document. 3.4 How BinkleyTerm handles mail Understanding a bit about how BinkleyTerm handles outbound mail may help you to understand how to use it better. It will not matter if you don't understand everything in this section, but reading it quickly now and then referring to it later if you have a problem may help you if you get stuck. The driving forces of outbound traffic are filenames. You will have set up some special folders for outbound packets using the "Hold" configuration line in BINKLEY.CFG. If you are using multi-zones then you will have several folders, one for each zone, and if you are using Domains then you will also have separate directories for each zone within each domain. See the reference guide for information. User Guide - Page 12 BinkleyTerm ST 3.00 - User Guide Example, if you are in Zone 2 and in BINKLEY.CFG, you have the lines Hold c:\bt\hold Domain Fidonet.org FidoNet nodelist Domain nest.ftn nest nestlist Domain Lifenet.ftn lifenet lifelist Then you will have the folders: c:\bt\hold Default folder for zone 2 (Europe) c:\bt\hold.001 Zone 1 (North America) c:\bt\hold.003 Zone 3 (Australasia) c:\bt\hold.004 Zone 4 c:\bt\hold.005 Zone 5 c:\bt\hold.006 Zone 6 (East Asia) c:\bt\nest.05a NeST zone 90 (Note "5A" is 90 in base 16) c:\bt\lifenet.04d LifeNet zone 77 ("4D" is 77 in base 16) Your mail exporting program will place netmail packets, compressed mail packets and other network files in these folders for BinkleyTerm to send. The filenames of the packets tell BinkleyTerm how to treat the different packets. A typical packet might have the name: 00FC0019.OUT This tells BinkleyTerm that it is intended for node 252/25. (00FC/0019 in Hexadecimal). The ".OUT" extension means that it is an uncompressed netmail packet. Packet extensions are: .HUT Uncompressed packet, to be left on Hold for the other system to pick up. .CUT Uncompressed packet to be sent to another system using Crash or Continuous mail (i.e. it should be sent immediately). .DUT Uncompressed packet to be sent Direct. Exactly when it can be sent is controlled using BinkleyTerm's event file BINKLEY.EVT. .OUT Normal uncompressed packet, treated identically to DUT. Some utilities will change the extensions for you at different times of the day so that you only send mail at particular times. Refer to the instructions about "Routing" in the documentation for your mail exporter. User Guide - Page 13 BinkleyTerm ST 3.00 - User Guide Files and compressed mail can be sent using File attach or FLO files. These have a similar naming convention to the .OUT files: .FLO Normal flow file .HLO Flow file on Hold .CLO Crash or Continuous flow file .DLO Direct flow file A flow file is an ASCII text file listing the files to be sent to another system. Each filename may also have a special character preceding it. Example, #c:\bt\hold\0000fc9c.mo1 ^c:\myfiles\wizzle.doc c:\pascal\notes.doc The '#' tells BinkleyTerm to truncate the file after it is sent, i.e. set it to zero bytes length. This option is sometimes used for archived mail to prevent duplicate filenames. '^' tells BinkleyTerm to delete the file after it is sent. This is also used for compressed mail to avoid filling up your outbound areas, as well as for temporary files (e.g. TIC files). Other special characters include ';' A comment. BinkleyTerm ignores the rest of the line. '~' File has already been sent. BinkleyTerm sets this as it sends each file so that if the session is aborted it doesn't send the same files on the next call! When using IOS another file-type for compressed mail is used, these are: .OAT Normal Archived Packet .HAT Held Archived packet .DAT Direct Archived packet .CAT Crash/Continuous Archived Packet. The Archived mail address is encoded differently to allow for point addressing. This takes the form: aaabbbcc.OAT aaa = The Net encoded as base 36. bbb = Node in base 36 cc = Point in base 36. e.g. a packet for 252/25.10 would be called: 07000P0A.OAT (070 = 252 in base 36, 00P = 25, 0A = 10). The advantages of this format is that it enables points to call points from other point networks directly instead of having to go through their boss. Another advantage is that you don't need to use FLO files, resulting in less clutter in the outbound folders and less time for BinkleyTerm to find the files. Future versions of BinkleyTerm-ST will extend this format to include file requests and unarchived mail. User Guide - Page 14 BinkleyTerm ST 3.00 - User Guide 3.5 The Concept of Cost One of the prime considerations with BinkleyTerm is sending mail for the least cost. Cost is, of course, determined by the nodelist entry. With a properly compiled nodelist, local FidoNet nodes have '0' in the cost field for their nodelist entry (assuming local calls are free of charge). Other entries have cost fields that realistically reflect the actual cost of sending mail to a particular node. In most areas, it is cheapest to call during the evening or nighttime. Therefore, BinkleyTerm is normally set-up to send such mail only during nighttime hours. The 'L' flag used when scheduling events designates 'local only.' As already mentioned, nodes with a '0' cost field are assumed to be local. When the flag is applied to an event, only local calls are made. The 'L' flag should be used whenever it costs the most money to make calls, and removed for events during which calls are cheapest. More about this is in the Reference Manual section, "Scheduling Events." 3.6 Windowed Interface BinkleyTerm features a windowed user interface. The windowed interface provides "at-a-glance" convenience for watching mail sessions in progress, as well as determining what activity has taken place with the system recently. There are 5 important windows displayed on the screen. 3.6.1 Current Settings This window contains various information about your system, including the current data and time, current event, current baud rate, status and amount of free memory. The current event line features a number and a list of event flags. The number corresponds to which entry in the BinkleyTerm event file BINKLEY.EVT covers the current event. The flags are letters that are a subset of those used with event scheduling. Here is a list of letters that may be found in this window: C Continuous Mail Only Event L Local Only Event N Do not accept Inbound File Requests R Receive Only Event B BBS Use Allowed D Dynamic Event K Do Not Send Continuous/Crash Mail. See the section "Scheduling Events" in the Reference Guide for more information about these flags. User Guide - Page 15 BinkleyTerm ST 3.00 - User Guide 3.6.2 Today at a Glance This window contains several lines of information regarding the activity on your system since midnight. Note that the totals given apply only to calls handled by BinkleyTerm's Unattended (mailer) mode, and do not include Terminal Mode totals. The 1st line, "BBS/Mail", lists how many BBS calls, mail calls and external mailer calls have come in separated by a slash '/'. For example 2/15/1 would indicate 2 BBS callers, 15 mailer calls and 1 external mailer call (an external mailer could be a UUCP mailer, a FoReM FNET mailer, etc). The 2nd line, "Calls Out", lists the number of dial attempts that have been made by your system, successful or otherwise. The 3rd line, "Good/Cost", shows how many successful calls have been made and the cumulative cost of them all. For example, 3/100 would indicate 3 successful calls, which have cost 100 units (if you have set up the cost table correctly [in ParselST.cfg or BINKLEY.CFG] then this should correspond to actual currency, e.g. cents in America, pence in UK). The cost calculation assumes that the amounts given in your cost table are in cost-per-minute. The 4th Line, "Files I/O", shows how many files have been received and sent, e.g. 12/3 indicates that you have received 12 files and sent 3. Finally the 5th line indicates the last session. If it was another FidoNet mailer then the other system's address will be displayed, otherwise it might indicate that it was a BBS caller or external mailer. 3.6.3 Pending Outbound Mail This window displays a list of systems for whom mail is waiting along with related information. The window can be scrolled using the cursor arrow keys. Up Up one line Down Down one line Shift-Up Up a page Shift-Dn Down a page Home To top The nodes are sorted in numerical order, but systems that are waiting to be called are listed first. The actual information displayed depends on whether you have the "NiceOutbound" configuration command in BINKLEY.CFG (this can be toggled by pressing Alt-F). User Guide - Page 16 BinkleyTerm ST 3.00 - User Guide With NiceOutBound disabled then all you get is the system name and flags indicating the status of mail for that system: C Crash/Continuous H Hold D Direct N Normal R File Request - System will not be called during this event. There may instead be a message: NoConn BinkleyTerm could not connect to this system Tried BinkleyTerm has called, but mail is still waiting. UnKnown System is not in NodeList When NiceOutbound is enabled then the number of files, size and age of the files are displayed. The disadvantage of using this option is that it can take BinkleyTerm some time to scan all the outbound folders for this information. Pressing Alt-Z zooms the pending Outbound Window to fill up the screen, where even more information is displayed, including the number of calls made to each system. 3.6.4 Recent Activity This window displays information about what BinkleyTerm is doing, as it happens. This information will also be written to the log file depending on the current "LogLevel" setting. 3.6.5 Transfer Status During file transfers, this window displays information about the transfer, such as the filename and how many bytes have been sent. 3.7 Controlling BinkleyTerm with Batch Files Point systems or mail-only nodes may be able to use a Graphical shell program such as BTS (part of the ACS package) or Avalon. These are GEM based programs that let you set up and control BinkleyTerm. You should refer to the documentation provided with these programs for more information and you can probably skip the rest of this section. BBS systems and more complex nodes will need to use batch files to control BinkleyTerm's operation. Typically these will be used to run BinkleyTerm, load up the BBS for human callers, run mail processing utilities after a call, etc. You will first of all need to find a CLI or shell program. There are two types of CLIs: MSDOS style and Unix style. Some people prefer one or the other. If you are using FoReM or ///Turbo-board then there is an MSDOS style shell built into the BBS. Users of other BBS systems (e.g. QuickBBS) must use a separate CLI. Example CLIs that may be used include: Pcommand : Very basic MSDOS style CLI. Craft : Very good commercial Unix style shell. User Guide - Page 17 BinkleyTerm ST 3.00 - User Guide There are others that may possibly be used, but I don't have experience of using them with a BBS. Basically any shell or CLI that will run batch or script files, has conditional flow control and supports errorlevels and environment variables should work. You should probably ask someone near you what they use. If you are not familiar with CLIs and Shells then it is highly recommended that you find someone nearby to provide you with their batch files. 3.7.1 Errorlevels One of the basic concepts of using batch files to control BinkleyTerm is that of errorlevels. An errorlevel is simply a numerical value that a program may "return" when it terminates. A better term might be an exit code, as it does not necessarily mean that there has been an error if it set! Batch and script files can make use of the errorlevel to decide what to do next. If you are using an MSDOS style shell (e.g. PCOMMAND or ///Turbo board's built-in shell) then you can use batch files such as: :start myprog -p1 IF ERRORLEVEL 2 goto process IF ERRORLEVEL 1 goto start IF ERRORLEVEL 0 goto end :process proc -c -d1 IF ERRORLEVEL 1 goto start IF ERRORLEVEL 0 goto end :end I'm sure you can work out what this batch file will do. If not refer to the documentation that came with your CLI or shell. What will happen is that the program "myprog" is executed, and then when it exits control will pass to a different part of the batch file depending on the exit code. User Guide - Page 18 BinkleyTerm ST 3.00 - User Guide If you are using a Unix style shell then you should refer to the documentation that comes with it. A typical method of getting the errorlevel is from the variable $status, e.g. the above example as a Craft script file might be something like: while ( 1 ) myprog -p1 switch ( $status ) case 2: proc -c -d1 if ( $status == 0 ) exit breaksw case 0: exit endsw end 3.7.2 What errorlevels BinkleyTerm Produces There are 4 general types of errorlevel: Sysop-Initiated Function keys and Alt-X. Pressing a function key causes BinkleyTerm to exit with a value of 10 times the function key number. e.g. F1 returns 10, F2 return 20, etc, F10 returns 100. Alt-X causes a value of 1 to be returned. Sysop-Defined En= exits used with event scheduling (See reference Guide), external mail exits (see "ExtrnMail" in the reference guide), Caller-Initiated A non-mail caller returns the baud rate divided by 100 (e.g. 300 baud returns 3, 2400 baud returns 24, etc). NOTE: Some MSDOS style shells may restrict errorlevels to between 0..255 in which case 38400 baud returns 128 (384-256) instead of 384. System-Generated BinkleyTerm cannot run for some reason (e.g. it cannot find itself in the nodelist). User Guide - Page 19 BinkleyTerm ST 3.00 - User Guide The following errorlevels are hard coded into BinkleyTerm, but the others may be defined by yourself using the configuration files: Error- Level Means Caused By -------- ----------------- ----------------------------------------- 1 Exit Alt-X Keypress 3 300 bps Call Non-mail call at 300 Baud 10 ** F1 key pressed 12 1200 bps Call Non-mail call at 1200 baud 20 ** F2 key pressed 24 2400 bps Call Non-Mail call at 2400 baud 30 ** F3 key pressed 40 ** F4 key pressed 48 4800 bps Call Non-Mail call at 4800 baud 50 ** F5 key pressed 60 ** F6 key pressed 70 ** F7 key pressed 72 7200 bps Call non-Mail call at 7200 baud 80 ** F8 key pressed 90 ** F9 key pressed 96 9600 bps Call Non-Mail call at 9600 baud 99 ExtrnMail Default External mailer return code 100 ** F10 key pressed 120 12000 bps Call Non-Mail call at 12000 baud 128* 38400 bps Call Non-Mail call at 38400 baud 144 14400 bps Call Non-Mail call at 14400 baud 192 19200 bps Call Non-Mail call at 19200 baud 254 Error Address not found in NodeList -2* Error Address not found in NodeList 255* Error General error -1* Error General error 384* 38400 bps Call Non-Mail call at 38400 baud * Some shells may only allow errorlevels between 0 and 255. In these cases values greater than 255 will be logically ANDed with 255, thus -1 becomes 255, -2 becomes 254 and 384 becomes 128 (384-256). Refer to your shell's documentation to find out if this happens. The Craft Shell will return the full value (i.e. 384 for 38400 baud), but I don't know about any others. ** The functionality of function keys is entirely up to you. 3.7.3 A bit more about errorlevels By using the En= errorlevels associated with BinkleyTerm's event handling, you can control how your system works. If you want something to happen a particular time each day, then select a unique "E1=" exit code for that task. The task can be set to occur periodically throughout each day, once-per-day, once-a-week or on selected days within the week. Similarly by having a variety of E2= and E3= codes, you can use different mail unpacking routines at different times. Refer to the section "Scheduling Events" in the Reference Guide for details. User Guide - Page 20 BinkleyTerm ST 3.00 - User Guide The 10 F-keys errorlevels can be quite handy to run often used utilities, e.g. to run an editor, Binkley-Shell or to load NeoDesk. The external mailer option is intended for invocation of an external mail handling program such as a UUCP mailer or the FoReM FNET mailer. It is invoked by receiving a predefined string of characters. It can also be used to set up multiple BBS installations, allowing which BBS is loaded to be selected by the user. This is covered in more detail in the sections "External Mail Programs" and "User Selected BBS functionality" elsewhere in this document. 3.7.4 Shell Commands Shell commands are programs or batch files that are run from within BinkleyTerm. These include 10 shell commands invoked by pressing Alt- Function keys, and defined using the "Shell" command in BINKLEY.CFG, as well as the "Editor", "Packer", "Aftermail" and "Cleaner" commands. The behaviour of shell commands depends on what type of shell you are using. If the command is the full pathname of an executable program (i.e. it ends in .PRG, .TOS or .TTP) then it will be executed directly by GEMDos. Otherwise, if you are using a resident shell that can be called through the shell_p vector at 0x4f6, then your command will be executed directly by the shell (Craft and Gulam will work like this). If your shell sets the COMSPEC or SHELL environment variables then the shell will be invoked as either "$COMSPEC /c commandline" or "$SHELL -c commandline". Because shell commands are executed from within BinkleyTerm, there will be less memory available than when using errorlevels. 3.7.5 Environment Variables Environment variables should be set up in your startup batch file. Refer to the section about environment variables in the reference guide. In particular it is a good idea to set BINKLEY to point to where BinkleyTerm's data files are located and also RXBUF and TXBUF. The COMSPEC and SHELL variables are normally defined by the shell program, so you shouldn't need to set these yourself. Different shells define these in different manners, refer to your documentation for more details about setting environment variables. e.g. set BINKLEY = f:\bt set RXBUF = 8192 set TXBUF = 512 or alternatively: setenv BINKLEY f:\bt User Guide - Page 21 BinkleyTerm ST 3.00 - User Guide 3.8 Configuration File Most BinkleyTerm parameters are set through a configuration file. By default, the configuration file is named BINKLEY.CFG, and is expected to be available unless a different configuration file is specified on the command line. A sample BINKLEY.CFG files is included with the distribution package. You can edit the file with any plain text editor such as Tempus, MicroEmacs or Craft's STedi; or with a word processor in ASCII mode such as 1st Word. The Reference Guide contains a complete listing of all BinkleyTerm configuration statements and their proper use. It is recommended that you read through each statement's description and decide if you need it or not. BinkleyTerm directly uses the raw configuration file, and each time the program in invoked, BinkleyTerm will scan and process the file, setting internal values to those that you have selected. 3.9 NodeList The FidoNet Nodelist is the glue that holds FidoNet together. It is vitally important that all nodes keep up to date with the latest nodelist. Most of the FidoNet coordinator positions are there for the purpose mainly of updating and distributing the nodelist. Because the nodelist is very big (just over 1 Megabyte with about 12000 systems at the time of writing) it is not practical to distribute the entire nodelist every time it is changed, so a "NodeDiff" file is distributed each week, which contains instructions for updating from last week's list to the current one. It is the duty of your Net Coordinator to make sure that this is available to you every week. It is very important that you process the list every week and don't miss out on any of the diff files. The nodelist and nodediff's are referred to as "raw" nodelists as they are simply ASCII files. Most mailers and mail processing software require it to be processed (or compiled) into binary form so that entries can be accessed more easily. BinkleyTerm is capable of using a variety of compiled nodelist formats, but as far as the ST is concerned, the only useful format is the Version 6 format. To select this you must make sure that the line "NewNodeList" is included in BINKLEY.CFG and that your nodelist processor produces this format. At the time of writing, the only nodelist processor available for the ST that works with BinkleyTerm-ST is ParselST. However in future versions of BinkleyTerm-ST there will be support for other nodelist processors. Point systems do not require a nodelist at all as long as their bosses phone number and password are included in BINKLEY.CFG. See the section on "Point Systems" later in this document. There is also a suite of programs available for points called FIDO24 (because it was designed for REGION 24 [Germany] point systems), which can help points install smaller nodelists. User Guide - Page 22 BinkleyTerm ST 3.00 - User Guide 3.10 FidoUser.LST The nodelist processor may also be used to produce FIDOUSER.LST, a list of sysop names and node addresses, that BinkleyTerm can use when dialling out. When this file is available to BinkleyTerm (in the nodelist folder), then at most places where you can type in a node number you can instead type in a sysop's name. This applies to both Unattended and Terminal Modes, while polling or dialling a system. 3.11 Multiple Zones and Domains Zones are a high-level addressing scheme devised for use within FidoNet. In a full FidoNet address, such a 1:104/36.0, '1' would be the zone, '104' the net, '36' the node number, and '0' the point number. Currently, zone addressing is not supported within the FidoNet message or packet structure, allowing software such as BinkleyTerm to provide only "kludged" support of zones. BinkleyTerm offers such support, and endeavours to make it as seamless as possible. If for some reason you do not wish zone support to be active, place the statement 'NoZones' in your configuration file. This will cause BinkleyTerm to essentially "turn off" zone support. If you intend not to use zone support, then use the 'NoZones' configuration file statement. If you have not used the 'NoZones' statement, BinkleyTerm will assume that a full, zone-based nodelist is available for its use. For information on how to properly compile a nodelist for BinkleyTerm, refer to the section "Nodelist" for more information. When attempting to send mail to nodes in other zones, BinkleyTerm will assume that mail for other zones will be held in separate outbound areas by zone number. For example, if your outbound mail directory is C:\BT\OUTBOUND, mail for your zone will be held there. However, mail for nodes in zone 2 would be expected in C:\BT\OUTBOUND.002, mail for zone 3 would be expected in C:\BT\OUTBOUND.003, and so on. This example is for zone 1. The zone number for which your default outbound directory applies is determined by the FIRST appearance of the 'Address' statement in your configuration file. Subsequent 'Address' statements identify your alternate identities within other zones (and/or networks). For example, if the first 'Address' statement designates an address in zone 2, then the outbound area designated by the 'Hold' statement in your configuration file is the default, and mail to other zones would require their own distinct outbound areas with extensions that match the zone number. The multi-zone outbound areas are in hexadecimal. For example, the outbound area for zone 10 would be C:\BT\OUTBOUND\.00A. Using this method, it is possible to support up to 4,095 zones. User Guide - Page 23 BinkleyTerm ST 3.00 - User Guide Operation of a system within multiple networks is becoming increasingly popular. Normally, networks such as NeST, LifeNet, ChatNet and so on are implemented as separate zones. To facilitate operation of a BinkleyTerm system within multiple networks, you may specify a separate system address, each with a different zone. For example, if you wish to use a different address for FidoNet (currently zones 1, 2, 3, 4, 5 and 6) and for two alternative networks, you might have the following in your configuration file: Address 1:1010/89.0 Address 9:569/999.0 Address 11:334/1.0 If your system connects with a system in zone 9, your system will identify itself as 9:569/999. If connected with a zone 11 system, it will identify itself as 11:334/1. The first 'Address' statement is the default, and callers in zone 1 (and any zones other than 1, 9 and 11 - those specified with 'Address' statements) would find your system identified as 1:1010/89. Domain addressing adds yet another level of addressing to specify different networks. Within each network, zones and nets can all be specified without conflict to identical zones and nets in other networks. Domain support in BinkleyTerm requires that you use separate nodelist files for different domains. BinkleyTerm can now be used much more effectively in multiple network installations, assuming it is configured correctly. A full address with a domain is written like 1:234/56.7@fidonet.org, where "fidonet.org" is the domain. Other FidoNet compatible domains tend to have the extension ".ftn", e.g. "alternet.ftn". To use domains you must use the "Domain" command in BINKLEY.CFG as described in the reference manual. To process separate nodelists you will have to patch a copy of parselST.TOS to read and write different filenames. All of the nodelists must be kept in BinkleyTerm's nodelist folder and you must create the neccessary outbound folders. My advice is to only use Domain's if you have a good reason to. A lot of mail processing software does not work properly with it, and it can be quite tricky to set it up. 3.12 Point Systems Points are essentially a "system under a system" and allow the point operator to have limited access to the network without the normal requirements of keeping a system on-line at certain hours. Since point addressing is not part of the FidoNet standard, certain "Kludges" must be used in order to handle a point network. User Guide - Page 24 BinkleyTerm ST 3.00 - User Guide First of all you must find your "fakenet" address. Point systems should ask their boss. A node should theoretically ask the international coordinator to assign one, but in practice you can just make one up. For example I use 25225 (based on my node address of 252/25). In fact many mailers don't even use fakenet addresses any more and the complete 4D address is passed in the session handshake, but you will still need to define your fakenet address. Once you have your fakenet address then you must place it after your address in BINKLEY.CFG, e.g. for a node Address 2:252/25 25225 and for a point: Address 2:252/25.10 25225 where 10 is the point number assigned to you. What happens here is that in some mail sessions the addresses may be replaced by 25225/10 and 25225/0. If you are a point and you don't want to use a nodelist then you must also add your boss's phone number after the fakenet address, e.g. Address 2:252/25.10 25225 0793-849044 and define your session password with the KEY statement, e.g. Key !PASSWORD 2:252/25 It is possible to be a point in more than one system by simply defining more addresses, e.g. Address 2:252/25.10 25225 0793-849044 Address 2:250/123.31 25023 061-429-9803 Key !PWD1 2:252/25 Key !PWD2 2:250/123 Actually a lot is possible using the Key statement and it is now possible for one point to directly poll another point in a different net if required. Please read about the "Key" statement in the Reference Guide. 3.13 Security In the ideal world, we would not need locks, police, or jails; there wouldn't be crime. But we don't live in an ideal world, and for this reason, BinkleyTerm offers a selection of features that are intended to offer your system a certain level of security against "electronic mail crime." The existence of security features is not intended to evoke fear. Chances are excellent that you will have no need for security features in most cases. But just as high crime areas see more locks and iron gates than low-crime areas, the choice of how much security to put in place is up to you, and is based on your needs and experience. User Guide - Page 25 BinkleyTerm ST 3.00 - User Guide BinkleyTerm's internal security is based on a simple principle. With the exception of session passwording, for each secured feature (all of which are specified within the configuration file), there is a default statement. When you implement no security features, the default statement is used to specify a particular feature's configuration. 3.13.1 Prot When security is implemented, however, two more statements are used in addition to the default. One type of statement, known as "Prot" for "protected," describes a group of systems with which you have implemented session passwording. These links are "protected" by passwords. When session passwording is implemented, unless a password is matched when connecting to a protected system, a mail session is aborted. "Protected" or "Prot" systems are the top-level, or "most favoured" situations, since you generally know the other person at the other end (a prerequisite to establishing a password). 3.13.2 Known The second type of statement is called "Known" and describes systems that are listed in the nodelist ("known" to you) but with whom you have not established a session password. These are links with listed systems, but links that are not password protected. This group represents the middle-level of security. 3.13.3 Default When you use a Prot and/or a Known security feature, then the default statements all take on a new meaning - that of unknown systems. The defaults are used for links that are not in the nodelist, and therefore, cannot have a session password established. This group of systems represents the lowest-level of security, since you really have no idea who owns such systems, or where they are located. 3.13.4 Session Passwording BinkleyTerm supports session-level password protection. Using such protection helps prevent situations where someone uses a FidoNet mailer to 'impersonate' a legitimate FidoNet node, and pickup mail addressed to the node. When implemented, both the sending and receiving systems must have it in operation, with the same password on both ends (exceptions noted below). With Point systems, passwording can be automatic. Simply use the 'Key' configuration file option, and choose a password. Make sure your Boss also uses the same password. User Guide - Page 26 BinkleyTerm ST 3.00 - User Guide For other types of systems, password information is kept in the nodelist data file. ParseLst (and some other nodelist processors) can easily add a password to a nodelist entry during processing. Refer to the documentation for your nodelist processor. Or you can use the 'Key' configuration option to save having to recompile the nodelist! When talking with other systems that use the YooHoo or EMSI session negotiation methods, full, two-way protection is available. The systems connect and exchange the password when the YooHoo takes place. If the passwords do not match, the session is terminated, regardless of who initiated the call. The only exception is when you have a password implemented, but the remote has NO password implemented. In this case, if YOU placed the call, then a session will still occur. If the REMOTE placed the call, then the session will be aborted. When connected with SEAdog and compatible systems, password matching takes place only when you are picking up mail from the remote system. You may send to a SEAdog system without a password match taking place. (The assumption is that you always know who you're calling, but don't always know who's calling you.) Note that session passwords must not exceed eight (8) characters, and are case insensitive. When BinkleyTerm cannot find a password for a remote system when placing a call, it will not check for a password during the session. This responsibility is left to the remote system, if the remote chooses to perform checking. BinkleyTerm allows easy implementation of new passwords. Simply add the agreed upon password as outlined above, and send the remote system a message. BinkleyTerm will allow an outbound session to take place in cases where you have designated a password, but the remote has not yet implemented it. This is handy for letting a remote system know that a password was implemented. Note that in this case, BinkleyTerm will NOT allow the remote to have a successful session when the remote calls your system; only when you place the call (as stated above, the idea is that you know who you're calling, not who's calling you). 3.13.5 Secured Inbound File Areas Another method of securing the flow of mail involves controlling the processing of incoming mail to your system. In most cases, you will want to protect common mail links with session passwording, as outlined in the previous section. Still, the potential exists for another abusive system to send you rogue mail, or mail "planted" onto your system in hopes that it will be routed to another system at your expense, or find its way into a national EchoMail conference. User Guide - Page 27 BinkleyTerm ST 3.00 - User Guide The following list shows the various security levels and the configuration file statements that define their respective inbound paths: Prot 'ProtInbound' Known 'KnownInbound' Default 'NetFile' In a typical installation secured in this manner, mail will automatically be processed only if received to the 'ProtInbound' area. Mail received to 'KnownInbound' or 'NetFile' must be examined and processed manually. Of course, you could choose to configure your system in a such a manner that mail received in any of the three areas is processed automatically to your liking, possibly to special message areas. The only "hole" in this is with FSC-0001 sessions, such as those with SEAdog or Fido. Since BinkleyTerm has no way of knowing the address of the sending system until a packet is received, that first packet (.PKT file) will always be placed in the default area specified by the 'NetFile' statement. Secured inbound file areas simply provide another, extra measure of handling potential security problems associated with the reception of "rogue" or "planted" mail. 3.13.6 Controlling File Requests BinkleyTerm offers a method of establishing limitations on file requests received from systems that are not session password protected, or are not found in the nodelist. This support is optional; if you do not wish to limit file requests in this manner, use only the files and configuration file statements mentioned in the section "File Requests." The following table lists these possibilities, the file types (as described in the section "File Requests") and the respective configuration file statement used: Prot ABOUT 'ProtAbout' AVAIL 'ProtAvail' OKFILE 'ProtReqList' Maximum 'ProtReqLim' Maximum 'ProtMaxBytes' Maximum 'ProtMaxTime' Known ABOUT 'KnownAbout' AVAIL 'KnownAvail' OKFILE 'KnownReqList' Maximum 'KnownReqLim' Maximum 'KnowMaxBytes' Maximum 'KnownMaxTime' User Guide - Page 28 BinkleyTerm ST 3.00 - User Guide Default ABOUT 'About' AVAIL 'Avail' OKFILE 'Okfile' Maximum 'MaxReq' Maximum 'MaxBytes' Maximum 'Maxtime' Essentially, the default files and configuration file statements described in the section "File Requests" are used for all file requests by default unless a higher "Known" or "Prot" statement is used. Note that all file request controls apply to update requests and function requests as well. 3.13.7 Response File Templates Refer to the section "Request Response Files" for information on their operation and use. It is possible to designate separate response file templates for each of the three security levels. Generally, you won't want or need to do this unless security controls on file requests have been implemented. The security levels and their respective configuration files statements for secured response file templates are: Prot 'ProtReqTpl' Known 'KnownReqTpl' Default 'ReqTemplate' User Guide - Page 29 BinkleyTerm ST 3.00 - User Guide 3.14 BBS Interface One of the most common uses of BinkleyTerm is as a mail front-end for a bulletin board system, or BBS. BinkleyTerm offers three different methods for passing control to a BBS. The method you use is determined by a configuration file statement (refer to the Reference Guide for details). 3.14.1 BBS Exit The 'BBS Exit' option will cause BinkleyTerm to exit to the start-up batch file with an errorlevel of the baud rate divided by 100 upon receipt of a non-mail call. For example, a 300 baud caller exits to the batch file with an errorlevel of 3, a 2400 baud caller at errorlevel 24. The batch file then detects the errorlevel, and jumps to a section of the batch file you designate to start the BBS program with the required information. The batch file should recycle and restart BinkleyTerm once BBS use is terminated. 3.14.2 BBS Spawn The 'BBS Spawn' option causes BinkleyTerm to stay resident when a caller accesses the BBS. BinkleyTerm will execute the following command as a child process: spawnbbs