OS/2 Shareware BBS: 2 BBS

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / suarmp22.zip / SUARM.DOC < prev next >

Wrap

Text File | 1996-11-01 | 33KB | 723 lines

SHUT UP AND RUN THE MAIL QWK tosser for RemoteAccess 2.50+ and compatible systems By Michael Nelson and Pab Sungenis Version 2.2 1 November 1996 ------------ INTRODUCTION ------------ When they say necessity is the mother of invention, they are not exaggerating. SUARM is a perfect example of this saying translated into fact. When my BBS, Connections!, joined the Annex network in 1994, Mike Nelson (who was then the SysOp) and I had a problem on our hands. Despite our tinkering, jumping through hoops, and long distance phone calls to the author, we were unable to get MkNet to work under OS/2. Since I would have rather chewed my own leg off than put the BBS back under MSDOS, I dragged out my laptop and went to work immediately. I was fairly versed in the QWK structures (having written PabQwk, the first offline reader for an 8-bit system in 1992) and managed to have a bare-bones toss- and-scan program running in about 48 hours. Even the name we chose (taken from a tagline we had seen) reflected the slapdash attitude behind SUARM 0.1: no bells, no whistles, nothing fancy, just shut up and run the mail. A month later, I had finally added a few bells and whistles I had always wanted in a tosser, designed a user interface, written some quick documentation, and released SUARM upon the world. Two quick bug fixes followed, and the program served me well. As time went on, some inadequacies of SUARM became apparent. Since I had been working in a one-network-per-host situation, I hadn't seen a need for origin lines. My 'status reports' which had been so neat at first quickly became useless and annoying. New users had a lot of questions I didn't think would be as hard to answer as they were. And, finally, there were just more gizmos and toys I wanted. After nearly a year of preparation, version 2.0 of SUARM was ready for release. Version 2.1 of SUARM was released early in 1996 to accomodate the changes and additions to RA in the new version 2.50. And this version takes care of a few bug fixes and needed additions. For more information, take a look at the WHATSNEW.DOC file. --------- IN THEORY --------- QWK networking really began with the founding of what is now the ILink[sm] computer network. The concept grew out of Mark "Sparky" Herring's QWK offline mail format, which had allowed users to download new messages, read them offline, and upload replies. It seemed a logical next step to take one of those mail packets and import the messages into another board. The fundamental principles of QWK networking have not changed since the first transfers took place. A system calls another system, downloads a mail packet, and imports it into its own messages bases. New messages are scanned, packed, and sent as a reply packet. While not as elegant as other methods, QWK networks have the advantage of being easy to set up and (for the end user) easy to maintain. SUARM implements a number of 'additions' that have crept into QWK over the years, most notably the 'kludge' lines. While QWK headers originally only allowed 25 characters for a user name or subject line, the 'kludge' lines have expanded this limit to 60. SUARM can use these add-ons and other modifications to the format to provide the best interface between RemoteAccess (and similar systems) and QWK networks available today. ------------- SETTING IT UP ------------- If you are installing SUARM for the first time, extract it into its own directory. You may also want to add this directory to your search path, and add a SUARM environment variable pointing to this directory. If you are upgrading from version 1.x, simply extract the new version on top of your old version. SUARM and SUARMCFG will make all needed changes to your configuration automatically. Once you have extracted the program, pick up a mail packet from each BBS you are going to be importing from. You will need a packet from each BBS you hope to use SUARM with. Once you have all the packets you need, run the program SUARMCFG.EXE. This program will allow you to set up your system in the simplest possible manner. (Those wishing to experiment, to get the most power possible from SUARM, should also read Appendix A on configuration file structures.) You will see three options on the menu bar. Select "Edit." From the pull-down menu, select "pathnames." You will be prompted for three paths: where to find incoming QWK packets, where to put outgoing REP packets, and a scratch directory where SUARM may do its work. WARNINGS ALL three paths must be defined before continuing. Make sure NO important files are in SUARM's work directory. SUARM will delete them. Once you have set up these paths, select "BBS" from the menu bar. From the pull-down menu, select "New." You will be prompted for the BBS ID of the board you wish to add to the configuration. Type the filename of the QWK packet (minus the extension) of the appropriate board. SUARM will scan the packet, configuring itself for that BBS. You should then save both the main configuration and the config for that BBS by pressing F6 and then F8. After this, you can continue to add as many "New" boards as you want. Once all the BBS's you will be using have been added to SUARM's databases, you are ready to configure SUARM to import and export from each. ------------------------------ USING THE CONFIGURATION EDITOR ------------------------------ To load the configuration editor, type SUARMCFG from the DOS prompt. If you have set the SUARM environment variable, the editor will change to the SUARM directory immediately. The editor will look for a file called SUARM.CFG, and load it if it is found. This is the main configuration file, containing important information about your system setup. If no SUARM.CFG is found, the editor will use several default settings. Chances are you will want to change them. At any time, you may press F5 to re-load SUARM.CFG from disk, or F6 to save the values you have set up. You may also press F7 to load a .CFG file for a BBS, or F8 to save the current BBS's .CFG at any time. This and other important hotkeys are displayed on the bottom line of the screen. Across the top of the screen are the main menus for the editor. From left to right, they are: FILE: This menu has only two options. CHANGE DIRECTORY: This allows you to change the current working directory. You may have to use this if you did not set the SUARM environment variable, or if you want to work on a configuration saved in a different direcory. EXIT: Exit the editor. EDIT: This menu allows you to change important settings, which will generally be used by the tosser at all times (although many options can be overriden by a custom .CFG file for a BBS, see Appendix A). SYSOP: These settings control how the tosser interacts with you personally, and how it handles functions directly related to you. The settings under this menu are: SYSOP NAME: This is your name, as defined in your BBS setup. All imported files and other important messages are addressed to this name. Also, any messages addressed to "SysOp" or from "SysOp" on your system can be converted to this name. See "Convert Outgoing" below. HUB SYSOP NAME: This is the name of the SysOp of your hub. If you select the "Convert Incoming" option (see below), all messages to/from "SysOp" in your mail packet will be changed to this name. This name will be different for each system, and as a result is not saved in SUARM.CFG, but in the individual BBS's .CFG. IMPORT BASE ID: This is the base ID (see below) to import all specified text files to. Whether or not you import text files, this base MUST be defined. The default is base #1 as defined in MESSAGES.RA. CONVERT INCOMING: If this option is enabled, then all messages coming into your system to or from "SysOp" will have that name changed to the Hub SysOp name. CONVERT OUTGOING: This option allows you to change all messages to/from "SysOp" exported from your system so they bear your name instead. KILL DUPLICATE MESSAGES: When this option is turned on, SUARM will check its database to determine whether or not each message in a packet has already been imported. This is effective in stopping 'dupe loops' and 'carpet bomb' messages. If you do not want or need this option, turning it off will increase the speed of the program when tossing. It is recommended you leave it ON. PATHS: This lets you define the paths SUARM is to use for incoming QWKs, outgoing REPs, and as a scratch workspace for its own use. You should have already defined these in the previous section. ARCHIVERS: This allows you to define the command line to be used for each of the four archivers supported by SUARM. The default settings are the recommended command lines for use with PKZIP, ARJ, PKPAK/PKARC, and RAR. They may be edited to suit your needs (for example, if you use InfoZIP instead of PKZIP, or want different default settings for RAR). NOTE: if your network uses FWKED-style packet encryption (see below, and also appendix B) and you configure SUARM to automatically decrypt the packet, the 'Unzip' command will be ignored at the decryption stage, since FWKED only works under PKZIP, and requires a custom command line. There are also options to LOAD and SAVE the SUARM.CFG file. BBS: This menu is the largest, and lets you configure the settings for the current board. Before any of these options can be used, you must first either LOAD a BBS configuration, or create a NEW one from a mail packet. CONFERENCES: This is the most important part of the configuration, and where you will spend the most time. You can also get to this section by pressing F4 at any time. You will see a window with your currently defined conferences (if you are just beginning your configuration, this window will be empty.) You may move up and down the conferences with the arrow keys. Buttons on the side of the window allow you to edit or delete conference selections, add a new selection, and exit from the conference editor. When you add or edit a conference, you will see a dialog box. You will be prompted for: BASE ID: With RA 2.02 or greater, this will usually be a conference number as defined in MESSAGES.RA. Under other systems, or in certain cases, this will be an 'MK' style base ID. See below for details on MK IDs. CONFERENCE: This is the conference to import from your hub. You will be able to select zfrom a menu of available conferences with the arrow keys. ORIGIN: This allows you to select which pair of origin lines (see below) will be used for this conference. Up to five pairs of origins may be defined for each BBS you get mail from, allowing you to import several different networks at the same packet for each BBS. When you have finished configuring the conference, hit ENTER or press OK. To abort at any time, hit ESC or press "Cancel." BAD MESSAGES: A relatively new concept in QWK networking, bad messages are (basically) stuff you weren't expecting. If you turn on a conference in the mail door of your hub and download it, but don't add it to your configuration in SUARM, the tosser won't know what to do with it. Thus, it is considered a 'bad message.' This section offers you three options for handling bad messages: IGNORE them, just skip over them when tossing. DUMP them to a specified base. The message will be saved, along with some basic information, in this base. If you have configured to save your bad messages in this manner, SUARM will scan through your bad base each time it is run to see if the conference in question has been configured yet. If it has, then SUARM will automatically move the messages into that conference. AUTO-JAM them. This creates a JAM format message base for the conference, based upon the name it is given on your hub. A future version will also allow automatic updates to MESSAGES.RA for auto- JAMmed bases. This allows you to keep the conference separate, and ready to be added to your BBS at your leisure. You will also be asked for: BAD BASE ID: The base ID (see below) of the conference to dump bad messages in. If you do not have bad messages set to "dump," then this will be ignored. AUTO-JAM PATH: The path to put all automatically created JAMbases in. If you do not have bad messages set to "Auto-JAM" then this will be ignored. ORIGIN LINES: This section lets you define the origin lines that will be appended to mesages leaving your system, and on messages that originate (without an origin line of their own) from your hub. Up to five pairs of origin lines may be defined for each BBS, and each conference can be configured to use any of the five pairs. Note that origin lines, like nuns, policemen, and Krynoids, always travel in twos. You should make sure that each origin line is a matched pair. (For example, if you have your origin #1 mentioning ILink, you don't want your hub's origin #1 mentioning GeniusNet.) Many networks have standard layouts and content requirements for origin lines. Make sure you check with your network administration or with network rules when you enter your origin lines. OPTIONS: These are some different options, not important enough to warrant their own menu option, but too important to ignore. The options available in this section are: CONVERT NAMES TO UPPERCASE: Some mail doors (and some networks) require that the "To" and "From" line on each message be in uppercase. RA uses mixed-case as a standard. If you select this option, SUARM will automatically convert the names on all messages exported from your board to your hub to uppercase. The default is NOT to do this. MAXIMUM NUMBER OF DUPES: This allows you to control the size of SUARM's duplicate database. Each dupe record takes 6 bytes of disk space, so a database of 10000 (the default) duplicate records would require 60000 bytes. If disk space is at a premium, you may lower this number. (Lowering the number also slightly increases tossing speed, but at the expense of accuracy.) Note that this is a GENERAL option, and will be saved in SUARM.CFG, not the BBS's .CFG. REPLY COMPRESSION: You may select the compression format to be used on outgoing .REP packets to your hub. This has no affect on incoming mail packets; SUARM automatically detects the compression format used. SUARM supports PKZIP, ARJ, PKPAK/ARC, and RAR compression formats. IMPORT TEXT FILES: This allows you to define a number of text files to be imported if they are included in your mail packet. For example, a SESSION.TXT file may be imported with a complete rundown on mail traffic for that packet, or an important news file or bulletin included in the packet can be imported as mail to you. All imported files are saved in the base specified under the "SysOp" menu option, with the file name as the subject. ENCRYPTED MAIL: For systems receiving encrypted mail packets by satellite, SUARM implements the FWKED (CODEKEYS.LST/KEY_ID) standard for automatic decryption. Make sure your CODEKEYS.LST is in the SUARM directory if you enable this option. You will be prompted for: ENCRYPTED MAIL PATH: This is the path your encrypted mail packets will be found in. It will almost always be different from your normal .QWK path. ENCRPYTED MAIL MASK: This is the filemask to search for packets with. For example, if you are receiving encrypted ILink packets, the filemask will be ILINK.0*. Encrypted packets from my system would be CNX.0*. The general rule of thumb is: if you don't know whether or not you need this, then you don't need it. Check with your network administration if you are not sure. More about encrypted packets in Appendix B. REFRESH CONFERENCE NAMES: Often, names will change on a system, and conferences will be added and dropped. This option allows you to update SUARM's "Conference name" database for a specific hub. You will need a mail packet in the .QWK path for the hub you want to update. NEW: This allows you to create a NEW BBS configuration, and is usually used when you are picking up mail from a new system. You should have already used this option when first setting up. You will be prompted for the BBS ID of the hub in question, and the rest will be done automatically. There are also options to LOAD and SAVE that BBS's .CFG file. --------------- ABOUT BASE ID'S --------------- If you are using SUARM with RemoteAccess, then generally the "base ID" you are entering for each conference and for other situations (saving bad messages, importing text files, etc.) will simply be the conference number as you have it defined in MESSAGES.RA. For example, if you give "145" as the base ID of a conference you are importing, then all messages in that conference will be imported into message base number 145 on your BBS. This works with both Hudson and JAM message base types, and allows you to set up SUARM in the simplest possible manner and the shortest possible time. There are times, however, when this is not good enough. For example, you may be running a BBS program other than RemoteAccess, or you may want to import messages into a base not defined in MESSAGES.RA (for example, a *.MSG-format netmail base, or as part of a doubled-Hudson setup). For these cases, SUARM provides a simple method of directly addressing a message base's format and location on your drives. SUARM supports what is known as the 'MK' base ID format, named after MKNet and the MK message utilities which first used it. It is especially included for those making the transition from MKNet to SUARM. An MK base ID is a single letter denoting the message base's format followed by (if needed) a sub-board number and the location of the base on disk. Formats supported in SUARM 2.0 are: HUDSON: (Also known as QBBS). H followed by a three digit board number and the path to your Hudson base. Example: H001C:\RA\MSGS\ JAM: J followed by the JAMbase path and name. Example: JE:\RA\MSGS\JAM\RAUTIL SQUISH: S followed by the SquishBase path and name. Example: SC:\PROBOARD\MSGS\FIDO_OS2 *.MSG: ("Fido") F followed by the path of the base. Example: FC:\IM\NETMAIL\ ----------------- ADVANCED CONCEPTS ----------------- SUARM's configuration files were designed to be easy to read, understand, and edit. In fact, they are simple text files issuing a number of commands. (The exact command names and syntax are covered in Appendix A.) SUARM will recognize a command whether it is in the master SUARM.CFG, or in the configuration file of a BBS. This allows you to tailor your setup to your specific needs, instead of making you use the 'bigger hammer' method of forcing things into place. For example, you can change global definitions on a temporary basis by adding the appropriate command in a BBS's .CFG file. Let's say that for some reason, your hub 'FUNBBS' is still using PKZIP 1.0, and you need to change your ZIP command for that BBS only to make sure your REPs are readable by your hub. You could add a line to your FUNBBS.CFG: ZIP=PKZIP10.EXE -a,PKUNZIP -o This would make SUARM use PKZIP10.EXE instead of your standard PKZIP when you compress your replies. Or, for example, say you want to check for duplicates in general, but not from one specific BBS. You could add the line to that BBS's .CFG: DUPECHECK=OFF I refer to this concept as 'overriding.' Essentially, you are overriding your master configuration, telling SUARM to do things differently in this one case. In the same way, you can take a function normally associated with a specific BBS and make it apply to ALL boards you feed from simply by including it in your SUARM.CFG file. For example: adding the line: OPTION=UPPERCASE to SUARM.CFG will make sure ALL reply packets, regardless of where they are going, use uppercase-only names in their headers. Or adding: IMPORT=SESSION.TXT will import the SESSION.TXT files of all packets that pass through SUARM. This concept is called 'globalizing,' since you are taking an option and forcing SUARM to apply it globally. ALSO NOTE that you CAN, if for some reason you want to, override a globalized command. The individual BBS's .CFG file always has final say, so be careful with overriding and globalizing, or you might end up not doing what you wanted to. Also note that SUARMCFG.EXE always creates the optimal configuration file for your system, and as a result ignores all globalizing and overriding. If you modify your .CFG files in this manner, I suggest that you NOT use SUARMCFG.EXE. ------------- IN CONCLUSION ------------- This new version of SUARM has been as much a labor of love as it has an update to suit my needs and the needs of others. A lot of bug fixes have been made and a lot of new 'gizmos' as one user called them have been added at people's prompting. Briefly, let me thank Jim Lee, Michael Leavitt, Patrick Spreng, Kathy Lessa, Richard Sharp, Pete Rocca, and everyone else who has made contributions to this version of SUARM. Especially all the intrepid beta testers out there. Also, thanks to Fred Kantor for creating an encryption system that was not only easy to use as a SysOp, but easy to implement into my own software. To contact me, netmail me at 1:266/73, E-Mail me at pab@cnx.com. I also monitor the Fidonet RAUTIL echo and most conferences on ILink for personal mail to me. I also offer a Fidonet echo called EMPIRE for product support for SUARM, Bulkmail, Lyme, and my other programs. It's also available as an Internet mailing list. For information on connecting to either, please contact me. And don't forget to register! Pab Sungenis - 6 Aug 1995 -------------------------------------- APPENDIX A: CONFIGURATION FILE LAYOUTS -------------------------------------- FILE: SUARM.CFG Purpose: Main configuration file, determines global configuration. Format: One command per line. FILE: bbsname.CFG Purpose: Configuration for import from a BBS, determines settings for that BBS only. Format: One command per line. FILE: bbsname.CNF Purpose: Holds conference names for all available conferences from a hub. Created by SUARMCFG's "New" BBS command. Format: First line: number of available conferences (decimal). Subsequent lines: Conference number (decimal), space, conference name. AVAILABLE COMMANDS: Command: ; Syntax: None. Purpose: Designates a comment line. Command: ORIGIN Syntax: ORIGIN=num,text Purpose: Specifies text for origin line number "num." Command: OPTION Syntax: OPTION={ZIP|PAK|ARJ|RAR} Purpose: Specifies which compression format to use on outgoing messages Command: OPTION=UPPERCASE Syntax: OPTION=UPPERCASE Purpose: Converts names in headers of outgoing messages to uppercase. Default is mixed case. Command: HUBORIGIN Syntax: HUBORIGIN=[num,]text Purpose: Specifies text for hub origin line number "num." If no number is specifed, defaults to Hub Origin #1 (for compatibility with SUARM 1.x). Command: MAXDUPES Syntax: MAXDUPES=num Scope: Global only. Purpose: Sets the maximum number of duplicate records to 'num' where 0 < num <= 10000 Command: WORKPATH Syntax: WORKPATH=pathname Purpose: Defines the path SUARM will use for temporary storage. Note that the pathname MUST end in a \, and the path cannot be used for anything else, since SUARM will wipe it. Command: QWKPATH Syntax: QWKPATH=pathname Purpose: Defines the path SUARM will search for mail packerts. Note that the pathname MUST end in a \. Command: REPPATH Syntax: REPPATH=pathname Purpose: Defines the path SUARM will place reply packets. Note that the pathname MUST end in a \. Command: ENCRYPT Syntax: ENCRYPT={YES|NO},pathname,filemask Purpose: Defines encryption settings. If auto-decrypt (ENCRYPT=YES) is enabled, then in addition to the QWKPATH defined above, SUARM will search the specified path for files matching the specified filemask, decrypt them, and toss them. Commands: ZIP, RAR, ARJ, PAK Syntax: (command)=compresscommand,decompresscommand Purpose: Defines the command lines to be used for the specified compression format. Generic command lines are created by both SUARM and SUARMCFG, but this allows you to specify different options or compression programs for each format. Command: KEEPBAD Syntax: KEEPBAD=baseid Purpose: Defines the base to keep bad messages in, if BADTYPE is set to KEEP. Command: BADTYPE Syntax: BADTYPE={KEEP|IGNORE|AUTO}[,pathname] Purpose: Specifies handling of bad messages; whether they are kept in a bad message base, ignored, or a base is automatically created (in path "pathname"). Command: CNV Syntax: CNV={IN|OUT},{YES|NO} Purpose: Enables/disables conversion of "SysOp" on messages to the appropriate SysOp name. Command: FILEIMPORT Syntax: FILEIMPORT=baseid Purpose: Specifies the Base ID to import text files into. MUST be defined, whether used or not. Note: Replaces STATID from SUARM 1.x config files. STATID lines will be used/converted automatically. Command: NAME Syntax: NAME=sysopname[,hubsysopname] Purpose: Defines SysOp name, and (optionally) the name of your hub's SysOp. Command: DUPECHECK Syntax: DUPECHECK={ON|OFF} Purpose: Enables/disables duplicate message checking. Command: IMPORT Syntax: IMPORT=filespec Purpose: Import specified text file if included in packet. Command: (conference number) Syntax: num=baseid Purpose: Import messages from conference number "num" on your hub into the specified base ID. This defines the mapping used to import a packet. -------------------------- APPENDIX B: ENCRYPTED MAIL -------------------------- With the advent of satellite mail delivery, some QWK networks are opting to encrypt their mail packets when they are sent over the satellite. This way, only people with valid keys (presumably network SysOps) will be able to decode and import the mail, preventing 'renegade' boards from echoing networks they are not members of. SUARM implements one popular method of packet decryption: the FWKED method. This method, created by programmer Fred Kantor, matches up a keyspec in an encrypted packet with the appropriate decryption key in a file known as CODEKEYS.LST. The packet is then decoded, using the specified key. This method was recently approved and implemented by the ILink network for their mail delivery over the Planet Connect satellite service and an upcoming FTP delivery method. Other networks will probably follow suit in the upcoming months. If you need packet decryption, obtain the appropriate CODEKEYS.LST file from your network administration. Place this file in your SUARM directory, then select the 'Encryption' option under the 'BBS' menu in SUARMCFG. ENABLE AUTO-DECRYPTION: Check this box to activate the automatic decryption. Note that if this box is checked, SUARM will only look for encrypted mail packets from that BBS. ENCRYPTED PACKET PATH: Enter the path to search for encrypted packets. This will usually be the directory your satellite receiving program stores them in. ENCRYPTED PACKET MASK: This is the filemask to use when searching for encrypted packets. For ILink packets, use ILINK.0*. SUARM's built-in decryption enables you to save a step in your mail tossing. You will not need the FWKED program, nor will you need to pre-process your packets before tossing them.