synchro.net

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

/ synchro.net / synchro.net.tar / synchro.net / modem.madness / SMMNETML / REC_200.ZIP / SYSOP.PRN < prev

Wrap

Text File | 1993-04-30 | 158.3 KB | 3,729 lines

Remote Echo Control (REC) Version 2.00 Sysop's Documentation Copyrighted (c) 1990-3 by Daniel S. Fitch All Rights Reserved Remote Echo Control 2.00 Sysop Documentation Table of Contents 1. Introduction............................................1 1.1. Overview ...................................1 1.2. Copyright and Disclaimer ...................1 1.4. Registration for Use .......................2 1.5. Program Versions and Distribution ..........2 1.6. Implied Consent ............................3 1.7. Trouble Reports ............................4 2. Installation............................................4 2.1. Definition of Terms ........................5 2.2. Upgrading ..................................5 2.3. New Installation ...........................6 2.4. Configuration File .........................6 2.5. Wildcard EchoTags .........................14 2.6. Address Specification .....................15 2.7. Address Defaulting ........................16 2.8. Batch File Changes ........................16 3. REC Operation..........................................17 3.1. User Instructions .........................17 3.2. Command Line Parameters ...................17 3.3. Overview ..................................18 4. Operational Details....................................19 4.1. Overlay ...................................19 4.2. Message Disposition .......................19 4.3. Minimal Disk Reads ........................20 4.4. Inbound Message Addressing ................20 4.5. OutBound Message Addressing ...............21 4.6. Display Level Control .....................22 4.7. Exit Error Levels .........................22 4.8. Sorting ...................................23 4.9. Point systems .............................24 4.10. Message Headers ...........................26 4.11. Message Generation ........................27 5. Mail Processor Support.................................27 5.1. ZmailH 1.25 ...............................28 5.2. Qecho .....................................29 5.3. ZmailH 2.0 ................................30 5.4. Squish 1.0 ................................30 5.5. QMail .....................................32 6. Major Features.........................................32 6.1. Readdressing ..............................32 6.2. Automatic Starting of Echos ...............33 April 30, 1993 (c) Daniel S. Fitch, 1990-2 Page i Remote Echo Control 2.00 Sysop Documentation 6.3. Automatic Forwarding ......................35 6.4. Suspend & Resume ..........................38 6.5. ReScan Mode ...............................39 6.6. Gateway Function ..........................40 6.7. Batch Mode ................................40 6.8. Notify Mode ...............................45 6.9. Status Report .............................45 6.10. Automatic Cleanup .........................46 7. Security...............................................49 7.1. Dump Report ...............................50 7.2. Changing Echo-Source ......................51 7.3. Lockout & LockIn ..........................51 7.4. Duplicate Echo Tag Names ..................51 8. Error Messages.........................................52 8.1. Message Processing ........................52 8.2. Batch Processing ..........................54 8.3. CleanUp Processing ........................54 9. Bonus Utilities........................................55 9.1. AreaList ..................................55 9.2. AreaRpt ...................................55 10. Conclusion ..........................................56 April 30, 1993 Page ii Remote Echo Control 2.00 Sysop Documentation 1. Introduction 1.1. Overview Remote Echo Control (REC) is a zone- and point-aware program written for echo hubs that allows your echo nodes to remotely control which echos they receive from your system. This is done with no manual intervention on your part. Installation is quick, configuration is simple, and execution is fast, and logging is complete. Many of the features of REC can be very advantageous to an echo hub with only one network address. If you are and echo hub in multiple zones or a gateway system, then REC will be very valuable. In addition to allowing your echo-mail downlinks to automatically start and stop echos, REC has several other features that you will find useful. Most of these features are listed below: Re-Addressing In-bound net-mail messages Automatic Forwarding of echo requests Multiple Echo-lists per echo-hub Support for gateway systems Full support for Zmail flavors Squish ReScan and Flag support Automatic starting of echos from your echo hubs Batch Command mode Disposition for processed messages Notification of Downlinks Sysop Status Report Automatic Cleanup of Dead-End echos Full Support for 3D (Zone-aware) and 4D (Point-aware) addressing A variety of Sysop-configurable security options 1.2. Copyright and Disclaimer Remote Echo Control (REC) and its accompanying utilities are copyrighted by Daniel S. Fitch, and all rights are reserved internationally. The programs and documentation are not to be decompiled, altered, or re-engineered in any way. This includes any April 30, 1993 Page 1 Remote Echo Control 2.00 Sysop Documentation patches to the load modules, and removing the copyright notice that is displayed when the programs are executed. REC comes with no guarantees. You use the software at your own risk. I will not be responsible for any damages resulting from the use of REC, including but not limited to software, hardware, system outages, or monetary. I have taken all reasonable steps to properly test this software, and will take all reasonable steps to correcting any problems discovered. 1.4. Registration for Use If you use this software for over 30 days in 12 consecutive months, you are required to register. This way I know how many copies are in use, and whether I should continue to maintain it. Registration is a legal requirement, and not an option. If you use REC, then register it. Consider it a vote for the program's continued support and development. There is no charge for registration. REC and its accompanying utilities are not crippleware. There is no change in operation of the software by registering the software. The tear-line of each message that REC generates will indicate whether the program is running Registered ('Reg")or not ("Eval"). Any attempts to forge registration keys will result in REC aborting with configuration errors. There is a program called REGISTER in the distribution archive. The program will automate the processing of sending in a new registration, changing your registration information, or deleting your registration should you cease operating as an echo hub. You should read the full instructions on how to use the program in the REGISTER.PRN instruction file. All registered users will receive the following benefits: Net-mail acknowledgment of the registration A personal registration key day-to-day and long-term support Ability to run Beta (or Alpha) program versions Non-registered users can expect technical support for getting REC to work on their systems. However, beyond that they should expect to register before receiving further technical support. Telephone support is not provided for REC, unless I deem necessary after an initial echo- or net-mail contact. April 30, 1993 Page 2 Remote Echo Control 2.00 Sysop Documentation 1.5. Program Versions and Distribution LIVE versions are designated by a simple 3 digit numbering system in the pattern of "X.YY", where "X" is the major release number and "YY" is the minor revision number. These versions are available to the general public and are released in to the SDS SOFTDIST file echo for national distribution. The can also be file requested from my system using the magic name of "REC". BETA test versions are identified with the word "<BETA>" after the version number. They are available for file request from my system using the magic name of "RECBETA". Such Beta programs have gone though as much testing as I can put them through, and generally they are running on my system. However, you should still expect a few problems to pop up with little or no warning. After all, you are testing as well as running the program. Some beta versions will be released in to the SDS SOFTDIST file echo as I deem warranted. ALPHA test versions are identified by the word "<ALPHA>" after the version number. They are to be only run on my own system and any other systems that I explicitly permit to run that particular version, since they are used to test features that I am not able to fully test on my test system. As such they have not been completely debugged, and are not for distribution to anyone else by any means. If you have a need for an Alpha version, contact myself either in the echo or via net-mail and I will put it on hold you to pickup. On some occasions they will be available for file request, and if so the magic name will be "RECALPHA". These versions are NOT TO BE DISTRIBUTED by anyone under any means without my prior approval. Versions of REC may be distributed by anyone in any BBS network organization according to the following guidelines. It must be distributed with all original files present. No files may be added. None of the original files may be altered in any means. Changing the archive format is permitted, as long as the contents of all files in the archive remain the same. This distribution is to be done FREE OF CHARGE by the distributing system, except for a nominal fee to cover any charges for postage or disk media. Charges incurred by users of a Pay BBS are not included in this restriction, unless the charge is tied explicitly to REC. April 30, 1993 Page 3 Remote Echo Control 2.00 Sysop Documentation 1.6. Implied Consent If you do not agree to these restrictions, then do NOT use this software or make it available for others to access it. Use of this software indicates that you agree to these terms. Distribution of the software, or making it available for others to get it via any means of file transfers also implies consent and agreement to the terms specified in the License for Distribution. 1.7. Trouble Reports For technical support, you can contact me in one of several ways. Anyone can use the REC_SUPPORT echo available through FidoNet, MetroNet, or MXBBSNET. Zmail users can also use the ZMAIL echo found in either MetroNet or FidoNet. No matter how much testing is done, any software is bound to have glitches or bugs present. This includes the documentation. You may be asked to send your configuration and echo control files to the author at the name and address listed above for registration. Please be sure to supply the include as much of the following information as you possibly can. Failure to do so may result in my being unable to determine the problem, and asking you to supply further information. I would rather you send more information than not enough. Below is the list of what I recommend: hardware and software description Which release of REC you are running Any program termination messages Copy of relevant portion of the log file Complete copy of your configuration file Complete copy of your echo control file Copy of the REC_DUMP.RPT A short narrative of the problem Any captured screen displays Any messages read in by or created by REC (*.MSG format only) All copies of files should be archived in to a single file. Do not attempt to put all of this in to a single net-mail message as the net-mail process may alter the data the to point were problems are either hidden or created. April 30, 1993 Page 4 Remote Echo Control 2.00 Sysop Documentation 2. Installation Well, that is enough of the legal matters. Now let's get on to the business at hand and get this program working! 2.1. Definition of Terms Just so everyone is using the same terminology, I will briefly describe the terms I will be using in this documentation. This is not intended as a short course, but rather as a translation. ECHO - The actual message area that is passed from system to system. ECHO HUB - The system that sends echo mail to your system for you to distribute. ECHO LIST - This a ASCII (text) listing of all the echos available through a particular system. ECHO NODE - The node receiving echo mail from your system. AUTOSTART - Allowing an Echo-Hub to be able to automatically create pass-through echos on your system by simply sending you the echo. Additionally, these same echos can be passed on to specific Echo-Nodes. LOCKOUT - Blocking an echo from receiving mail on an certain echo. This could be needed for several reasons, including Network Policy, local Net policy, or echo moderator decree. LOCKIN - Once connected to an echo, an echo-node is not allowed to disconnect from the echo. This is typically for required echos. GATEWAY - A special system that is designated as the echo-mail gateway system between two or more networks. April 30, 1993 Page 5 Remote Echo Control 2.00 Sysop Documentation 2.2. Upgrading This version of REC is not a "load and go" upgrade. The many new features and changes to existing feature will require changes to your configuration file. You should read the HISTORY.PRN file for exactly what has changed, and refer to the indicated sections of this document for full details. The biggest changes you will have to deal with are the redesigned security scheme, multiple mail-processor support, and multiple echo- lists. 2.3. New Installation While you can place REC in any directory on your system that you wish, I suggest that you place it in its own directory. This will make program updates easier and keep your hard disk somewhat more organized. The first step is to un-archive the distribution file into the directory that you wish to use. The original distribution file contains the following files: REC.EXE The main program REC.OVR Overlay modules SAMPLE.CFG A sample configuration file SYSOP.PRN Sysop documentation, ready to print HISTORY.PRN Revision History, ready to print REGISTER.EXE Program to automate registration of REC REGISTER.PRN Registration instructions NOTIFY.HDR A sample text header for notify messages REPLY.HDR A sample text header for reply messages RESULT.HDR A sample text header for result messages CANCEL.HDR A sample text header for Forced Clean messages HELP.TXT A sample text "Help" to be sent to echo-nodes The distribution file also contains a few little utility programs that you may find useful. They were written for the sysop of an echo hub, and are part of the REC package. Consider them a bonus. These utility programs are listed below and explained later in this documentation: April 30, 1993 Page 6 Remote Echo Control 2.00 Sysop Documentation AREALIST.EXE - Alphabetical listing of echos AREARPT.EXE - Echo Distribution Report REC is now on your BBS, and ready to be configured. Coincidentally, configuration is the next topic to be discussed. 2.4. Configuration File 2.4.1. Naming Most of the file names that REC will need are specified in the configuration file. There are some names, however, that are hard coded in the program. The most important one of which is the configuration file name. In some environments, each zone or network requires a separate Echo Control File. You can create a different configuration file for zone or network that you want, or you can use just one configuration file. The configuration file name defaults to REC.CFG and is expected to be found in the directory where the REC program is located. You can override that file name using one of two methods: Environment String Variable, or a Command Line Parameter. To specify the configuration file name via an environment variable, you put a "REC" statement in your environment string. If you are not sure of how to set environment variables, you should to your DOS manual. For example, you can use the following statement to tell REC to look for the configuration file "FIRST.CFG" in the directory "C:\MAIL\REC": SET REC=C:\MAIL\REC\FIRST.CFG You can also specify the configuration file name using the "/FC" command line parameter. For example: REC /FCC:\MAIL\REC\SECOND.CFG The above line will tell REC to look for the configuration file "SECOND.CFG" in the directory "C:\MAIL\REC". The order of precedence is the command line parameter, the environment variable, and then the default name. Also realize that if you specify an override that doesn't exist, REC will not check any of the other locations. It will end with an error message and the proper return code. April 30, 1993 Page 7 Remote Echo Control 2.00 Sysop Documentation 2.4.2. Format The configuration file for REC is a standard ASCII file that you can edit with any ASCII or Text editor. The example is broken down into several sections, and there is almost no required order that they must come in. Certain entries are required, other entries must occur at least once, and some entries are optional. The entire configuration will be verified at the start of each run of REC, which only takes a second or two. The entries are case-insensitive, and the keywords must be followed by at least one space. If an entry can have more than one field after it, these fields must be separated with either a single comma or at least one space. Do NOT use TAB characters anywhere inside the configuration file. With the exception of Location, SystemName, SysopName statements, any spaces in a single field must be typed as an underscore ("_"). The program will replace them with spaces when the configuration file is processed. There is a required order of some of the configuration statements. If you follow the order shown in the sample configuration file, you will not have any problems. The order is briefly shown below: ADDRESS ECHOHUB ECHOLIST AUTOSTART GATEWAY Each of the entries are described below in alphabetical order. They appear in several "logical" groups in the sample REC.CFG file. For examples, please refer to the sample configuration file found in the distribution file 2.4.3. Required Statements AccessName (MIN 1) - This is a name that you want your echo nodes to use when they send a message to REC. A space in the name is shown by an underscore (_) character, as shown in the example in the sample configuration file. AccessName {text} Address (MIN 1) - This is a list of all the addresses that your system is known as for echomail. This list should include April 30, 1993 Page 8 Remote Echo Control 2.00 Sysop Documentation every address that your system uses to pass echo mail in areas that you want to control with REC. If you have addresses that you do NOT use for echo mail traffic, do NOT list them here. At best they will do nothing, at worst you will get wrong addresses on your outbound mail. Please place your most commonly used address first, as that address will be the default. EchoControlFile (ONLY 1) - This is the complete path and file name of the file that controls how the echos are distributed. The format of this file will depend on which mail processor you indicate with the MailProcessor statement. EchoNode (MIN 1)- This is the definition of each of your echo nodes that you want to use REC with. You can have nodes listed in your Echo Control File that are not listed as an Echo Node, but only nodes listed as Echo Nodes will be allowed to use REC. The only optional fields are the 3 sysop names. EchoNode {address} {flags} {password}[sysop name [...] Address - The net address of the echo node being defined. Flags - These are the character flags that indicate which echos the system is allowed to access. Password - This the password that your echo node must use to get access to REC processing. Sysop Name [Max 5] - While password checking is always followed, you have the option of restricting REC access by name. If at least 1 name is specified, then the sender of the REC message must be listed here for REC to accept the message. If no names are specified, then the message will be accepted by REC no matter who the sender is (providing the password is correct). These fields are also used by some other parts of REC, so I strongly encourage to specify at least one name for each echo node. Location (ONLY 1) - This statement is only really used by the Registration program. However, its presence is required when running REC. The syntax is fairly straight forward, and is shown below. The actual data following the key word is entirely up to you, and the presence of spaces or commas will have no affect on the use of the data. Location {city, state, Country} April 30, 1993 Page 9 Remote Echo Control 2.00 Sysop Documentation MailProcessor (ONLY 1) - This statement tells REC which type of mail processor you are running, and also what format of echo control file you use. This statement is described fully in the Mail Processor Interface section of the doc's. MsgDirectory (ONLY 1) - This is the directory that net-mail messages will be read from and written to. RecDir (ONLY 1) - This is the directory that the REC program and all of it's support files can be found. SystemName (ONLY 1) - This is the name of your system, and will be placed on generated messages to your echo nodes and your own echo hubs. SysopName (ONLY 1) - This is your name, and will be placed on generated messages to your echo nodes and your own echo hubs. 2.4.4. Optional Statements AutoCancelDelay - This statement will allow you to change the default turnaround time of 1 day for echos that are automatically canceled. This is useful when you only connect with a system once a day or only every couple of days. AutoCancelDelay {echo hub} {# of days} AutoStart - This statement identifies which systems are allowed to automatically start new echos to you just by sending you the echo. This is typically only setup for your echo hubs, and requires the use of BadEchoMsgDir statement, and is necessary for the "/S" command line parameter is used. This statement can also be used in conjunction with the DelayEchoStart option. See the section on "Auto-Starting Echos" for more details AutoStart {from address} {to address} [downlinks...] BadEchoMsgDir - This is the directory where your mail processor puts messages that come in to you on echos that you do not have listed in your echo control file. This statement is required when using the "/S" command line parameter. See the section on "Auto-Starting Echos" for more details. CleanUpDelay - The statement allows you to control the number of days REC will wait to CleanUp an echo that has been April 30, 1993 Page 10 Remote Echo Control 2.00 Sysop Documentation automatically started by one of your echo hubs. The default value is 5 for 5 days. See the section on "Automatic CleanUp" for further details. CleanUpDelay {number of days} Gateway - This command will allow REC to perform special Flavor controls for the Zmail line of mail processors. It is needed for only those running a true official echo-mail gateway between two networks. See the Gateway Section of the documentation for more information. Gateway {echo hub} {echo node} {hub flavor} {node flavor} DefaultSecure - This statement specifies the default level of security for any echo that is not "sourced" from one of your _listed echo hubs. DefaultSecure - {security flags} DelayEchoStart - This option will have REC delay the addition of an echo to your echo control file when it has been requested by one of your downlinks and forwarded on to one of your hubs. This will only be used for systems which included on an AutoStart Statement. EchoHub - This is the definition of your echo hubs, which are your primary echo feeds. An entry is needed for any echo hub which you want to use automatic forwarding or Automatic Cleanup, which will be described in the Major Features section. EchoHub {address} {flags} {send to} {subject} [type] Address - The network address of your echo hub. Flags - The is the list of character flags that an echo node must have to obtain an echo from this echo hub. Send To - The name that you want to address the message to. Subject - The text that you want to see on the message subject line. This is also where you specify the password for automated hubs running REC or AreaFix. Type (option) - Two possible values can be placed here: "REC" or "Areafix". If the field is omitted or has any other value, it will be ignored. This field is used only with Automatic Forwarding, and is described in the REC Processing Section. The default value will have messages addressed for a human being to read. April 30, 1993 Page 11 Remote Echo Control 2.00 Sysop Documentation EchoList - This statement defines an echo-list. Full information on this statement can be found in the section on Automatic Forwarding. EchoList {filename} {Description} {EchoHub Addr | LOCAL} {Security Flags} filename - The DOS filename of the echolist. It can be on any accessible drive or path, but the end filename must be unique regardless of path or extension. description - A text description of what the file means. Keep this down to just a few short words, and indicate any spaces with underscores ("_"). EchoSource - This statement will override REC internal method of determining the source for an echo area. Please see the sections on Automatic Forwarding and Security for details on it's use. EchoSource {address} {tag...} EuroDate - Because of the many overseas users of REC, both in Europe and Asia, I have added this option at repeated popular request. REC defaults to using the "American" style of date formatting, meaning MMM-DD-YY ("Sep-09-92"). The use of the EuroDate option will force REC to use the format of DD-MMM-YY ("05-Sep-92") which is common in the European countries (and some branches of the U.S. Military!). This statement will NOT have any affect on the date field shown in the .MSG file headers since that is specified by FTSC rules. ExtraNotify - This statement allows you to notify nodes other than those listed as EchoNodes. If you specify the optional "To name" on the message, the message will be address to that person. Otherwise REC will put "Sysop" in to "To name" field on the notify message. ExtraNotify {Address} [to name] ForceForward - This statement is used to force REC to forward unknown echos to a particular echo hub. It is not to be used indiscriminately and ideally should not be needed at all. But it's better to be prepared then not. Read the section on Automatic Forwarding for full details. ForceForward {echo-node address} {Echo-hub address} April 30, 1993 Page 12 Remote Echo Control 2.00 Sysop Documentation Lockin - This statement will block an echo node for stopping an echo that they are required to have. The asterisk "*" wild- card character can be used. Please read the second on Wildcard EchoTags for notes on this feature. Lockin {echo tag} {address...} Lockout - This allows you to specifically deny access to an echo by a particular node. As with the Lockin statement, the asterisk "*" symbol can be used here as a wildcard. Please read the section on Wildcard Echo Tags for more information. Lockout {echo tag} {address...} MaxMsgSize - This statement controls the maximum number of bytes in a single message. If the message will exceed this limit, it is broken up in to multiple messages. This limit is an approximate limit only, so do not use the maximum possible size for your mail processor with a variance by close to 250 bytes being possible. The minimum size is 1,000 bytes, the default is 10,000 bytes, and the maximum size 32,767 MaxMsgSize {number of bytes} MsgAttr - This allows the sysop to control which attribute flags are placed on the outgoing .MSG files. The defaults are Private, KillSent, and Local. Using this statement with completely override the defaults, even if it doesn't have any parameters. CAUTION: Be sure to specify at least the Private (P) attribute. Otherwise any user with net-mail access on the receiving system will be able to read the notify messages and obtain the password. MsgAttr [P] [R] [S] [IT] [O] [KS] [L] P = Private R = Received S = Sent IT = In Transit O = Orphaned KS = Kill Sent L = Local MsgDisp - This statement allows you to control how REC will dispose of the messages is processes. You can either Kill (delete) the messages, Keep them so they will be imported, Move them to another directory, or Copy them to another directory _and_ let them be imported as well. The default is to Kill (delete) all messages processed. See the section on "Message Disposition" for more details. April 30, 1993 Page 13 Remote Echo Control 2.00 Sysop Documentation MsgDisposition {good disp} [good dir] {bad disp} [bad dir] NotifyExclude - This will allow you to specify a particular system that you do not want notified, even though it is listed as one of your EchoNodes. This will have no affect on your ExtraNotify statements NotifyExclude {address} NotifyOptions - This statement will allow the sysop to put additional information on to the Notify message. As this can be used to reveal the password to the recipient, it must be used with care. "Users" will list all persons allow to send change requests to REC from that node. "Password" will put the node's password in to the message. "Desc" will put the descriptions for the echos on to the notify message. NotifyOptions {Users} {Password} {Desc} ReAddress - This option allows you to change this from-address on any inbound messages that REC processes. Please read the section on Re-Addressing before you use this option ReAddress {inbound address} {new address} RegistrationKey - This statement is used to put your registration key in to REC. It is not required for running REC, but if you wish to change or delete your registration, this statement will be needed. Please refer to the REGISTER.PRN documentation for information on how to get your own registration key. RegistrationKey {registration key} ReportOptions - This statement allows extra items to be put on the Active, Available, and Forwardable reports. Currently there is only one option possible, that being "Desc" which will put Descriptions on to all of the echo-tags given on the report. ReScan - This statement will active REC's ReScan List generation. This statement has two distinct forms and is explained in detail in the section on ReScan Support. ReScan List {filename} ReScan Command {filename} {command line} Secure - This statement allows you to put additional security requirements for specific echos. An echo node will not be April 30, 1993 Page 14 Remote Echo Control 2.00 Sysop Documentation able to access these echos without having the indicated security flags. The format is shown below: Secure {security flag} {echo tag...} SquishFlag - This statement will allow users of Squish to put special area flags on certain echos selected by address. Please read the Mail Processor section on Squish for more details on it's use. SquishFlag {Address} {Flag ...} Sort - This statement controls the order in REC will sort the echo control file. The sorting is done in a "sectional" fashion, meaning that it will only be done one echos that appear between comment lines. Sort {Tag|Board} [FeedFirst] Name - Sorted by echo tag name Board - Sorted by echo board number or location with a secondary sort on echo tag name FeedFirst - will force the address of the EchoHub for the echo to be listed as the first downlink. This is not a requirement for most mail processors, but it does help to put a sense of order to the echo-tags. StatusReport - This statement will cause REC to create and send to the Sysop a net-mail message every time REC is run in notify mode. This message will detail out the status of you echo control file and well as your echo nodes and echo hubs. This report is described in detail in a later section. 2.5. Wildcard EchoTags The LockIn, Lockout, EchoSecure, and EchoSource statements will accept the specificiation of wild-card echo tags. Simply put, a wild card echo-tag is simply an echo tag that ends with an asterisk "*". Any echo tag that starts with the same characters as those that precede the asterik will be considered a match. For example, the wildcard tag "Local*" will match the following: LOCAL_HELP LOCAL_SYSOP LOCALFUN LOCAL April 30, 1993 Page 15 Remote Echo Control 2.00 Sysop Documentation 2.6. Address Specification In the BBS world there 4 different methods of addressing: 2D, 3D, 4D, and 5D ("D" = Dimension). 2D uses only the net and node, 3D adds in zone support, 4D adds in point support, and 5D adds in domain support. All but 2D addressing require the use of "Kludge" lines in the body of the message text. You should realize that each level of addressing requires support for all levels below it. For example, 4D addressing requires support for 3D addressing as well. REC today supports full and correct 4D addressing for all mail processors, and 5D addressing for Zmail 2.0 users. Below I have listed examples of the addressing and what Kludge lines are used: 2D net/node No Kludges 3D zone:net/node INTL Kludge 4D zone:net/node.point TOPT & FMPT Kludges 5D zone:net/node.point@domain DOMAIN Kludge The format for putting an address in REC is quite simple. If you deal with point systems, then I suggest that you be sure to read the section on Point Systems for details on how REC handles them. On the example below, note that the only required field is the "node". All statements will follow this format: [zone:][net/]node[.point][@domain] In addition to the above, some statements will also allow you to specify an "ALL" in certain locations of the address. Several examples are show below All@FidoNet [All FidoNet addresses] 1:All (all of zone 1) 1:104/all (all of zone 1, net 104) 1:104/435.All (all points) The "All" modifier can be used on several statements including Lockout, LockIn, and the Gateway (echo node portion) statements. You should note that once REC finds the word "ALL" in the address, it will not read any more of the address. This means that the following statements will do the same thing, that is prevent anyone in Zone 13 from adding to the echo named Restricted_Echo: April 30, 1993 Page 16 Remote Echo Control 2.00 Sysop Documentation Lockout Restricted_Echo,13:All Lockout Restricted_Echo,13:All/101 Lockout Restricted_Echo,13:All/101.0 2.7. Address Defaulting The addresses that you specify will default in 2 different ways. This defaulting allows REC to determine address information if a piece is missing. I strongly urge you to specify the complete zone, net, and node for all addresses in the configuration file. The first Address statement you specify will default using the address of "0:0/-1". An address is considered valid when it has 0 or greater for all parts except the net number, which must be greater than 0. Additional Address statements, Echo Hubs, Echo Nodes, Security, and Lockouts will all default using the first Address statement. The addresses in the echo control file default in this same manner, but slightly extended. The first address on an echo will default using the first Address statement you have in the configuration file. Starting with the second address, each address will default using the previous address. This means that the second address will default using the first address, the third will use the second, and so on. This is often called the "Short-hand" method of listing addresses. Please examine the example below for an illustration, and assume that the first Address statement in the configuration file is for 1:104/435: P SYSOP 104/1 200 303/202 204 205 3:100/1 110/50 The first address will be 1:104/1. The complete receiving address will be 1:104/200, 1:303/202, 1:303/204, 1:303/205, 3:100/1, and 3:110/50. This simplifies the echo control file, and REC will sort the receiving address in ascending order after processing, and write them back out in the "short form" shown above. Please note that while this example did not specify the full address (including zone number) on the first address, I strongly recommend that you do put a full address as the first address. This is the safest way to proceed, and I highly recommend it. April 30, 1993 Page 17 Remote Echo Control 2.00 Sysop Documentation 2.8. Batch File Changes To put REC in your batch files may require a bit of re-working of your inbound mail processing. If you are using a Hudson or similar style message base for your net-mail message area, you MUST ALWAYS run REC before you import any net-mail into your message base. Otherwise you will import the mail before REC can process it, and no changes will take place. If you are using a Fido-Style or .MSG style net-mail message, this restriction does not apply. REC checks and sets the Received bit on the message during processing, so the same message will not processed twice. A typical scenario would go like this. You run your mail processing event as before except you do not import net mail. This means you would import, export, and bundle up echo mail. Then you would run REC to read your inbound net-mail messages and see if it has any work to do. After REC is finished running, you can import all remaining net-mail into your system. Lastly, if REC has created any replies to any of your downlinks, you should bundle that mail to be sent. This is not an all inclusive explanation. Each person runs their system differently, so a line by line example is not possible. The key point to remember is easy, but still worth repeating - Always run REC before you import net-mail in to your message base. 3. REC Operation At this point, REC is installed and ready to go on your system. Now is a good time to tell you use REC to process change requests. 3.1. User Instructions Included in the distribution archive is a file called HELP.TXT, which is the sample help file that will be sent to a node should they ask for it. You may edit this if you wish. I would recommend that you read it first, carefully, before you decide to change it or delete it. In fact, I suggest that you keep a reference to this help file in April 30, 1993 Page 18 Remote Echo Control 2.00 Sysop Documentation the NOTIFY.HDR file, so you users know how to get help without bothering you directly. 3.2. Command Line Parameters There are several command line parameters that REC will recognize. They are described in their own sections in this documentation, but I will list them here for your easy reference. /B - processes batch commands (Batch Processing) /C - activates CleanUp Mode (Automatic CleanUp) /D - sets the execution Display Level (Display Level) /F - overrides internal file names (Configuration & Setup) /M - displays Memory Usage (Memory Requirements) /N - activates Notify mode (Notify Mode) /O - forces complete re-sorting of the ECF /R - activates Status Report generation (Status Report) /S - activates the Auto-Start echo check (Auto-Start Mode) /V - generates echo dump report (Security - Dump Report) Some parameters are not described in their own sections, so they are explained below. /X - This parameter will tell REC to NOT process any messages it may find in the inbound Message directory. They will still be scanned so REC can determine the next message to use if it needs to create any messages. /? - This parameter will have REC display a short syntax display screen and terminate WITHOUT doing any processing. 3.3. Overview REC runs in several steps and many of these steps are optional depending on which options you have set up to work. This gives REC a very modular and structured design. You will notice this sequence of steps if you carefully read REC's log. REC will process the configuration file and verify it contents to the best of its ability, which mainly means syntax errors. Any errors found will be listed by statement name and sequence number, and at that point REC will terminate immediately. Configuration errors are NOT recorded in the log. April 30, 1993 Page 19 Remote Echo Control 2.00 Sysop Documentation The second item to be processed are the Batch Commands. Any batch commands found are processed and the result reported both in the log and via a reply message to the sysop. The third item to be processed are the net-mail messages. Any messages intended for REC are processed, disposed of accordingly, results logged, and replies generated. After all inbound messages are processed, REC will create any necessary updates for your echo hubs. Next to be performed are the special features of REC allows you to use. These include Automatic Cleanup, Notification, AutoStarting echos, Sysop Status Report, and others. The options are activated using a combination of command line parameters and configuration statements. Each of these special features are described in their own section later in the documentation. The last step to be performed is the sorting and writing of the echo control file. This file is only written when changes were made, and is sorted to the smallest degree possible. However, the /O option is on the command line, the entire file be sorted to the maximum degree possible. Finally, REC will clean up its use of dynamic memory and exit, setting the appropriate DOS error level. 4. Operational Details 4.1. Overlay REC is a very large program with over 12,000 lines of code, not counting a vide variety of common modules that I use among all of my programs. Because of this, the final compiled size of a single executable would be huge. Add the fact that not all of the routines are executed with every run of REC, it this becomes are large problem. The solution is to hav REC use an overlay file to store routines on disk until such time as the are needed, if they are needed at all. This file is called REC.OVR and must be found in the current directory, the directory where the program is executing, or in a directory along your PATH. If you received any errors from the Overlay management routine, verify that the overlay file is the correct one from the distribution April 30, 1993 Page 20 Remote Echo Control 2.00 Sysop Documentation archive and that it can be found in an appropriate directory. These two checks have resolved all overlay managers problems I have seen. 4.2. Message Disposition Each message that REC process is considered "good" or "bad". If the message was recognized but had any sort of security error, it is considered "bad". If the message was completely processed, then it is considered good regardless whether the message had any errors or not. For each "good" or "bad" message, you have 4 options on how to dispose of the message. The first option is the default disposition of "Keep". In this case, the received bit is toggled on the message but not other action is taken. Another option is "Kill" which will delete the message after processing. A third option is "Move", which will move the original message to the specified directory and then delete it. The fourth option is "Copy" which is a combination of Keep and Move. When the messages are copied they will be renumbered and will retain the the .MSG extension. The new message number will be noted in the log. Also the received bit is never set on the message that is put in to the holding directories (Move or Copy) while it is set on the message that is left in the net-mail directory [Keep or Copy]. 4.3. Minimal Disk Reads REC does not read in a file until it becomes necessary. For example REC will not read in the echo control file unless it finds a message to process or the indicated batch operation will required it. The echo-lists are loaded at the same time as the echo control file, but the descriptions are not loaded until they are needed. The overlay file that comes with REC is highly structured. It has been designed so that each overlay routine does a single high- level task and only once. The common routines are kept in the EXE file to reduce the need to swap routines in to memory from the overlay file. In addition, the overlay buffer is large enough to hold several routines as once. April 30, 1993 Page 21 Remote Echo Control 2.00 Sysop Documentation 4.4. Inbound Message Addressing While .MSG files to have zone and point fields in the message header, not all mail processors actually populate these fields. As such, REC has to do a series of searches (which are extremely fast) to determinate the proper originating and destination address of the message. First, REC will read in the entire header and all of the ^A kludge lines. If an INTL line is found then it will be used to establish the 3D originating and destination addresses. The TOPT and FMPT kludge lines will supply the proper point numbers, and finally the DOMAIN kludge will provide the proper domain names. Next, any Re-Addressing indicated is performed on the loaded messages from-address. This feature is explained in the section on Major Features, but for now I'll mention that it is only necessary for some systems that use 2D addressing only (meaning not very zone aware). Finally, REC will search to find a match on the various addresses you have listed in the configuration file. The destination address is checked against your Address statements, and the originating address is checked against your EchoNode statements. Two types of searches are actually performed. The first is for an exact match, under the assumption that they addresses on the message are 3D or 4D. The second search, if necessary, only checks to match the net/node number under the assumption that the message used 2D addressing. The last check is not really addressing, but it is important none the less. The "To-Name" of the message is checked for a match against your list of AccessName statements. If after this there is no match found for either of the addresses or the "To-Name", REC will assume the message is not intended for REC processing and simply ignore it. 4.5. OutBound Message Addressing OutBound messages are both simpler and more complicated to determine the proper addressing on the messages. The are three types of messages that REC can create: Replies, Echo Node Notifies, and Sysop Notifies. These messages are explained below. April 30, 1993 Page 22 Remote Echo Control 2.00 Sysop Documentation 4.5.1. Echo Node Replies This is the easiest of messages to address. REC is replying to a message that is was sent from another system. REC will simply switch the from and to address from the original message when it creates the reply. 4.5.2. Echo Node and Echo Hub Messages These are the most complicated of messages to address. REC has an address to send the notify message to, but it doesn't know which address to send the message "from". REC will look for a match between the destination address and your Address configuration statements in two combinations: match on Zone and Net, or match on Zone. If no matches are found, then the message will be sent from your Primary Address (the first one listed in your configuration file). 4.5.3. Sysop Messages These messages are the Sysop Status Report, Cleanup Processing Report, and an AutoStart Report that REC can generate. These will be addressed to the Primary Address and sent to the person listed in the SysopName configuration statement. 4.6. Display Level Control REC can display a large amount of information as it is processing. The more information that is displayed, the more time REC takes to run. In addition, this display of information can conflict with people that run in a non pre-emptive multi-tasking environment such as Windows or Desqview. The OS/2 operating system is a pre- emptive multi-tasking environment, and the only time this will not be a problem. You have the option is controlling how much information REC displays when it is running. This will have NO effect on how much information is written to the log file. The option is a "/D" parameter followed by a single number ranging from 1 to 5, such as "/D3". The number 1 will provide the smallest amount of display, while the number 5 will provide the greatest amount of detail. How much detail each value will allow is shown below, and each number also April 30, 1993 Page 23 Remote Echo Control 2.00 Sysop Documentation includes all information below it. For example, a display level of 3 (the default) will also show all the information for display level 1 and 2, but not 4 and 5. 1 - Copyright and termination notice 2 - Major processing events 3 - Messages processed and created 4 - Addresses of messages processed and created 5 - Full, complete details. It is possible to use I/O redirection on REC to sent the screen output of REC to a file. This is most useful when you have to report a problem and you want me to "see" what REC is doing. You can also use this send the output to a NULL device so that very little is displayed on the screen. You cannot prevent the copyright notice from being displayed on the screen. 4.7. Exit Error Levels REC will set the DOS error level when it is finished running. The error level is set using a simple binary pattern, so you can check for multiple conditions or single conditions very easily. Below is the chart: 0 No errors, no processing 1 Configuration Errors, program halted 2 Message or Batch commands processed 4 Requests Forwarded 8 Echos AutoStarted 16 Echos Cleaned-up For example, if you run REC in Autostart mode and want to rescan your message base if echos were started, you use the following lines: REC /X /S If errorlevel 8 goto rescan If you want to check for multiple conditions, you simply add the error codes together. For example, if you want to check for Messages processed and echos AutoStarted, you would check for errorlevel 10. If you are not sure how to check for error levels, please consult the manual for your operating system. April 30, 1993 Page 24 Remote Echo Control 2.00 Sysop Documentation 4.8. Sorting REC has the capability to automatically sort the echos found in the echo control file. REC will also automatically sort your downlinks addresses on each echo so the actual format area line can be smaller, which will allow for faster reading by the mail processor. 4.8.1. Echo Control File The actual echos will only be sorted if you employ the Sort configuration statement. The syntax is shown in the section on Optional Configuration statements. You can sort the file in two different ways: "Tag" or the Echo-Area name, or the "Board" meaning the message board number or directory name. Sorting by "Board" implies an automatic secondary sort key of "Tag". Sorting in only done inside of a "section" of your control file, and a section is determined by the present of a comment line. If it is wished to separate the echo control file by network, for example, simple place at least one comment line between the echos in one network and the next. As many sections can be created as desired, but it should be remembered that REC will always add any new echos to the bottom of the echo control file. Sorting will only occur if echos have been added to the echo control file. Adding or removing of downlinks, or deleting echos, will not force sorting to occur. 4.8.2. Echo-Area Downlinks The downlinks that are listed in your echo control file are automatically sorted asscendingly in the following order: Domain, Zone, Net, Node, and Point. This allows for maximum use of the "short-hand" method of listing downlinks, which takes up less disk space and can be read-in faster by both REC and your mail processor. It should be noted that nodes in the same net, zone, and domain of the echo source will be listed first, followed by all other "foreign" addresses. There is an old practice that the echo area source (or feed) must be listed first on the echo. This is most likely a requirement left- over from other echo area managers, and indeed that was also a requirement of previous versions of REC. However, REC uses a totally April 30, 1993 Page 25 Remote Echo Control 2.00 Sysop Documentation different method of determining the echo area's source, so this convention is not necessary for REC. The location of the echo source will not have any affect on the operation of your mail processor, or at least none of the authors of the various mail processors supported by REC have made such a claim. It would seem that some habits run deep, and many sysop's still prefer to see the echo source address listed first. So be it. The Sort statement has the option of "FeedFirst", which will tell REC to put the echo source as the first address in the list of downlinks. The use of this option will have no affect on REC, other than adding a few milliseconds on to the pre- and post-sort routines of the downlink sort logic. The sorting of the downlinks will only happen on the specific echos which have had downlinks added to them. There would be no reason for sorting echos which have not had any changes or just had addresses deleted. 4.9. Point systems Point Systems are also called Private Nets or Point Nets. In its simplest form, a point system is not much more than a private sub- network of BBS's. It is a fact, however, that humans have become very good at making simple things complicated. The major difference between PrivateNets and "Public" Nets is that point systems don't appear in the nationally distributed nodelist. The Boss Node of a point system is basically the door by which its dependent points talk to the rest of the world. All other BBS's just send the mail to the Boss Node, and the Boss node passes on the mail to the individual point systems. The point systems send all their mail to the Boss Node, which then passes that mail on the to the rest of BBS world. As far as echo mail is concerned, you are just passing it along like echo mail to any other BBS. Net mail takes a little more work, but there are a couple of different ways to handle that, all of which are beyond the scope of this documentation. The addressing of a point system of perhaps the most confusing part. There are 2 main ways to address a point system: private or fake net, or point reference (4D). Take my own system, for example. My FidoNet address is 1:104/435, and my private net (or point net) is 30527. I could address my fifth point (or private BBS) in either of these ways: April 30, 1993 Page 26 Remote Echo Control 2.00 Sysop Documentation 1:30527/5 (called private net or fake net) 1:104/435.5 (called a point reference - or 4D) The second style, or point reference, is all that the rest of the BBS world would need to know to get a net-mail message to one of my points. Echo mail is passed down via the echo control file, just like it would be to any other BBS. Now for the specifics of how REC handles point systems. REC will (of course) accept either of the formats of addressing a point system. The important point to remember is this: However you list the point system's address in the Echo Node definition, is how it will be handled in the echo control file. Where ever possible, Point systems will appear using the short-hand notation that I will describe next. Assume that I receive the echo tag ABC from my local NEC, and I pass it off to two other systems (210 & 550) and two of own point systems ( 5 & 15). Here's what you would see in the echo control file if I used point referencing or complete addressing for my points when I setup the EchoNode statements: P ABC 1:104/1 210 435.5 435.15 550 If the second point listed (435.15) was only shown as "15", it would actually be sent to 104/15 instead of my point 104/435.15. The same line would like this if I used private net addressing: P ABC 1:104/1 210 550 30527/5 15 As you may have noticed, the private net addressing looks just like address for net 104, except that the net number is 5 digits long instead of 3. It is your preference as to which method you want to use. What you should remember is this: If you use the PrivateNet addressing style, your mail processor most likely will NOT strip the Private Net address from the seen-by and path lines. This may be against the policy of either your Net or Network's policy. If you would like a recommendation from myself, then I have two of them. First, be consistent in how you define all of your points. Second, use the 4D Point Reference method. April 30, 1993 Page 27 Remote Echo Control 2.00 Sysop Documentation 4.10. Message Headers REC provides you the capability to put a customized header on each message that REC creates, with the exception of the Echo Change Requests that are sent to other systems (automated or not). There are 4 types of these headers: Reply, Result, Notify, and Cancel. Each of these headers is totally optional, and you can use some, all, or none. The headers are taken from straight ASCII files that REC finds in the RECDIR directory name specified in the control file, and they are placed at the top of the message being created. The information will be read in and put on the message exactly as you have typed it. Sample messages are provided in the distribution archive. Below are the file names and where the are used: REPLY.HDR Reply Message Header RESULT.HDR Result Message Header NOTIFY.HDR Notify Message Header CANCEL.HDR Cancel Message Header The Reply Message Header is put on messages that REC creates in response to a .MSG file it processed from one of your downlinks. The Result Message Header is put on a message created when REC has created an echo that was put on Forward-Hold. The Notify Message Header is put on a message that REC creates during Notify Mode. The Cancel Message Header is put on a message that is created when REC has been told to forcibly cancel an echo via the Cancel batch command. REC will add the appropriate message header to a message if the name is found in the RECDIR directory. No error message will be created if the file is not found. There are only three rules you need to remember when you format these files. First, any line-feed characters (ASCII #10) found in the file will be ignored. Second, any hard carriage returns (ASCII #13) will be retained. Third, any lines longer than 255 characters will be truncated to 255 characters. Other than these rules, you can put whatever you want in the messages and format then any way you want. 4.11. Message Generation All messages generated conform to the FTSC published requirements. This includes the use of the zone, point, and domain kludges in the actual body of the message header. REC fully supports April 30, 1993 Page 28 Remote Echo Control 2.00 Sysop Documentation the reading and writing of messages using the Kludged fields. As an effort to encourage the use of .MSG file header zone and point fields, REC will populate these fields, but it will not assume that they are correct when messages are being read in to REC. It is possible for REC to create a message that is far larger than what is capable for most mail processors. All messages that REC creates are subject to the maximum message size as defined in the configuration file. If a message should exceed this limit, the current message will be closed and the report will be continued on to a second message. Such action will be noted on the screen but not reported in the log. 5. Mail Processor Support The popularity of REC has grown much further than I had originally anticipated. REC was originally written for use with just one mail Processor, ZmailH version 1.2x, as there was no other method to automatic an echo hub running ZmailH. Before very long, people running other mail processors where trying to Kludge REC to run on their systems, with the expected mixed results. Not all of the features would work properly under some situations, and REC itself was not designed to handle this. In spite of all this, more non-ZmailH users were registering REC and asking for a hook to make REC work better with their own mail processor. To quote a phrase, I saw the handwriting on the wall and decide to build a multiple Mail Processor Interface support directly in to REC instead of just creating kludge after kludge while confusing myself and my users beyond all hope. This is the result of those efforts. The main portion of REC that performs all the work uses an internal format that is generic to all of the mail processors. The main processing routines of REC have no idea, nor do they care, which type of mail processor you are using. A single interface routine controls the actual reading and writing of the echo control file to and from the generic format used by REC. This type of approach allows for maximum flexibility, as well as a few quirks. Because of the isolation of the mail processor type, the main routines will allow you to use facets of REC which may not be supported by your mail processor. For example, Zmail 2.0 supports full 5D addressing while Qecho does not. REC will allow you to put April 30, 1993 Page 29 Remote Echo Control 2.00 Sysop Documentation domain addresses in REC's config and they will be put on the generic internal record that REC uses. However, when the echo control file is created, the domain fields will be ignored if you are using Qecho. There is no error checking or reporting for this condition. That would add an enormous amount of overhead code that would be unnecessary in most cases. This is another example of REC giving you full power with a minimum amount of overhead and program size, even the power to make a big mess. REC assumes you know what you are doing, as you should. The syntax portions of the following sections indicate what fields you are allowed to put after the "MailProcessor" keyword in the configuration file. Remember that you need at least one space between the keyword and the data fields. This section is no substitute for the actual documentation that came with your mail processor. I have listed the basic Format of the echo control file in order to give you some idea of which alternative is best for you if your mail processor is not supported directly. If there are any differences between REC and the mail processor documentation, then assume I am wrong. 5.1. ZmailH 1.25 Syntax: ZMAILH_125 [Private Net Number] Format: {#|P} {Tag} [Address ...] "P" indicates a passthrough area "#" is the hudson-style message board number "Address" is 3D or Long-hand style 4D format The Zmail Mail Processor (Copyrighted by PROZ SOFTWARE) has two features which require special support by REC. They are "Flavors" and "Point Address". Both of them are discussed here. 5.1.1. Flavors Zmail allows special processing of the outbound flavors for your echo mail. You can have the mail marked Crash, Hold, Normal, or allow it to default. You can also have the echo mail not bundled but left as .MSG files in your mail directory for another program to work on. The actual rules and use of these options are left up to the Zmail documentation. April 30, 1993 Page 30 Remote Echo Control 2.00 Sysop Documentation However, they are completely supported by REC. All characters found before the first number in the address are considered flavor codes. There is _no_ validiation of these codes, again part of the flexibility of REC. You can up to 10 symbols on a single address, and they can be put on any address you need to. They also can be used with the FLAVOR batch command and the EchoHub, EchoNode, and AutoStart configuration statements. Some default logic is imposed with these flavor commands. If you put any flavor on an echo for an echo node, it will stay there until you remove or change it. If it has no flavor when the echo node is added to the echo (via a message or batch), the flavor codes will be taken from the following places in this order: Batch Command Line Gateway Statement Echo Node or Echo Hub Statement If you wish to have all the echo mail for a certain echo node to have a certain flavor, just add that flavor to the address part of the Echo Node statement (and AutoStart statement if necessary). Every time that echo node adds an echo, the flavor on the Echo Node statement will be used. This works for Echo Hubs as well as Echo Nodes. 5.1.2. Point Addressing Zmail does have an unusual method of addressing for 4D points systems. It requires that you put the private net (or PointNet) number in address as it is found in the echo control file. This is what the PointNet Configuration statement is for. ONLY USE THIS STATEMENT FOR ZMAIL 1.2x WHEN YOU ARE USING 4D POINTS. It will force REC to use the following addressing convention for the echo control file [zone:][net/]node.pointnet/point You will notice that the zone and net are optional, but the node and Point Net values will be put in for every single one of your point addresses. 5.2. Qecho Syntax: QECHO April 30, 1993 Page 31 Remote Echo Control 2.00 Sysop Documentation Format: {#|P} {Tag} [Address ...] "P" indicates a passthrough area "#" is the hudson-style message board number "Address" is 4D format The Qecho interface uses a "typical" fully 4D file format in the traditional AREAS.BBS format. This format should work equally as well for those using SuperBBS, Remote Access, or any other mail processor following this type of de facto standard. 5.3. ZmailH 2.0 Syntax: ZMAILH_200 {pass-through}[=root dirname] "Pass-through" can be "P" or "O" (P is default) If "O" then "root dirname" required "root dirname" is root directory path for MSG style areas no space between "O" and "=root dirname" Format: {#|P|O{path}} {tag} [Address ...] "#" is the hudson-style message board number "Address" is 5D format ZmailH 2.0 is the only domain-aware mail processor that I have ever heard of being designed. It has several excellent features very useful for echo hubs in multiple networks, and REC compliments those features very nicely. As far as REC is concerned, the passthrough echo areas created by REC can be invisible using the "P" option, or as MSG-style echo areas using the "O" option. In the case of the latter, you will need to specify the root directory path where REC will need to create the directory for the echo mail to be stored. REC will automatically create any needed directories, and even clean them up as needed if an echo area in MSG-style format should be dropped. ZmailH 2.00 fully supports true 4D addressing (unlike version 1.25) and 5D addressing as well. Flavor support is also supported exactly as it was for version 1.25. Since REC does not have any editing of the flavor codes, the new flavor codes present in ZmailH 2.0 will not have any affect on REC. April 30, 1993 Page 32 Remote Echo Control 2.00 Sysop Documentation 5.4. Squish 1.0 Syntax: SQUISH_10 {S|M} {root dirname} [external AREAS] "S" forces passthrough areas created in Squish format "M" forces uses of MSG-style areas (default) "root dirname" give root path for echo-mail files "external areas" specifies FULL path and name of file to be created in Squish AREAS.BBS format. Format: ECHOAREA {Tag} {path} {area flags} [Address ...] The Squish mail processor is fairly new product that has grown in popularity, primarily due to it's speed and capability to produce the Squish-format message base. It is a full 4D addressing software package. As Squish users know, Squish can work with two different methods of specifying echo areas. In the interest of maximum flexibility combined with minimum code and overhead, REC will handle either file but only in a specific fashion. REC will read and write directly to the SQUISH.CFG formatted file listed in the EchoControlFile statement. Any line not beginning with ECHOAREA will be considered a comment and treated accordingly. This method was chosen since that is the only place that most of the area flags can be specified. However, since many Squish users also need to work the external file in the traditional AREAS.BBS format, REC will also create this file at the same time it updates the SQUISH.CFG file. It must be noted that any changes made to the external file will be ignored by REC. REC will read and write to the SQUISH.CFG file, but it will only write to the external file. Squish does have a nice selection of area flags, but perhaps the most important to multi-zone operation is the "-P" flag. This flag is used to specify which address should be put on messages in the indicated echo area. Since the wrong address can have damaging affects on echo mail processing by your uplinks and downlinks, REC has a method to solve this problem called "SquishFlag". With the SquishFlag statement, you can specify which flags you want added to an echo area definition when particular addresses are added. It must be noted that the entire list is checked, so that multiple matching entries will EACH be processed. This is necessary to allow for specific and general combination of flags to meet your needs. The address field of the SquishFlag statement can use the April 30, 1993 Page 33 Remote Echo Control 2.00 Sysop Documentation "All" type of address, which is another reason to be careful. And lastly, REC will not perform any editing checks on these flags. It is very possible to put duplicate or conflicting flags on an echo if you aren't careful. There are two major uses for this feature, putting a "-P" flag on one of your hubs, and putting a one-way "-X" flag on one of your echo nodes. An example follows: SquishFlag 13:13/2000 -P13:13/70 SquishFlag 1:104/435 -X(1:104/435) With the above statements, assume that the first one is an EchoHub and the second is an EchoNode. Any new echos created for EchoHub 13:13/2000 will get the origin address flag of 13:13/70. Any echos to 1:104/435 will be forced to be one-way links, meaning echo messages are sent to that address but not accepted from. Note that there is no difference between and EchoHub or EchoNode address. 5.5. QMail Syntax: Qmail {root dir name} "Root Dir Name" - root path for all echo-mail directories. Format: [#]{echo-mail directory} {tag} {addresses} "#" indicates a pass-through echos I've begun to get some registrations from those using Qmail, so it seemed like a good time to add direct support for the Qmail mail processor. That's one good reason for registering the REC <grin>. The Qmail mail processor is supported in the manner that it is used to maintain echo-mail directories in the Opus Style, where each echo-mail area is kept in it's own directory. When REC creates a new echo area, it will create a directory for that echo area. When REC should cancel an echo area, it will delete the directory along with any echo-messages in that directory. Addresses in Qmail are supported with full 4D support. April 30, 1993 Page 34 Remote Echo Control 2.00 Sysop Documentation 6. Major Features There are several major features that REC has. Each of these features has its own advantages, restrictions, and requirements. Most of the time, all you will have to do it either add a configuration statement, or add a command line switch to activate the feature. However, you should know what the particular feature will and won't do for you. 6.1. Readdressing Unfortunately, not every mail processor in use today is zone intelligent, or even zone aware. You may run in to a situation where a system has echo mail in a zone other than their primary zone which works fine, but all net-mail will come addressed from their primary zone. Let's consider the following example. You send echomail to 200:5000/211. REC will always use that address to send mail to that system. However, that system is not using a zone-aware mail processor. All message sent to you arrive from 1:104/435. Since REC isn't looking for that address, it won't process any change requests. Also, if you were to define the echo node to REC as 1:104/435, you have to deal with Gateway issues for it to get the zone 200 echos. This becomes a real mess in big hurry. REC's job is to automate and simply your life, not make it worse. As such, the ReAddress statement is used. You put the following line in your configuration: ReAddress 1:104/435,200:5000/211 Using the proper address dimension is critical to this statement. Unlike most other configuration statements, the addresses on this statement do NOT pick up any default zone or net values from anywhere else. What you see if what you get. If a message being addressed wrong on the sending end, REC will log it as an 'Unathorized System" and give the full incoming address as REC determined it. To solve this problem, simply put the address from the log entry on an ReAddress statement, followed by the correct address. Please make sure that that specify zone and domain information if necessary. If the address is coming from 1:104/435 and you put 104/435, the message will not be re-addressed. April 30, 1993 Page 35 Remote Echo Control 2.00 Sysop Documentation When REC reads in the message from 1:104/435, it will change the address to 200:5000/211 and process it that way. Please note that the change is made internally to REC and not written out the .MSG file itself. Any re-addressing that is done is noted on the screen and in the log for your reference. 6.2. Automatic Starting of Echos 6.2.1. From Echo Hubs The entire idea of REC is to automate the handling of your echo mail distribution. There are times that your echo hub just start sending you a new echo, and REC has the capability to automatically add this new echo to your Echo Control File. This feature requires the use of two configuration statements, "AutoStart" and "BadEchoMsgDir", and one command line parameter, "/S". Both of these are defined in the section on the configuration file. Now you will find out how these statements are used by REC. When REC is run with the "/S" parameter, it will scan every message in the BadEchoMsgDir. Each echo message will be checked to see if it matches an AutoStart statement in your configuration file. To have a match on a particular AutoStart statement, the message must be addressed from and to the addresses shown on the autostart statement. If a match is found on any of the AutoStart statements, the message will be saved in memory and the next message will be processed. Any non-echo messages encountered will be ignored. After all the messages are scanned, REC then checks to see if echo areas on the individual messages are already defined in your echo control file. If so, the message is ignored. Otherwise, it is added to your echo control file as a pass-through area with the system the message came from as the echo area's feed. An appropriate message is sent to the Sysop indicating what happened, and entries are made in the log. You should remember a few things about this. First, it is not recommended that this be setup for your downlinks. You should have your downlinks use the Automatic Forwarding feature to get echos that you are not already receiving. Second, while REC can only match on net and node numbers when it scanning the bad echo messages, you MUST give the zone address on the AutoStart statement if you running zone- April 30, 1993 Page 36 Remote Echo Control 2.00 Sysop Documentation aware. The addresses on the AutoStart statement will follow the normal Address Defaulting, and failure to give the correct zone number could result in the wrong address being added to your echo control file. You may notice that what REC adds to the echo control file is a dead-end echo, or an echo that is coming in as a pass-through area and not being sent to any of your downlinks. This is the exact same type of echo that is automatically cleaned up by REC during Automatic CleanUp Processing. It sounds like REC will start the echo the day it comes in, and then automatically clean up the echo with the next maintenance run. Well, REC is a little smarter than that. Any echos that are Auto-Started like this are protected from Automatic Cleanup for a certain number of days. This way your downlinks have a chance to get on to the echos before they simply disappear. This delay is controlled using the CleanUpDelay statement, which is described in the Automatic CleanUp section. You can run AutoStart either once a day or every time you process mail. I would suggest running it whenever you have finished processing your echo mail, and you have messages in your Bad Messages directory. Running Autostart once a night could leave you with dozens (or hundreds) of individual messages in your Bad Echo Messages Directory. This could result a large and sudden increase in disk space, and well as the possibility of loosing some of the messages. 6.2.2. To your downlinks It would seem that I only thought of about half of the use of the AutoStart statement when I originally added in to one of the first versions of REC. Effective with version 2.00 of REC, it is possible to have autostarted echos from your echo hubs also automatically passed on to downlinks that you have identified. This is done very simply by adding the downlinks addresses you want to be auto-started to the auto-start statement. Any echos that come in and are automatically created by a particular AutoStart statement, will also have the downlink addresses from that same AutoStart statement automatically added. This can cause some confusion with regards to AutoStarting to downlinks and Forwarded echo requests using the Delay-Echo-Start option. The AutoStart to Downlinks is intended to be used with new echos that are brand new to the distribution system, not an existing echo that has just been requested by one your downlinks. Any echo that has been Auto-Started and that also has at least one request on Forward-Hold will be exempted from AutoStarting to your April 30, 1993 Page 37 Remote Echo Control 2.00 Sysop Documentation Downlinks. Should an echo be AutoStarted on your system that was not requested by one of your downlinks, it will be subject to the Downlink side of the AutoStart statement. Typically, this type of situation only occurs between the top- stars of the echo distribution system and all coordinators down to the net level. But that does not need to be the case if you do not wish it. I STRONGLY RECOMMEND that you do not put a downlink on an AutoStart statement without their prior approval. This could lead to unexpectedly higher phone bills just to receive echos that the downlink will not be able process. To quote a line from the movie "Hunt for Red October" which expresses my reasons rather well, "Wars have begun that way, Mr. Ambassador!". We all get in to enough trouble without going out of our own way to find even more <grin>. 6.3. Automatic Forwarding I have mentioned Automatic Forwarding a few times, so now I will explain this neat little feature. You don't have to be an echo hub for long before one of your echo nodes asks for an echo that you are not receiving from your own echo feed. This feature will allow you automatically pass on a request to your own echo feed to start the echo. The receiving address, receiving name, and subject line are all populated from the Echo Hub entry. To have a message to an AreaFix program, put "Areafix" (or whatever your echo feed is using) as the Echo Hub's send-to field and the password on the subject field. Remember you have to specify the class as either AreaFix or REC to either of those programs. It can't really be much easier. 6.3.1. Echo Lists As more and more echos are being added to backbone systems in a variety of BBS networks, it can be difficult to keep track of which echos are valid to which system. Echo tags can be spelled incorrectly, or requested from the wrong echo-hub, and thus create a nice little mess for you to fix. Fortunately REC has a very powerful means to control this problem: Echo Lists. One or more echo-lists can be defined for each echo-hub you have defined to REC. Each list contains a name and optional description for each echo that is available from that particular echo hub. Before an echo request is forwarded to an echo-hub, the echo-lists are rapidly searched to make sure that the echo tag is valid. If it is valid then REC will check to make sure that the requesting echo-node April 30, 1993 Page 38 Remote Echo Control 2.00 Sysop Documentation has access to that echo. If this is true then the request is granted, otherwise it is politely refused. The syntax for the echo-list is very straight forward. Every line in the echo-list is an echo. The first word on the line is the echo tag name, and everything else on the line is the description. There is only one restriction with regard to echo-list file names. The actual filename, without the drive:\path or extension, must be unique for each echo-list. For example you cannot use the filenames FIDONET.NA and FIDONET.NO for your echo lists, even if they are in separate directories. The filename is used internally by REC and identical file names will only cause confusion. An echo-list is not used directly, but instead is quasi-compiled for faster and random access. When an echo-list is added or changed, REC will re-compile the list. This compiling consists of creating a binary search tree from the echo-list, which can be searched rapidly and easily for any echo tag name. The descriptions are put in to a random access file so they can be obtained quickly, should they be needed for any of REC's reports. REC detects a change in the raw echo-list by a simple file-date check. If the file dates between the raw and compiled echo-lists do not match, REC will recompile the echo- list. Do not attempt to modify the echo-list files that REC creates. They may appear to be in a random order but they are not. If you alter them in any way, REC will loose performance and can possibly crash. If you need to make any changes, make them to the raw echo- list so REC can adjust it's files accordingly. Echo-Lists can have a major influence on REC's Security Scheme. You should read the security section on Echo Security before using echo-lists. 6.3.2. Delayed Echo Start This option will only work for an EchoHub that is listed in an AutoStart statement. It is however, one of the most powerful and useful statements in REC, and it solves a common problem that happens when you are an echo hub for any length of time. If you do not use echo-lists for all of your echo-hubs, then this statement is very important. At some point in time, one of you Echo nodes will request an echo that you will forward on to your hub. For some reason, your echo hub will come back with a message saying that you have been denied that echo. This could happen because the echo is restricted, or because it doesn't exist. Now you have to manually remove the echo from your echo control file, and manually notify the downlink that the echo won't be coming in. So much for automating all the work in being an Echo Hub. April 30, 1993 Page 39 Remote Echo Control 2.00 Sysop Documentation With the Delayed Echo Start feature, this is no longer a problem. This option causes the Automatic Forwarding routine to do something a little bit different. Instead of automatically adding the echo to your echo control file, it puts the echo request in a holding file. The echo is then forwarded off to your echo hub just like before. When the echo starts coming down, it will automatically get added to your echo control file using the AutoStart feature described earlier. But REC will also check to see if the echo is listed in the holding file for one of your echo nodes. If the echo is found in the holding file, the echo node that requested the echo will be added to the echo in your control file. The echo node will also get a net-mail message from REC indicating that the echo has been activated and they can expect to see the messages any time. If more than one echo nodes requests the echo, only the first request will be forwarded on to your echo hub, but all of requests will be put in to the holding file. Likewise, when the echo is automatically started, all of the requesting echo nodes will be added to the echo and notified as well. If the echo is rejected by your echo hub for any reason, the echo will obviously not get sent to your system and get automatically started. The echos that are on hold are reported on the Sysop Status Report and the Notify messages sent to your echo nodes. The requests are also given a date and time stamp, so you can tell how long the echo has been on hold. At this point in time, REC will not clean out this holding file. If you see requests that are still in the hold file, you can either delete them (either the entire file or just the line in question), or you can manually issue a request to your echo-hub to start echo and see what happens. 6.3.3. Force Forward When all is said and done, there will always be an exception to the rule. The Force Forward feature allows you to prepare for that exception, and as such I expect that this statement will rarely be used. The Force Forward feature allows you to forward unknown echos to an echo hub, regardless of the presence of an echo-list or not. The way it works is fairly easy. If an echo request is not located on the echo control file and is not found in any of the echo lists, the request will be returned as "Unknown Echo Tag" and summarily ignored. The Force Forward feature will override that result, and REC will pass the echo on to the indicated echo hub. April 30, 1993 Page 40 Remote Echo Control 2.00 Sysop Documentation This only happens if the echo is NOT found anywhere. If the echo is found on any echo list and the echo-node does not have access to that echo-list, the echo will not be activated or forwarded regardless of the presence the ForceForward statement in the configuration file. This feature should only be used when you do not have an echo list for a hub and you wish to allow your echo nodes to forward echo requests. REC works much more accurately with an echo list, but the Force Forward feature allows it to work without one. 6.3.4. Top Star Sytems A Top Star system is a special case of echo distribution. In this situation, you would be the highest point in the distribution tree meaning that you send the echo to downlinks but you have no uplinks. These are typically ZEC, REC, and NEC systems for echos that range only in the appropriate zone, region, or net (respectively). In such situations, a top-star echo will not becoming from any defined echo-hub. Therefore echo-source address will be blank and the echo considered non-sourced. However, you can create a special type of echo-list called a "Local" echo-list. To put it simply, when you define the echo-list on the EchoList statement, you put the word "Local" in for the echo-hub address. You then can grant access to the entire list of echos rather than on an echo-by echo basis. 6.4. Suspend & Resume An echo node can now temporarily stop the flow of echo traffic and then start it backup when they want it. The node simply sends a ":SUSPEND" command to REC to stop the echos, and a ":RESUME" command to start them back up again. The suspended echos are kept in a file separate from the echo control file, which means that if an echo becomes a dead-end from a Suspend command, it will be subject to automatic cleanup. When the echos are resumed, any such echos will be turned backon at the echo-hub - providing they are still valid. While the Resume command will bypass any lockouts or other security issued, the echo tag will be verified before it is reconnected to the downlink. If they echo doesn't exist on the system, it will be searched for in the appropriate echo-list. If it not found, a message to that affect will be sent to the node. Both the Suspend and Resume commands force a separate report to be sent to the node, listing all echos that were acted upon. April 30, 1993 Page 41 Remote Echo Control 2.00 Sysop Documentation 6.5. ReScan Mode REC has two different methods of supporting echo ReScan requests, list-mode and command-mode. However both are activated in the same manner. First, the ReScan statement must be in the configuration file. Secondly, the echo-node must put the ":RESCAN" command in to the message that they send to REC. If the node is already receiving the echo, the echo will be placed on the rescan file. If the node is not receiving the echo, REC will first attempt to add the node to the echo in the normal fashion. If that attempt is successful without forwarding the echo request, the echo will be placed on the rescan file. The list-mode of ReScan statement is the more common method. REC will simply put the echo-tags to be rescanned in to a list which you can use with your mail processor. This is the way that REC has worked previously. The command-mode of the ReScan statement is intended for Squish users, but others in similar situations may use it. In this method, REC will write a command line to the given file name, which is usually a batch file. This command line will include whatever is neccessary for the mail processor to rescan the echo, and includes two "markers" to allow you to insert the echo tag name and requesting node address on the command line if you wish. The basic format of the command line is considered free form. You can put whatever characters you wish after the file name, and they will be put on every single line that REC puts out to the rescan batch file. The marker fields are %TAG% and %NODE%, and they indicate which point REC should put the echo tag and requesting node address on the command line. For example, the syntax below would produce the following file: ReScan Command RESCAN.BAT Squish ReScan %node% %Tag% SQUISH RESCAN 1:104/66 FIDOSYSP SQUISH RESCAN 1:104/317 AI Note that the markers are not case-sensitive and that the entire line is converted to upper case when written to the rescan file. April 30, 1993 Page 42 Remote Echo Control 2.00 Sysop Documentation 6.6. Gateway Function The Gateway function of REC is specifically designed for systems that serve as a echo-mail gateway between two networks, AND that run the Zmail mail processor, AND use a gateway software package such as FNPGate (by Jason Steck). All in all, this should be a very small number of systems, but the feature is worth a few words. If you do not fit the above criteria, then this part of the documentation will be of no use to you and it can be skipped. The Gateway statement allows the forcing of Zmail Flavor codes on to certain addresses in the echo control file. A check is performed on an echo every time a node is added to an echo. If source of the echo matches Hub address on the Gateway statement and the echo node address matches the echo Node on the Gateway statement, then the indicated flavors are applied. REC will check to make sure that the flavors do not already exist before it adds them, but it is advisable that the only flavor code to be added is the "*" code. This will keep the message around for further processing by the FNPGate software (or similar) package. The use of this feature is best explained by review of the Zmail documentation and the documentation for your gateway software. 6.7. Batch Mode 6.7.1. Overview There will be times that is will be easier and faster for you to submit an update to REC than to wait for the echo node to send mail. Also there are be certain things that an echo node cannot do, such as change your board names and echo tag names. Batch mode allows you to do this with a simple text file and a command line parameter. Batch mode is optional for the Sysop. You may feel it faster and/or easier to make the change directly to the echo control file yourself. However, batch mode is reported in the log file which provides an audit trail. It can also be used to perform certain updates at a particular time, such as nightly maintenance when you would prefer to be sleeping comfortably. April 30, 1993 Page 43 Remote Echo Control 2.00 Sysop Documentation Perhaps it single greatest advantage is in transferring an echo node from echo hub to another. You could just setup an event to run REC with your special batch command file at a particular time, and let REC make the necessary changes while you are doing something else. The commands can be entered in to a file, or specified on the command line. If you only have a couple of commands, it will be easier to specify then on the command line. However, if you have several commands you will find it easier to put them in to a simple text file. There is a special file name that REC will always look for, and execute if it is found. This file name is BATCH.REC, and once it has been processed it is immediately deleted so it won't be processed more than once. You can also specify your own file name via the "/B" parameter, and the only difference is that this file will not be deleted once it has been processed. You simply create the file of commands in any straight ASCII text file, and then specify the file name on the parameter. The following example will show using a batch command file named "NOTIFY.TXT": REC /BNOTIFY.TXT The third way to use the batch commands is via the command line. You simply put a "/B*" as THE LAST parameter on your command line. You then follow it with the batch commands as you type them in to a text file. Please remember that each batch command consists of two parts: A Keyword followed data. For each batch command you put on the command line, you need to have two parameters. First you specify the keyword, then a space, and last the data. If the data field has more than one piece, each piece must be separate by a comma. You CANNOT put a space in the data part of the command. For example: REC /B* NOTIFY 1:104/317 ADD PIRATE,415 NOTIFY 415,Silly_Fool The above example has 3 commands: Notify, Add, and a second Notify. The syntax of the commands are shown below. But you should notice that on the Add command "PIRATE" and "415" are separated by a comma and not a space. All of the commands and data are case- insensitive. If you have noticed that I put everything in uppercase except for "Silly_Fool", you need to realize that the "Notify" command is a little unusual. Please read about it before you attempt to use it. April 30, 1993 Page 44 Remote Echo Control 2.00 Sysop Documentation 6.7.2. Commands To use batch mode, first you create a simple text file with any text editor. In this text file you just list the commands you want to execute with any needed parameters. The complete list of available commands is shown below: Add - This command allows you to add an echo node to an echo tag. ADD {tag},{echo node} Board - This command allows you to change the board of an echo. You must specify the tag and the new board value. BOARD {tag},{board} Cancel - This command will force a clean up of an echo that is not a dead-end echo. What it will do is send a notification message to echo node receiving the echo, and then remove the echo node from the echo. The board of the echo will also be set to a pass-through. This will cause the echo to be cleaned up the every next time REC is run in clean up mode. Cancel {tag} Change - This command will allow you to change of one address to another address, for either a specific echo or all of them. This statement is very powerful, but as such is very DANGEROUS. Do not use this command without thinking first. See the section on Switching Echo Feeds for more details. CHANGE {echo-tag},{old address},{new address} Create - This command allows you to create an echo area. Because of the support for multiple mail processors, this statement has an unusual syntax. You specify a list of fields, each separated by a comma, in the same order that they would appear in the echo control file. There is no limit on the number of fields that can be listed. You can add echo nodes to the echo here or via "Add" commands that come after this statement. CREATE {field}[,Field ...] Drop - This command allows you to remove an entire echo from your echo control file. It is completely deleted from the file. DROP {tag} April 30, 1993 Page 45 Remote Echo Control 2.00 Sysop Documentation Flavor - This command allows you to set flavor to an echo for a particular echo node. Any flavor specified on the address directly will be ignored. The flavor must be placed after the echo node. To remove all flavor from the tag and echo node, use the special flavor of "*_NONE_*". The special name for all tags can be used (see below). FLAVOR {tag},{echo node},{flavor} Notify - This is a unusual command, since it doesn't behave like the other commands. It doesn't create a notification message right away, but instead puts the information in a small table which will get processed by the usual Notify Routines at the usual time. You do NOT need to specify the "/N" parameter to make this command work. The "to-name" is also unusual, since it will be put on the message to the person the message is sent to. For that reason, any spaces in the name need to be shown as underscores ("_"), and the case that you use will be repeated exactly. This field will default to "Sysop" if it is omitted. NOTIFY {address}[,to-name] Relink - This command will force REC to create a net-mail message requesting the starting of all echos connected to that address. It's purpose is mainly for the situation where your echo hub looses their echo control file and tells you to "reconnect" to all of your echos. Read the Switching Echo Feed section for more details. RELINK {echo-hub address} Remove - This command allows you to remove an echo node from the distribution of an echo. The special tag for all tags can be used (see below). REMOVE {tag},{echo node} Tag - This command allows you to change an echo tag. You must specify the current tag value, and the new value you wish to use. TAG {current tag},{new tag} UnLink - This command will force REC to send a message to the indicated echo hub to turn off or disconnect all of your echos from that system. Please read the section on Switching Echo Feeds for more information. UNLINK {echo hub address} April 30, 1993 Page 46 Remote Echo Control 2.00 Sysop Documentation 6.7.3. Processing Notes The Cancel command is perhaps the only command not easily understood. It is designed to be used when you are told that a particular echo is no longer available. For example, if your echo hub tells you that ECHO_XYZ has been cancelled by the moderator, you will want to remove it from your distribution. You will also need to notify your EchoNodes so they can to the same. By using the Cancel batch command, your echo nodes will be notified, and the echo will be removed from your control file. There is a special tag name that will cause the command to work on any echo tag. This can only be used on Remove, Change, and Flavor for obvious reasons. The special tag value is "*_ALL_TAGS_*" and is not case sensitive. You should remember one thing about Batch commands. It is assumed that the sysop know what they are doing. The Lockout, LockIn, and Security statements are not considered at all when you use these batch commands. This give you both maximum power and control, but also means you must be sure that you are doing what you mean to do. 6.7.4. Switching Echo Feeds There are 3 batch command that you will most likely never use. But just one use will make their worth obvious. These 3 commands are CHANGE, RELINK, and UNLINK. These three commands allow you to perform very simply the most dreaded task of any echo hub: switching your feed from one system to another. This situation will invariably happen to any echo hub that has been around for any length of time. Your own echo hub will be going away and you have to go through the tedious process of typing manual disconnect messages, changing your echo control file addresses, and typing manual connect messages to the new hub. That hassle is a thing of the past with this version of REC. To perform this tedious task very simply, you need to do 3 simple steps. First, edit your REC configuration file to have both your old and new echo hubs are listed in EchoHub statements. Second, issue the batch commands as shown below. And third, edit your REC config file to remove the old echo hub from all references, including AutoStart and Secure statements. Those 3 little batch commands are: April 30, 1993 Page 47 Remote Echo Control 2.00 Sysop Documentation Unlink {Old echo hub address} Change *_ALL_TAGS_*,{old echo hub address},{new echo hub address} Relink {new echo hub address} In the case were there are certain echos that you don't want to change, you can just add to extra commands and have this: Unlink {Old echo hub address} Change *_ALL_TAGS_*,{old echo hub address},{new echo hub address} Change echo_one,{new echo hub address},{old echo hub address} Change echo_two,{new echo hub address},{old echo hub address} Relink {old echo hub address} Relink {new echo hub address} I can't think of an easier method to do this, short of not being an echo hub <grin>. 6.8. Notify Mode This is a quick and simple way to let your echo nodes what echos they are receiving. This helps to make sure that your echo node is getting only the echos desired. During this Notify Mode, REC will still process any batch command files and inbound messages addressed to REC. Most often, you would use this mode once a week in a maintenance mode. An example is shown below: REC /N This above example show the command line parm of "/N". This forces batch notify mode, and will send an Active Echo Report to every EchoNode and ExtraNotify listed in the configuration file, excluding any ExcludeNotifies that you have listed. If desired, you can have REC create a sysop's status report during notify mode. This report is described next. 6.9. Status Report The Status Report is can be generated by two different means. If the StatusReport configuration option is used, the report will generated when REC is run in Notify Mode (/N parameter, see previous section). It can also be generated by running REC is Report Mode. While running in report mode, REC will still process any batch command files or inbound messages. An example is shown below: April 30, 1993 Page 48 Remote Echo Control 2.00 Sysop Documentation REC /R The status report is sent as net-mail to the address shown in the first Address configuration statement, and address to the name listed in the Sysop configuration statement. This report is broken down into several sections consisting of summaries and echo listings. They are shown below: 1 - Classification and summary of the echos in your echo control file (Local, Imported, Pass-through, dead-end, etc.) 2 - A summary of your echo hubs and how many echos you get from each one. It will also note the number of echos from that particular hub that do not exist on any of your echo-lists. 3 - A summary of all your echo lists, and how many echos you are receiving from each one. 4 - A summary of your echo nodes and how many echos each one gets from your. A single line will separate each zone in the listing. 5 - A listing all echos on "Forward Hold", or forwarded and waiting to be started by your echo hub. 5 - A listing of all echos on CleanUp Hold. 6 - A listing of all dead-end echos. You should realize that while the Echo Area Summary reports on every echo in your echo control file, the Echo Hub and Echo Node summaries do not. The total number of echos reported in the Echo Hub summary will equal the total number of echo areas ONLY if every one of your echo mail feeds are listed as an echo hub in your configuration file. It is recommended that you create the your status report on the same run as your Notify Mode. You can do this by either putting the line StatusReport in your config file, or by putting a "/R" on the command line of REC. It is also recommended that the Notify Mode and/or Status Report modes be generated on a run of REC that is not doing anything else. The reason is that the report is generated from information in memory, and not on the disk files. The CleanHold and ForwardHold sections of the report may be inaccurate if you create your status report on the same run as CleanUp or AutoStart. April 30, 1993 Page 49 Remote Echo Control 2.00 Sysop Documentation 6.10. Automatic Cleanup 6.10.1. Overview This was a major function that I felt was needed in order to completely automate the control of your echo mail traffic. This feature will automatically find, cancel, and drop any echo that being sent to your system but is not be sent to any other systems and is not being imported. To activate this mode, you use the /C command line option, as shown below: REC /C The way this works is simple, but you may need to read this section twice to understand it. It sounds far more complicated then it really is (I wish I could say the same thing for the program code!!). There are two parts to the CleanUp processing. The first part will drop any echos already cancelled, and restart any cancelled echos that are no longer dead-ends. The second part will cancel all new dead-end echos found. The link between the two parts is a control file. The second part writes a control file listed all dead-end echos found and cancelled from the automatic hubs. The next time REC is run in cleanup mode, the first part will read in this control file, and use it either drop or restart the cancelled echos. I STRONGLY RECOMMEND THAT YOU RUN CLEANUP MODE ONLY ONCE A DAY, IDEALLY DURING NIGHTLY MAINTENANCE. This means it becomes a permanent part of your nightly maintenance routines. Running cleanup mode on a weekly basis would result in a week delay in either dropping or RESTARTING a cancelled echo. If this option is implemented incorrectly, you can drop several of your echos from your control file that you either don't want to or that you should drop just yet. Please read this section carefully so this will not happen. I will give both an explanation and examples in the following paragraphs. Since the process really starts with the second part, I will start there. April 30, 1993 Page 50 Remote Echo Control 2.00 Sysop Documentation 6.10.2. Processing First, REC searches the echo control file looking for any echo that is 1) a dead-end, and 2) controlled by automatic hub. A message is sent to each hub necessary, instructing the hub to stop sending you those echos. A status message is sent to you indicating that the echos were cancelled. Example: You run REC in cleanup mode during nightly maintenance. During cleanup mode, REC finds that you are getting two dead-end echos from hub #1, SPORTS and FICTION. A message is sent to Hub #1 with the necessary commands to cancel these echos. The echo tags and the appropriate hub address are written to a control file. You are sent a status message listing the echos as cancelled. During the following day you should receive a reply from the echo hub that the echos were stopped. The next time REC is run in cleanup mode, it reads in this control file. If the hub is still automatic, the echo is still a dead-end, then the echo is dropped from your echo control file. Example: The next night you run REC in cleanup mode again. It finds and loads in the control file showing SPORTS and FICTION were dropped from hub #1 the previous night. However, during the 24 hours between the two cleanup runs, one of your echo nodes requested and was connected to the SPORTS echo. A message is sent to Hub #1 re- activating the SPORTS echo, and the FICTION echo is dropped from your echo control file. You are sent a status message indicating that the SPORTS echo was restarted, and the FICTION echo was dropped. 6.10.3. Important Notes There are some important things to remember. First, if you change a hub from automatic to manual between the two cleanup runs, and an echo needs to be restarted, you will get a message on the status report that an echo needs to be manually restarted. Any echos that should be dropped will be dropped as normal. Second, if a echo node should be added to one of the dead-end echos cancelled the previous night, the echo will not be restarted from the echo hub until the second cleanup run. In other words, during normal processing, echos are not checked to see if they need to be restarted if a echo node should request an echo. Lastly, all of this is noted in REC's activity log. You are also sent a message indicating what was cancelled, dropped, or restarted. April 30, 1993 Page 51 Remote Echo Control 2.00 Sysop Documentation Please note that you will only receive this message if there actually was something cleaned up. 6.10.4. Clean Up Delay There is one situation in which you don't want to delete a dead- end echo. That is the situation where your echo hub has automatically added an echo to your system using the AutoStart feature. In this case, the REC will find the echo in the CleanHold control file, and it WILL NOT be cancelled. Instead, a "day counter" will be incremented. Once this day counter is greater than the setting of the CleanUpDelay (default is 5 "days"), the echo will be dropped from the CleanHold control file and cancelled. Note that if the delay is set to 5 days, the echo will not be cancelled until the 6th cleanup run after the echo was Automatically started. 6.10.5. Auto Cancel Delay In these days of multiple networks and less expensive high speed modems, more and more systems are picking up mail over long distance. Many times these systems will only be called once a night or sometimes once every few days. This causes a serious problems with the default of 1 day between an echo being stopped and dropped. For example, assume that REC cleans up an echo named ABCDE from a long distance system that you only call once a night. The echo stop message is sent on the first day during maintenance. When you call and deliver the message, you may pick up mail in that echo. That mail get's processed with no problem. Later during the day, your echo hub will process echo mail, most likely generating more mail for you in ABCDE echo before the net-mail cancel message get's processed. The second day REC will drop the echo during nightly maintenance. The next time you call up that long distance system, you will pick up the last of the ABCDE echo mail along with your reply to the cancel message. When your mail processor kicks out the bad echo mail, REC will promptly use the AutoStart feature and turn the echo back on. Now the echo will sit on your system for the number of days specified by the CleanUpDelay statement (default of 5) before it can be cancelled again. During that delay period, you have an echo listed on your system that it not coming from your echo hub, and this can cause a good bit of confusion. The solution is the AutoCancelDelay statement. You use this statement to specify the number of days between the sending of the echo stop message and the echo being dropped from your system. At any time during this delay period, if one of you echo node requests the April 30, 1993 Page 52 Remote Echo Control 2.00 Sysop Documentation echo, it will automatically be restarted. At the end of the delay period, the echo will be dropped. 7. Security I wish there was a world in which no form of security or protection was needed. Unfortunately, there will always be those type of problems which will required a form of security. REC's security is designed to prevent accidental errors instead of intentional mischief. Even with this design in mind, much of the mischief can be easily prevented using the security features designed in REC. REC uses a 3-layer security scheme based on security flag matching. There are 4 different statements where echo can be assigned security: EchoHub, EchoList, DefaultSecure, and EchoSecure. An echo- node can only be assigned security via the EchoNode statement. An echo-node is allowed to receive an echo when the echo-node has been assigned all of the same security flags the the echo has been assigned. The set of security flags for each echo is determined in the same manner. The echo source address is determined for the echo, and then each echo-list assigned to that address is searched for the echo tag name. If the echo is found then it picks up whatever security was assigned to the echo-list, otherwise the echo will pick up (or inherit) the flags assigned to the echo-hub that matches the echo's source address. Should the echo not have an echo source address that is defined as an echo hub, only "Local" echo-lists will be searched. If the echo is not found on any "Local" echo-list, the echo will inherit the security on the DefaultSecurity statement. If this statement is not present in the configuration file, the echo will have no security and anyone will be able to request it. The last step involves a quick search of the EchoSecure statements. If the echo tag in question is found on any of these statements, the security flags from that statement will be automatically added to the echo in question. It should be made very clear that they entire key to this process is the proper determination of the echo's source address. For that reason, REC provides a security "Dump Report" that states (verbosely) exactly what REC thinks of each and everyone of your echos. April 30, 1993 Page 53 Remote Echo Control 2.00 Sysop Documentation 7.1. Dump Report When REC is run with the /V option, a file called REC_DUMP.RPT is created in RECDIR directory. This file lists each echo and all the information about that particular echo that REC has recognized. If you have any problems with REC, this is the first report you should look at. But for the purposes of this section, we will only be dealing with 3 fields: EchoList, Source and Security. If the echo being shown on the report was found in an echo-list, the file name [excluding path and extension) of that echo list will be shown. If the echo isn't found on any echo list, this line will not be shown. For each echo shown, there will be a line labled "Source:", followed by the network address that REC believes to be the source address of the echo hub where this echo comes from. If the echo is non-sourced, this line will show "<None>". The Security line is always present, as it indicates the exact security that REC has assigned to the echo. This line has two parts with the first part indicating where the security came from (List or Source) and what that security was. The second part indicates if any security was taken from EchoSecure statements in the config file. Other features of this report include a listing of all Lockins and Lockouts that affect the echo. The board number, location, area flags, and all downlink addresses are also shown on this report. Finally there is an estimate of the amount of memory it takes to store that particular echo in memory. At the end of the report is an estimate of the total amount of memory needed to store the entire file. 7.2. Changing Echo-Source If an echo comes back with the wrong source address, you can force REC to use the correct address with an EchoSource statement. Remember that if you specify an address that isn't listed as on of your EchoHubs, the echo will be considered non-sourced. Since only the echo lists associated with the echo source are searched for the echo, the correct echo-source is very important. The vast majority of the time REC will assign the correct source. However, it may assign the wrong source if the same echo is going to April 30, 1993 Page 54 Remote Echo Control 2.00 Sysop Documentation more than one address that is listed as one of your echo-hubs. The source can also be wrong if you are sending on of your top-star echos to your local echo-hub. Only non-sourced echos are looked for in the Local echo-lists. 7.3. Lockout & LockIn These two statements perform exactly the opposite functions. The Lockout statement will prevent a particular echo node from accessing an echo no matter what security flags they have. The LockIn statement will not allow an echo node to cancel an echo for any reason. 7.4. Duplicate Echo Tag Names In these days, more and more echos are being "gated" between networks. Add to this the fact that more and more systems are working in multiple networks and the chance of duplicate echo tag names becomes a serious reality. Under no circumstances should echo tags be duplicated in one network or between networks - except if the echo is being gated between those networks. And this is the exact situation where automated echo managers have problems. The easiest way to explain this situation is with a real example - my own. The ZMAIL echo is a MetroNet echo but it is gated in to FidoNet as well. I belong in both MetroNet and FidoNet, so I can get the echo from either source. But my FidoNet downlinks can only get the echo via my FidoNet source, and my MetroNet downlinks can only get the echo from my MetroNet source. Putting MetroNet downlinks on the echo sourced from FidoNet would violate several Echo-Mail policy rules of both networks and risk a very nasty dupe-loop. This is another reason why correct echo-sourcing is so criticial to REC's security. If the ZMAIL echo is coming from FidoNet, it will be found in an echo-list from my FidoNet uplink. As such, it will inherit FidoNet security and any of my MetroNet downlinks will have to get the echo from another source. April 30, 1993 Page 55 Remote Echo Control 2.00 Sysop Documentation 8. Error Messages REC can return many different messages, and not all of them are errors. In this section, I will list all of the error conditions, and where they are reported. Everyone of these errors/messages will be sent to the log file and the display screen. I will not be covering the configuration errors, since they are well detailed by the program error message if any should be encountered. The error messages are broken down in to the following groups: Message Procesing, Batch Processing, and Cleanup Processing 8.1. Message Processing Added - You were added to the distribution for the echo requested. Already on Hold - The echo is waiting on hold for your system already. Removed - You will no longer be sent the echo that you have requested be stopped. Added and Forwarded - The echo was not already being received by your echo hub. As such, it was added to both your echo hub and yourself. The request was also forwarded on to your echo hub's feed. It may take a day or two for you to start receiving the echo, so you will need to be patient. Put on Hold & Forwarded - The echo you requested was not being received by your echo hub. As such, it was forwarded on to your echo hub's feed. Your request has been put on hold until such time as the echo is being sent to your echo. At that time you will receive a message from REC indicating that the echo request has been satisfied. Put on Hold, already forwarded - This is the same as the previous message, with only one small difference. The echo had been requested by another system, and so it had already been forwarded to your echo hub's feed. You will still receive a message when it is being sent to your system. April 30, 1993 Page 56 Remote Echo Control 2.00 Sysop Documentation Report Generated <report name> - This message indicates that the report you request (Active, Available, or Forward) has been generated and sent to you on a separate message. Command Accepted <command> - This message indicates that the special feature you requested was accepted. The commands that will return this message are RESCAN, SUSPEND, and RESUME. ERROR: Not processed - The command was not processed by REC due to an error condition. You should not see this message, but it was added to cover all possible logic flaws in the program where a message command might be skipped. If you should see this messages, please contact your echo hub immediately, and ask them to look in to it on their end. They most likely will end up sending a bug report to me ASAP. Echo found, source unavailable - the echo you request was found, but it is assigned to a source (EchoHub or EchoList) to which you do not have access. Already active - You were already receiving the echo, so you weren't added to it a second time. Insufficient security - You did not have a high enough security level to automatically connect to the echo that you requested. You will need to contact your echo hub directly for access the echo. Locked out - Your echo hub has specified that your system is not allowed to receive the echo. You will need to contact your echo hub directly to find out why. Locked in - Your echo hub has specified that you are not allowed to disconnect from this echo. You will need to contact your echo hub directly to find out why. Not active - The echo you had requested REC to stop sending you was not be sent to you in the first place. Invalid report code - You asked REC to send you one of it's reports, but the report code you used was not know to REC. Not found or forwarded - The echo you requested did not exist, and could not be forwarded because your echo hub has not set you up to be able to forward echo requests. April 30, 1993 Page 57 Remote Echo Control 2.00 Sysop Documentation Unknown echo tag name - The echo you requested was not found on your echo hub's system and was not found on any Echo Listing. Rescan not allowed - In this case, you have request that your echo requests be rescanned, but your echo hub has not activated REC's ReScan feature on their system. 8.2. Batch Processing 'Not Processed': This is the same as the one above. 'Processed': The command was processed correctly. 'Node not found': The node requested was not found. 'Tag already exists': A tag could not be created because that tag was already being used by an existing echo. 'Node already active': The node was already active for the echo. 'Invalid Command': Either the command was unknown or one or more of the parameters were missing. 8.3. CleanUp Processing ' Cancelled': The echo was cancelled from an automatic hub. ' Dropped': The echo was dropped from the echo control file. ' Not found': An echo tag & echo hub combination found in the cleanup control file was NOT found in the echo control file. This can be caused by manually dropping the echo in between cleanup runs, or changing the feed of an echo in between the cleanup runs. ' Restarted': The echo was restarted from the indicated echo hub. ' Manual': The echo needs to be manually restarted for a manually control echo hub. The hub was reclassified as manual in between cleanup runs. AutoStart Processing does not create any report type messages. It creates a simple list of each echo that was Automatically started, April 30, 1993 Page 58 Remote Echo Control 2.00 Sysop Documentation which hub it came from, and which echo nodes (if any) where added to the echo. 9. Bonus Utilities As a free bonus, I have included a few simple little utility programs that I find useful on my system. The command syntax can by found by simply executing the program without any command line parameters. I will give the syntax here as well, along with a short description of what the program does. 9.1. AreaList This program takes an echo control file and produces an alphabetically sorted listing of all echo tags found. No consideration is given for separating by zones. An optional second report can be generated, a list of echos tags in the format required by for the Echo List file. AREALIST {mpc }{echo control file} {list filename} [Echo List filename] The "mpc" is the Mail Processor Code. This is a single number that indicates which of the mail processor formats the file is in. For a complete and current list of these codes, just execute AREALIST without any parameters. 9.2. AreaRpt This program will produce a report from your echo control file. The report is a listing of every system found, and which echos that system is receiving from you. Is is sorted alphabetically. AREARPT {mpc} {echo control file} {report name} The "mpc" is the Mail Processor Code. This is a single number that indicates which of the mail processor formats the file is in. For a complete and current list of these codes, just execute AREARPT without any parameters. April 30, 1993 Page 59 Remote Echo Control 2.00 Sysop Documentation 10. Conclusion Well, that's about all I have to say about REC and the bonus utilities. If you have any questions, feel free to contact me via net-mail to any of the addresses listed below. Send the message to Dan Fitch, or to Sysop. Best of luck in your BBSing, and my thanks for using this software. Later! Dan Fitch Author of Remote Echo Control (REC) Sysop of The Rec Room 1:104/435@FidoNet 13:700/0@YouthNet 31:905/133@CFRNet 116:112/700@PixNet 155:222/435@QBBSNet 200:5000/211@MetroNet Denver, Colorado USA April 30, 1993 Page 60