KINGDOMS KINGDOMS MANAGER DOCUMENTATION Version 2.18 Programming & Design : Dave Chapman : The Web BBS Copyright c 1993, 94, 95, 96 - Dave Chapman All Rights Reserved 3:712/523@FidoNet 61:9600/350@WorldNet 69:1171/200@AdultNet 169:3005/2@BattleNet 151:6121/823@EzyNet InterNet - dave.chapman@ibm.net - Kingdoms Support Page - http://www.magna.com.au/~davec/kingdom.htm KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ TABLE OF CONTENTS SECTION 1 - INTRODUCTION 4 1.1. Overview 4 SECTION 2 - FILE MENU 5 2.1. Edit Paths 5 2.1.1. BBS (Doorfile) Path. 5 2.1.2. Kingdoms Game Directory. 5 2.1.3. ASCII/ANSI paths. 5 2.1.4. Netmail Path. 5 2.1.5. Inbound Directory. 6 2.1.6. Outbound Directory. 6 2.1.7. Recon Directory. 6 2.1.8. Temp file path. 6 2.1.9. Report Viewer 6 2.1.10. KM Defaults 7 2.2. Check Paths 7 2.3. Other 7 2.3.1. Sysop & BBS Name 7 2.3.2. Days to keep old users. 8 2.3.3. Days to keep Log data. 8 2.3.4. Kingdoms Net ID. 8 2.3.5. Poll Frequency 8 2.3.6. Self Correction Frequency 9 2.3.7. Next Reset Due 10 2.4. About Kingdoms 11 2.5. Maint Flag 11 2.6. User On Flag 11 2.7. Logs 11 SECTION 3 - NETWORK 12 3.1. Your Routing 12 3.1.1. Setting Yourself Up : In Brief 12 3.1.2. KIDX.DAT 12 3.1.3. Default Outbound 12 3.1.4. Normal Outbound 13 3.2. Preferences 13 3.2.1. Mail Type - Hold/Direct 13 3.2.2. Crashmail - Yes/No 13 _____________________________________________________________ 2 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ 3.2.3. Compression - Zip, Arj, Rar, None. 13 3.3. Alias 14 3.4. Verify 15 3.5. Erase Routing 15 3.6. Net Times 15 3.7. Zero Times 16 3.8. Defaults 16 3.9. Index File Dump 16 3.10. Link Diagram 16 3.11. Worms 17 3.11.1 What IS a Worm? 17 3.11.2. Spawning a Worm 18 3.12. Other Routing 18 3.13. Reports 19 3.13.1. Overview 19 3.13.2. Worm Report Layout 19 3.13.3. Routing Report Layout 20 SECTION 4 - REGISTRATION 22 SECTION 5 - COORDINATOR 22 APPENDIX A : MAIL ROUTING 23 A.1 Overview 23 A.2. Defining your Routing - Standard Systems 23 A.3. Defining your Routing - Intermediate Hubs 25 _____________________________________________________________ 3 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ Section 1 - Introduction The Kingdoms Manager (or just `The Manager') is the control centre of Kingdoms. It provides the Sysop and Kingdoms coordinator with all facilities needed to manage and maintain the Kingdoms realm operating on his or her BBS and on the network itself. This document is NOT intended to be an installation manual. If you're installing the game, please see KSYSOP.TXT for that sort of information. This document simply takes each option available to you in the Manager and explains what it does and what it's for. If you find yourself stuck, or just want to know more about something in the Manager, then this is a good place to be! 1.1. Overview The Kingdoms Manager (KM) should reside in and be executed from your main Kingdoms directory. This is where KCFG.DAT, the Kingdoms configuration file, resides and where the Manager expects to find it. If the configuration file cannot be found in the current directory when KM starts, the Manager will create a new one using defaults. When you start KM you are presented with the main Manager panel. You can use your arrow keys to select options or use Alt-letter key combinations to jump to an option you want. Menus will pop down for the option you're on and again you can use your arrow keys to choose which option on the menus you're interested in, or press the capitalised letter of each menu option. Having positioned yourself on the one you want, press Enter to select it. The following sections describe each option available and it's function. _____________________________________________________________ 4 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ Section 2 - File Menu 2.1. Edit Paths 2.1.1. BBS (Doorfile) Path. This is the directory where Kingdoms expects to find the DORINFO?.DEF or DOOR.SYS drop file which your BBS creates when shelling to the door. You can override this parameter by using the Kingdoms /D parameter to fully specify the drop file you wish to use. You would do this primarily if you're using the DORINFO#.DEF format drop file, where `#' is the node number in multiline sites. See the Installation section in the Sysop documentation for further detail. This entry is ignored if Kingdoms is entered locally using the /L parameter. In this situation, the required information is taken from the configuration information specified in the Manager. 2.1.2. Kingdoms Game Directory. This is the directory where all your main (.exe) Kingdoms files and game data files (.dat) are located . Generally, this will be something like C:\KINGDOMS. You should be in this directory when you start Kingdoms itself or the maintenance/network utilities. 2.1.3. ASCII/ANSI paths. Kingdoms uses .KDI (Kingdoms DIsplay) format files for scoreboards, newsfiles, and other files created by or used by the game to display information to the players. These files always reside in the Kingdoms (game) directory above. If told to, using the /A parameter at runtime, the maintenance utility (KMNT) will also create ANS and ASC flavours of those files. If created, they are placed in the ASCII/ANSI path specified. 2.1.4. Netmail Path. When Kingdoms creates outbound files, it creates a .MSG style Netmail message in your mailer's netmail folder. The message is a file attach message to which files in the Outbound Directory are attached. The status on the attached files is Kill Sent, which means the files will be removed from your system by the mailer when they've been forwarded to the destination node. If you don't _____________________________________________________________ 5 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ plan to participate in a net, you can just make this C:\KINGDOMS (your Kingdoms directory). If you do, this should be the directory in which your mailer stores its Netmail (.MSG) files. 2.1.5. Inbound Directory. This is the directory where Kingdoms should look for incoming files. It will usually be the same directory specified in your mailer inbound (NOT your mailer download!) directory. If you don't plan to participate in a net, you can just make this C:\KINGDOMS (your Kingdoms directory). 2.1.6. Outbound Directory. This directory is the directory where Kingdoms will put files it generates going out to other Kingdom Realms, or BBS's. It does not have to be a directory related to your mailer in any way and will generally be a directory under Kingdoms for these files, eg, C:\KINGDOMS\OUTBOUND\. If you don't plan to participate in a net, you can just make this C:\KINGDOMS (your Kingdoms directory). 2.1.7. Recon Directory. Data on other Realms is held by Kingdoms in Recon (Reconnoitre) files. These files reside in this directory. Again, this will normally be a separate directory under your Kingdoms directory. If you don't plan to participate in a net, you can just make this C:\KINGDOMS (your Kingdoms directory). 2.1.8. Temp file path. When working, Kingdoms sometimes need to make temporary files and this is the place where they'll be put. Generally, this will be the Kingdoms directory itself. Where you put this does not matter particularly to Kingdoms, but it's recommended you make it a local drive in a networked environment to minimise traffic during heavy disk activity. 2.18 includes the facility for players to chat with each other in a multinode environment. This directory is also used to store the multinode communication files. 2.1.9. Report Viewer _____________________________________________________________ 6 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ This entry is the path *and* filename of your preferred text editor/viewer. When Reports (discussed later) return to your system, the data they provide are stored in various Report files. The editor you define here is executed when you select a report view in the Network options of KM. Valid entries for this field might be : C:\DOS\EDIT.COM (The DOS editor) C:\UTIL\LIST.COM (List) C:\UTIL\Q.EXE (QEdit) You may prefer to use an editor such as QEdit rather than a viewer such as LIST. The worm report is not sorted and holds information from worms in order of arrival. The right editor (eg QEDIT) will allow you to do any sorting you may desire. To accomodate sorting, incoming Worm data always contains the Worm ID then the full Julian date and timestamp of the Worm. Sorting on the first 13 columns therefore will always give you your incoming Worm data sorted by Worm ID, then date. 2.1.10. KM Defaults As mentioned, if an Configuration file doesn't exist, KM will create it for you. The defaults provided are : * BBS (Dorinfo1.Def) Path : C:\KINGDOMS\ * Kingdom (Game Files) Path : C:\KINGDOMS\ * ASCII Text Files Path : C:\KINGDOMS\TEXTASC\ * ANSI Text Files Path : C:\KINGDOMS\TEXTANS\ * Net Mail Path : C:\FD\NETMAIL\ * Inbound Files Path : C:\KINGDOMS\IN\ * Outbound Files Path : C:\KINGDOMS\OUT\ * Recon Data File Path : C:\KINGDOMS\ * Temp Files Path : C:\KINGDOMS\ * Report Viewer : C:\UTIL\Q.EXE 2.2. Check Paths This option will examine each of the entries you've configured in `Edit Paths' to check they're valid. Any which are not will be highlighted and should be corrected before attempting to run Kingdoms. It's a good idea to select this option whenever you've edited your paths as it will pick up any typos that may have crept in unnoticed to you. 2.3. Other 2.3.1. Sysop & BBS Name _____________________________________________________________ 7 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ Self explanatory. Your name and the BBS name. If you decide to register Kingdoms, the names entered here MUST match the ones you send in on your Registration form. If you enter Kingdoms locally, the Sysop name here is also the default logon name in Kingdoms when using the /L startup parameter. 2.3.2. Days to keep old users. Users who have not logged in for the number of days specified here will be removed automatically by Kingdoms maintenance. 30 is a good default. 2.3.3. Days to keep Log data. During maintenance, Kingdoms will automatically trim all it's log files to purge old/unwanted data. The number entered here specifies how many days worth of data to keep when doing the purge. Coordinator's please note : the log created when performing Coordinator functions, such as adding or deleting nodes on the network, is never trimmed automatically as the potential is too high for important historical information to be lost. Any trimming/deletion must be performed by hand on KCOORD.LOG. 2.3.4. Kingdoms Net ID. This field is used to specify which Kingdoms net this game is operating in. If your board is connected to several Kingdoms nets, each Kingdoms game in each network must be set up as a separate game and MUST have a different net identifier. If you're participating in a net, your Coordinator will tell you what Net ID your game is using. Make SURE you get it right as Kingdoms will not process inbound or outbound files if the data within them belongs to a different net Id than the one you have defined. Your Network ID will be alphabetic numeric characters to specify your Id. Special characters will cause problems as this Id is used in the generation of outbound file names from your Realm. The NetId _IS_ case sensitive. An up-to-date list of Network Id's currently in use (so you can select yourself one that hasn't already been used) is maintained on our web site, http://www.magna.com.au/~davec/kingdom.htm. 2.3.5. Poll Frequency _____________________________________________________________ 8 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ Poll Frequency is only used if you're participating in a Kingdoms network. Kingdoms will to keep track of how often mail takes to move between (both to and from) any given node and all other nodes in the Kingdoms network. The value entered here specifies how often, in days, Kingdoms should send automatic polls to all other Kingdoms nodes to maintain network statistics. The statistic data can be viewed by you and your users using option `N' on the Kingdom Realms menu. The data provided will look something like : -*Net Statistics*- Mail to Mail From No. Kingdom Realm Average Average ------------------------------------------------------- 1 - The Web N/A N/A 2 - Bad Company 2 days 3 days 3 - Way Out West 3 days 4 days ------------------------------------------------------- Press any key ... Of course, there will be one node listed for each node in your Kingdoms network. The N/A next to the Web above indicates Not Applicable. The Web in this case, is the home realm and, of course, there are no mail statistics to report! In the above example, it takes two days (on average) for mail to get from The Web (the local Realm) to Bad Company. It takes three days for mail on Bad Company to get to The Web. Note that the Poll Frequency value is based on day in the year (ie, the Julian day) not the day polling was first requested. For example, a value of 4 will NOT necessarily poll other nodes the first time it runs and for every four days after that. It polls if the current day or the year is divisible by four. If you want Kingdoms to poll all other nodes every day, just set the Poll Frequency to 1. 2.3.6. Self Correction Frequency Self Correction is a major feature and an integral part of Kingdoms network management. Since version 2.10, Kingdoms carries the default node routing/link information originally specified by your Coordinator within the Index itself. With this information available, each node is able to intelligently work out what connections (outbound or routed) it should have with what other nodes. This effectively frees the Sysop of each node having to know anything about the network itself as is required to get your routing right in most other InterBBS games. A typical example of where this is useful is when a routing change is required. Rather _____________________________________________________________ 9 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ than the coordinator having to tell every node in the network of the change and make sure everyone affected updates their routing, the Coordinator can simply issue a routing update from his or her node. Each realm the update reaches will then automatically (in inbound processing) re-evaluate it's routing rules and reconfigure them if necessary to the specified settings. It may have already occured to you however that updates may go astray or not arrive at their destination for some reason. If they miss getting a node connection update, how can the problem be fixed without further manual intervention? This is where self- correction is used. The value you specify here is how often you want your node to poll your Default Outbound for `self- correction' information. If you specify 5 for example, then every five days your node will automatically request update information from your Default. The information it recieves and processes by this request is effectively a complete copy of your Default's index file. That information will be compared against the local Index and any modifications to the default routing or to Sysop/BBS names will be applied locally. Likewise, downlinks from THAT node will then receive any missed updates by self correction and the information will flow down the network until all changes are effected on all nodes. Note the importance of the Default outbound here. For self correction to work properly, your Default Outbound MUST be the most direct link `upwards' in the network to the Coordinator node. Thus in many parts of the Manager and in the documentation, the Default is also called your `uplink'. This is required so that correction information always flows outward from the Coordinator node which, by definition, must always be correct itself. If the Default is set to a node which is not on a direct path to your Coordinator, self correction may actually pick up old data which, when re-evaluated, may incorrectly configure your routing based on out-of-date Index information on the link specified as the Default. During the automatic evaluation of your index links Kingdoms will, of course, set your Default to the right uplink. You don't normally have to worry about getting this right as Kingdoms will do it for you. This information is only pertinent to those who need to change their Default manually for some (rare) reason. A self-correction frequency of five is suggested as a good default. The coordinator node must never have self correction turned on and it should be left as a zero value. 2.3.7. Next Reset Due The Coordinator has the ability to force a reset network wide as he/she desires. This line allows you to see if one is due and, if so, when it will take place. If there is no reset pending, the words `None Scheduled' will appear beside the prompt. _____________________________________________________________ 10 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ 2.4. About Kingdoms Gives general information about Kingdoms and the Author. 2.5. Maint Flag When Maintenance starts, a flag within Kingdoms is set on indicating this. If a player attempts to log on while Maintenace is running, Kingdoms will inform them of this and ask them to wait (or exit with a keypress) a short period until it completes before allowing the player to enter the game. If something serious happens such as a crash or power failure while maintenance runs, the flag may not be flipped off as it normally is when Maintenance completes. This will effectively bar players from entering the game at all. Should this happen, simply select this option and confirm you want the flag turned off and all will be well again. If this DOES become necessary, I suggest you also check your KMNT.LOG to see if some sort of error or problem is being reported. 2.6. User On Flag When a player is online, their user record is marked to reflect this. As with Maintenance, a major system problem may mean this flag doesn't get switched off. Selecting this option allows you to turn all `user online' flags off. Of course, you shouldn't run this while someone is actually online! 2.7. Logs Allows you to select any game log for viewing (using the external editor defined in Paths) without leaving the Manager. _____________________________________________________________ 11 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ Section 3 - Network 3.1. Your Routing 3.1.1. Setting Yourself Up : In Brief Network Routing is the area you use to identify your node and the nodes you exchange Kingdoms mail with to Kingdoms. To enter Network Routing, you must have a valid KIDX.DAT file which will be available from your Kingdoms Coordinator. Setting this up is very simple. All you need to do is identify from the list presented which node you are in the Index. Based on the Connection information contained in the Index, the Manager itself will configure the rest of your routing automatically for you. It is not the purpose of this document to tell you how to set this up - the Sysop documentation (KSYSOP.DOC), Installation section can tell you that. Provided here is a general discussion of what things are and what they do so you understand fully what is happening when it is set up, or to give you help if you are experiencing difficulties. 3.1.2. KIDX.DAT The KIDX file is your Kingdoms `nodelist'. It contains an entry for each BBS in your Kingdoms network. Unlike a lot of other InterBBS games, it is not a straight text file you can edit. The reason for this is that Kingdoms manages it, not you, and there is therefore no reason why you should need to edit it manually. Your first KIDX.DAT will be provided by the Coordinator of your Kingdoms network. Any changes from that point on are handled automatically by Kingdoms when the Coordinator distributes them. There should be NO need for you ever to edit this file. Indeed, if you try, you could easily break your routing, so DON'T! 3.1.3. Default Outbound You will have one Default Outbound on your system. Your Default Outbound an outbound just like your Normal Outbound nodes with one important distinction - it is the node to which you connect for Kingdoms mail WHICH IS THE MOST DIRECT PATH BACK TO YOUR COORDINATOR NODE. Normally you don't have to worry about this as Kingdoms will work out which node should be your Default and mark it appropriately and automatically for you. If you are unsure however, you can generate a Link Diagram and identify from that the node your Default should be (it is the node marked `Uplink' _____________________________________________________________ 12 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ in the diagram for your node) and set it accordingly. As described previously, the Default MUST be the most direct path to your Coordinator node for Self Correction to work. If it is not, you should disable Self Correction by setting it to zero. 3.1.4. Normal Outbound A Normal Outbound is simply that. It's a node in your nodelist with which you communicate directly. That is, you call them, or they call you, to transfer Kingdoms data. Like the Default Outbound, you can only route data for other nodes to an Outbound to get it out on the network and to the place it should be going. 3.2. Preferences When selected, a list of all outbound nodes on your system (both Default and Normal) is presented. You can then tailor options for mail for your outbound node(s) to suit your preferences. The possibilities include type of mail, (hold or direct), crashmail (yes or no) and compression type (ZIP, ARJ, RAR or None). While the highlight bar is on the outbound node you're interested in changing preferences for, F1, F2 and F3 will toggle through mail type, crashmail and compressions options respectively. 3.2.1. Mail Type - Hold/Direct Pressing F1 will toggle between Hold and Direct mail for the highlighted node. That is, the .MSG file attach will be marked `hold' (waiting for a call in to pick it up) or direct (will be delivered on either an outgoing or incoming call to/from the destination node). 3.2.2. Crashmail - Yes/No Pressing F2 will toggle crashmail on and off. If on, any new .MSG file attach created will be marked Crash, Immediate. As soon as your mailer has the opportunity to do so, an outbound call will take place to (attempt to) deliver the mail. This generally means an extremely good throughput of mail to/from a system but can cost in terms of phone bills. Not using crashmail generally means you want your Kingdoms data delivered to its destination during normal mail hours/sessions. 3.2.3. Compression - Zip, Arj, Rar, None. Compression is available on all outbound packets in Kingdoms using your choice of the standard compression tools, ZIP, ARJ and RAR. Note that this is specifying compression for OUTBOUND packets only. Kingdoms will scan Kingdoms inbound data, work out _____________________________________________________________ 13 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ what compression format, if any, is being used, and decompress it accordingly if required. In other words - Inbound processing pays no attention whatsoever to what is specified here when decompressing packets - it decompresses inbounds according to the archive type it detects itself. When Knetout runs, it will search for compression on any outbound packets and decompress them accordingly. It will then do normal processing to add outbound data then, according to the type specified here, compress them again ready for transmission. Kingdoms must be able to locate the archiver(s) you have specified either in the current directory, or in a directory on the path, when it needs them. You should, of course, make sure that the destination outbound supports (ie, is able to decompress) any archiver type you choose when compressing mail that is destined for that node. 3.3. Alias Much as it would be nice if everything stayed stable and systems kept working, it is a fact of life that nodes will come and go, addresses may change and other less desirable things may happen. Such events can create havoc with a well running network! To help manage these changes, Aliases are supported under Kingdoms. An Alias basically comprises two addresses - the `Convert From' and `Convert To' addresses. These are simply addresses which allow information destined for one node to be readdressed to another dynamically, or `on the fly'. The following example will explain an example of where this may be necessary. Let's say the a node with address 1:2/3 has dropped their Fidonet link (ie, being a Fido zone) and no longer wants to (or can) use their original address. Let's also assume that the board is a member of BattleNet and has the address 169:2/3 on that network. The node who wants to change should notify their Coordinator who will distribute an Index Change instruction, telling all boards of the change. That's fine, and everyone will start distributing data to the new address as they should, but there may be a considerable amount of data already in transit in the network for the old address. When it reaches a node who has already processed the update, the destination address (the old address) for the inbound transit will no longer exist, and the transit data would be returned to the sender as undeliverable. Not a really good way to do it! This is where aliases come in. Quite simply, when a Change order comes into a node, not only does Kingdoms do the Index change, but it will ALSO, using the example above, create an alias address with a `Convert From' of 1:2/3 and a `Convert To' of 169:2/3. When transit data comes in for the old destination address, but to a node who has the new _____________________________________________________________ 14 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ address in their Index, it (the old address) will still not be found on the Index. Kingdoms will then however, check the Alias file and find the old address in the `Convert From' field of one of the Alias records. What it will do then is replace the destination address on the inbound transit with the `Convert To' address (the correct, or new, one) and continue to process it. The network is not affected, the data gets to where it should and no problems will arise even though not everyone in the network has yet processed updates. Note also that all this happens automatically and there is no need for human intervention, other than for the Coordinator to issue the original Change instruction. You can if you wish set aliases yourself, but there will rarely be a need to do so. It's better to let Kingdoms manage them. A maximum of 10 Alias records are held in Kingdoms at any one time, which should be more than ample. If a new one needs to be added and no space is available, the one which is oldest (referenced the longest time ago) will be overwritten to make way for the new. 3.4. Verify The Verify information in Kingdoms is worth running after you've changed your routing, should you decide to do so. It simply goes through your routing definitions, summarises them, and presents the summary data to you on screen. It's a nice check to see if everything is ok & I suggest you do it periodically. 3.5. Erase Routing If you've done a lot of things to your routing or incorrectly set something, such as your node on the Index file, you can erase all your Routing rules and start over with a fresh slate. This option allows you to do this. Having confirmed this is what you want to do, you will need to reenter the Network Routing options to respecify your node again, or your InterBBS functions will not operate. 3.6. Net Times This is an extended listing of the Net Times list available to players in the Kingdoms InterBBS options. It shows full detail of how long data is taking to get from your node to and/or from all other nodes in the network. The higher the poll frequency set in the `Other' options of the Manager, the more accurate these numbers are likely to be. A on any node in the list (excluding your own, of course) will allow you to send an immediate Recon Request to that node. _____________________________________________________________ 15 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ 3.7. Zero Times Erases the statistics kept for Net Times. This allows you to `start afresh' with your statistics gathering. You would want to do this most probably after things like network problems are resolved to give your players the most realistic view of the nodes you communicate with. 3.8. Defaults As described elsewhere, Kingdoms is capable of fully managing all your network connections for you. You will not normally have any reason to change these defaults Kingdoms sets for you. Should you do so however, the defaults can be easily restored by choosing this option and confirming that this is what you want to do. 3.9. Index File Dump Choosing this option allows you to dump your index, including your current routing definitions, to a standard text file for ease of reference should you wish it. There are times in Kingdoms you may be informed of a problem with node number xx, where xx is the physical record number of a node in your Index file. As all listings in the Manager which show nodes from the Index are sorted alphabetically by BBS name, they cannot be used to identify which node Kingdoms is talking about in these messages. The Index File Dump is listed (and numbered) according to physical record numbers and can also be used to identify these nodes with ease when required. 3.10. Link Diagram The Index File Dump described previously produces a list of nodes stating who they are currently routing data to. While this will normally reflect the network defaults, a manual change (override) to the routing specified by Kingdoms may mean the dump doesn't reflect what Kingdoms thinks is the network structure (as defined by the Coordinator) due to your manual modification. In contrast, the Link Diagram generates a picture of your complete network. It shows the Coordinator default links and does not take into account (or depict) any changes you may have made. In short, the Link Diagram is a complete picture of who connects to who in the Kingdoms network according to Coordinator specification. It can be particularly useful if you have made some manual modifications to your network and want to change something in particular back to what it should be without resetting everything automatically using the `Defaults' option on this menu. _____________________________________________________________ 16 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ A comparison between the Link Diagram and connections shown in the Index File Dump is a simple means of identifying areas where your node differs from the Defaults specified by the Coordinator. 3.11. Worms 3.11.1 What IS a Worm? One of the major problems I've found with other Inter-BBS games is the routing of game data. Too often things go astray or are not working properly, often due to a BBS that has it's routing defined incorrectly and is sending data off into a black hole somewhere. Unfortunately, though this is always a major issue in Inter-BBS games, facilities are rarely provided to verify the network setup from any node. The concept of the `Worm' is Kingdom's implementation of just such a facility. A Worm is named such because of it's function. When spawned from a node (any node can spawn a worm to any other node), a Worm will `crawl' through the network for anything up to ten days in an attempt to make it to it's destination. If it cannot reach the destination node in ten days, it will give up and return to the originating Realm. At each and every node it visits on it's way through the Kingdoms network it will, in addition to continuing on it's way to the destination, spawn a message back to the originator. When this message arrives back at the original node that spawned the worm, it will be added to the Worm report, `KWORM.RPT' on the local Realm. In this way, a complete report of the network links from one node to another will ultimately be generated, assuming the link is working as it should. In addition to spawning these informational messages on the Worm's progress, node data will also be added to the Worm on it's travels. That is, it will `grow' as it moves from node to node, compiling data about the nodes it travels through as it goes. Again, when a worm returns to it's origin node, the data gathered will be appended to the Worm report. In normal circumstances then, Worm data returned to the originator will consist of one record for each node the Worm passed through in addition to the compiled information gathered as it moves through the network. If a worm gets to a certain point then messages from it cut off suddenly, there is a problem with the network at the point the messages stopped being spawned back. In such cases, you should notify your Coordinator of the problem (remember to include the Worm report!) so remedial action can be taken. At present, Worms aren't very intelligent. Certainly they provide valuable information about the network so that if you suspect _____________________________________________________________ 17 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ something is wrong with a node, you can spawn a worm to it (effectively `ping' it, in network vanacular) and verify the links between the suspect node and your own. I plan however, in future versions, to add functionality to : * Report on Worms that pass through the same node more than once in transit to its destination. * Report on network `loops' by notifying the local Sysops who are in the `loop'. * Verify Index file structures are consistent on nodes the Worm passes through compared to the originating node. Two points to note about Worms : 1. Use them judiciously. Particularly in a large network, Worm's can generate a lot of network traffic by the time they've done a round trip from origin to destination and back again. Use them, by all means, but do everyone a favour and keep the traffic down by only spawning a Worm when you think there might be a network problem. 2. When you first connect to a Kingdoms network, make sure you *are* connected properly. Spawn a Worm to your network coordinator node (the N>etwork V>erify option in KM tells you who your coordinator is) to make sure you have a link to the coordinator. If that link isn't working, you have a problem! 3.11.2. Spawning a Worm Spawning a Worm is a simple matter. Select the `Worm' option on the Network menu. A scrollable list of available nodes will pop up. Select the node you want to spawn a Worm to and confirm the selection. The only restriction here is that you cannot spawn a Worm to your own node, for what I hope are pretty obvious reasons! :-) The specific format of a returned Worm report is shown (and described) in section 4.9 below. 3.12. Other Routing This is another means of checking suspected problems in the network, or even just a facility to satisfy yourself that all is as it should be. In short, this option will return you complete routing information as defined on any `Other' BBS in your Kingdoms network. When selected, a scrollable window of available nodes will pop up and you can select which one you want to send the request to. When it comes back, the data will be added to your Routing Report, for viewing at your convenience. _____________________________________________________________ 18 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ The Routing data returned includes (nicely formatted, of course!) : * The Realm Name * The Realm Address * A complete list of that node's Index and associated Routing rules. * A full list of Aliases active on the selected node * The version of Kingdoms that the node is running The specific format of a returned Routing report is shown (and described) in section 4.9 below. 3.13. Reports 3.13.1. Overview This option allows you to view the Worm and Routing reports while in the Kingdoms Manager. If you prefer to do this straight from DOS (or other OS), it will be useful for you to know that reports are always named *.rpt for ease of finding/reference. KWORM.RPT and KROUTE.RPT are the Worm and Routing reports respectively. You must have the Report Editor path and filename set up correctly in F>ile E>dit Paths to use this option. See `3.1.9. Report Editor' for more information. 3.13.2. Worm Report Layout The Worm Report will tell you many things about the path and operation of your Kingdoms network. It is first worthwhile to note that whenever you propogate a Worm, it is given a four character ID so you can always tell which worm is which as it's quite possible to send out several at once. Thus, the first characters of a Worm report line will always be `Worm [nnnn] :', where nnnn is the Worm ID. Following is a description of all the lines of text and status information you can come across in a Worm report, and what it means to you. For the purposes of illustration, the worm-id is assumed to be 2468. Worm [2468] : *** Spawned yyyyddd-hh:mm:ss to BBS-Name This line is created when you first select a Worm for propogation. The ID is recorded and the date/timestamp of when you issued it. The name of the BBS to which you requested it go is also recorded. Worm [2468] : --- Passthrough Notification on zz:net/node at yyyyddd-hh:mm:ss This line is created by another node as a Worm passes through it on it's way to a destination. Eg, If BBS-1 sends a worm to BBS-3 and to get there the worm has to pass through BBS-2, then a _____________________________________________________________ 19 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ passthrough notification will be issued back to BBS-1, by BBS-2, as the worm is processed and forwarded on. When you get this, you'll find out a lot about your network. If BBS-1 gets a passthrough notification back from BBS-2, then you know the link to BBS-2 is working fine, both ways, that BBS-2 is running inbound and outbound processing correctly, and at what time of day the outbound processing is run on BBS-2. You know also that BBS-2 has forwarded it on, but you CANNOT be sure it got to the next place (BBS-3) until you get a similar message back from BBS- 3, or a message such as those that follow telling you the Worm has reached it's destination and it returning. If you DON'T get something back from BBS-3, then either BBS-2 didn't forward it properly, or BBS-3 didn't process it properly. As BBS-2 has returned your pssthrough notification, it's probably ok and the problem probably lies with BBS-3, but you can make sure of that by requesting a routing report from BBS-2, which will give you detail on what it sends where and should answer that question for you. 3.13.3. Routing Report Layout A routing report is not the same as a Worm, but is very informative in it's own right. A routing report will send a request to any node you wish, asking for detail of that node's routing. The complete routing rules for that node will be returned to the requestor (normally the Net Coordinator) for examination as desired. This is ONLY the information held for routing rules which, if specified incorectly, will cause mail problems in the network itself. Thus, anyone can check anyone else's routing. Indeed, you are encouraged to do so to minimise processing errors on the network, and thus problems and hassles in the game itself. Information considered private to a node (such as registration numbers and status, passwords, user names, etc) is NOT distributed and cannot be requested. Like the worm, a line is written to the routing report when it is first requested to keep track of the date such requests were made. It will read something like `Routing Request generated yyyyddd/hh:mm:ss to BBS-Name.'. Assuming the request gets there and makes it back, the information returned is pretty much the same as you can view of your own realm within the Kingdoms Manager Network options on Routing and Aliases. A sample returned routing report follows : ----------------------------------------------------------------- --------- Routing Report Created yyyyddd (dd-mm-yyyy at hh:mm:ss) ----------------------------------------------------------------- --------- Routing at BBS-Name - processed yyyyddd (dd-mm-yyyy at hh:mm:ss) BBS-Name is running Kingdoms vn.nn. addr1 BBS1 (Sysop1) Default Outbound addr2 BBS2 (Sysop 2) Route to addr1 addr3 BBS3 (Sysop 3) This Node _____________________________________________________________ 20 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ addr4 BBS4 (Sysop 4) Route to addr1 ----------------------------------------------------------------- --------- --- Alias Data --- Alias 1 : Not used. Alias 2 : Not used. Alias 3 : Convert addr5 to addr4 Alias remarks/last reference Alias 4 : .... Alias 10 : Not used. -------------------------------- End Routing Info --------------- --------- Given that you've set up your own, this should be pretty clear to you by now. Quite simply, all the information that affects routing on the node is returned to the requestor for examination. It is not, of course, possible for someone to change another BBS's routing rules, but by mail you can inform another Sysop of routing rule problems, should any exist and get them fixed so the network continues to operate smoothly. _____________________________________________________________ 21 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ Section 4 - Registration Should you decide to register Kingdoms, this is where you enter the registration number provided. You will be asked for your name plus the BBS name to match up with a registration code provided to you by the Author. Remember that all fields are case sensitive when entering this information! If you've already registered, this option will display your registration details. Registration information is available in the accompanying document, KREG.DOC (or the text version, KREG.TXT). If you're on the Net, you can register with a credit card online at http:www.magna.com.au/~davec/kingdom.htm. You can also pick up the latest version of Kingdoms there! Section 5 - Coordinator These options are available only to your Netowrk Coordinator and are fully described in KCOORD.DOC, the Coordinator's documentation, which accompies the Kingdoms distribution archive. _____________________________________________________________ 22 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ Appendix A : Mail Routing A.1 Overview If you're participating in a Kingdoms network, your routing rules are set up and maintained using the Manager, KM.EXE. In short, your rules tell Kingdoms where to send mail for what node in your net. This appendix goes into detail about routing, what it means, and how it works in Kingdoms. Generally you won't need to read it to run your game (Kingdoms will maintain it fully for you) but the information is provided here for those who would like to know more about what's happening `behind the scenes'. When KNETOUT runs, it will examine the routing rules which are stored in the Index file, KIDX.DAT. For nodes which have outbound data, KNETOUT will generate a file attach .MSG in your Mailer directory (as defined in KCFG). The file attached to the message will be placed in your Kingdoms Outbound directory, again as specified in the Manager. Kingdoms does NOT create zillions of outbound files for the same node. It is smart enough to realise if an outbound exists for a node which is being sent more data and will simply append the new data to the existing file. This makes for a much faster and cleaner mail session during transfer and I'm sure those who have to pay STD rates to distribute Kingdoms data will appreciate the fact! It is VERY important you get your routing rules right or your players will find that attacks don't get through, money is lost they're sending to other Realms, or numerous other undesirable outcomes are possible. Kingdoms will define them for you based on the information available in the Index file so this isn't normally a problem but be aware of the need for caution if for some reason you have need to override the defaults chosen by Kingdoms itself! A.2. Defining your Routing - Standard Systems First up, make sure you have the latest KIDX.DAT file from your Kingdoms co-ordinator. Place it in C:\KINGDOMS and run the Manager. Selecting Network>Your Routing will put you in a screen where your routing rules are defined. This aspect of InterBBS games always seems to cause the most pain, which is why I chose not to use the normal text file _____________________________________________________________ 23 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ interface as I've seen (and seen go wrong in numerous ways!) in other BBS games, but rather built this area to allow you to easily manage your routing rules. You will have a screen before you which lists all the nodes in your `nodelist', your Kingdom Index (KIDX.DAT) file. If this is the first time you've used this option, you'll be asked to define which node YOU are in the nodelist. Using the arrow keys, place the highlight bar over your node and press enter. If your node is NOT listed, then press Esc to get out of there and get an updated KIDX.DAT file from your Coordinator that has you listed. Do NOT set yourself up as another node as mail routing for the game will get very confused to find multiple nodes with the same address on the network! Having selected your node, Kingdoms will configure your routing for you and there'll not normally be anything further you need to do other than perhaps set your outbound(s) to CRASH mail rather than normal mail should you wish it and turn on any compression you want. When this is done, re-enter `Your Routing' and have a look at what Kingdoms has done for you. Please note that the remaining discussion assumes Kindoms has created your routing and for some reason you wish to change it. A full description is provided so you can be sure you know what you're doing but do NOT assume you ever need to do any of this! In normal situations, Kingdoms will handle the whole thing for you and you should NEVER modify your routing definitions without first consulting your coordinator. Not only do you risk disrupting mail for your node if you get it wrong, but nodes who pick up from you and poll your node for network self correction will also feel the effects of a mistake and will have their routing broken in turn! In short, Kingdoms handles it all seamlessley ... if it ain't broke, don't try to fix it! The information you see when you enter Your Routing might look like : Address Name/Sysop Node Routing 3:712/523 The Web (Dave Chapman) This Node 3:712/807 Bad Company (Shane Hunter) Default Outbound (Direct) 69:1171/3 Way Out West (Darren Gibbs) Route 3:712/807 98:765/4321 Another BBS (Sysop Name) Route 3:712/807 This simple example, I hope, is apparent. We have : * The Web is the node on which Kingdoms is being set up. _____________________________________________________________ 24 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ * Bad Company is the BBS to which The Web sends its Kingdoms data. * Way out West's and Another BBS's Kingdoms' data is being routed to Bad Company. * Bad Company will have its routing set up to move data for these two on to wherever they are. Lastly, note that there is a (Direct) listed after Bad Company. This means that mail generated for it will be sent whenever The Web is connected to Bad Company - it matters not who made the originating call. If Bad Company was ringing the Web, then the mail for Bad Company can be placed on Hold to await an incoming call to the Web. Placing the highlight bar on the node you want to change and press F2 to toggle between Direct and Hold status for outbound mail depending on whether you call the node, or the node calls you, respectively. Generally, you can leave everything as Direct, so mail will transfer at all times, unless you have a specific reason for wanting to Hold mail for pickup only. For outbound nodes as well, you can set the `CRASH' flag on and off by pressing F3 while the node is highlighted. If it is on (Y), then file-attach messages created for your mailer will have the CRASH and IMMEDIATE flags set on accordingly. Having set this up, you often won't need to do any more. Kingdoms supports automated update of all Realm Index files so your Coordinator will distribute new nodes and they'll be added to your index file as they arrive without you having to lift a finger. Any new nodes that arrive for addition to your index file will automatically be routed to your Default Outbound so you don't need to worry about the routing of new nodes either. Kingdoms does it all for you! Should you ever want to change your Default Outbound, then just go back into the routing definitions and press Enter on the node you want to make your Default from that point on. You will be asked what you want to do with this node so select the option that defines it the Default Outbound. Kingdoms will prompt you to see if you want to change all other nodes to direct mail through this node and if you do, just hit Yes. Everything will be directed through a new node with just those few keystrokes, nothing more to it. Again, note that the Default Outbound MUST be your direct uplink on a path to the Coordinator node. You can see which node Kingdoms thinks that should be (and it's probably right!) by looking at the `uplink' node for your node on the Link Diagram. If you change it to some other node YOU MUST DISABLE SELF CORRECTION by setting it to zero or you risk the self correction process picking up old network data and incorrectly assigning routing definitions for your node. A.3. Defining your Routing - Intermediate Hubs _____________________________________________________________ 25 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ The above discussion should cover the requirements of most Kingdoms nodes and is very easy to implement. In the example however, The Web is calling only one node and sending all data to that node. If you are an intermediate hub (a BBS where more than one other BBS is picking up or delivering Kingdoms data) things are a little different, though Kingdoms still keeps it quite easy to do with a minimum of fuss. Again, Kingdoms (since version 2.10) does all this automatically and you shouln't need to change it. The following description is here only for those who have some need, and their Coordinator's approval, to do so! After routing configuration has completed, a hub might see a Routing screen such as : Address Name/Sysop Node Routing 3:712/523 The Web (Dave Chapman) Route 3:712/807 3:712/807 Bad Company (Shane Hunter) Default Outbound 69:1171/3 Way Out West (Darren Gibbs) Route 3:712/807 3:712/611 Sci-Fi BBS (Greg Hope) This Node 98:765/4321 Another BBS (Sysop Name) Route 3:712/807 Let's assume now that `Another BBS' is calling us (Sci-Fi BBS) for Kingdoms, not picking it up from Bad Company as is most likely the case above. Simply put the highlight bar on `Another BBS', and press Enter. You'll be given the following options : 1. Make this node the Default Outbound 2. Make this node a normal Outbound 3. Route mail for this node to another node 4. Forget it, no changes Simply select `2' and press enter and the routine list screen will be returned to you. Address Name/Sysop Node Routing 3:712/523 The Web (Dave Chapman) Route 3:712/807 3:712/807 Bad Company (Shane Hunter) Default Outbound 69:1171/3 Way Out West (Darren Gibbs) Route 3:712/807 3:712/611 Sci-Fi BBS (Greg Hope) This Node 98:765/4321 Another BBS (Sysop Name) Normal Outbound Simple, huh? Now mail for Another BBS will be held on Sci-Fi BBS until Another BBS calls in for it. As with the Default Outbound, _____________________________________________________________ 26 KINGDOMS v2.18 Kingdoms Manager Documentation ______________________________________________________________ you can press F2 while the node is highlighted to change their mail status from Hold to Direct. Something a little more complex. Assume `Way Out West' calls `Another BBS' for Kingdoms, rather than Bad Company. You want mail for Way Out West to go then to Another BBS rather than being routed to Bad Company. Again, highlight the node you want to change, Way Out West in this case, and press Enter. Choose `3' this time and a list of available nodes will pop up in another window. Kingdoms will ask you to select the node you wish to route data for Way Out West to, so highlight Another BBS and press Enter. The following screen will be returned : Address Name/Sysop Node Routing 3:712/523 The Web (Dave Chapman) Route 3:712/807 3:712/807 Bad Company (Shane Hunter) Default Outbound 69:1171/3 Way Out West (Darren Gibbs) Route 98:765/4321 3:712/611 Sci-Fi BBS (Greg Hope) This Node 98:765/4321 Another BBS (Sysop Name) Normal Outbound A couple of restrictions exist, which are there to protect you from yourself . 1. You cannot route data to your own node. 2. You cannot route data to a node that is not an outbound node. 3. You cannot change the status of the Default Outbound node except for the mail Hold/Direct flag. You must make another node the default outbound before you can modify it. That about covers mail routing. It should be pretty clear I hope! If you have any questions or problems, please don't hesitate to contact me netmail, on the Internet or via the Kingdoms Sysop echo on BattleNet. * End of Manager Documentation * _____________________________________________________________ 27