/************************************************************************** * Copyright (C) 1993 - see 'license.doc' for complete information. * **************************************************************************/ ----- Compiling, Running, and Maintaining CircleMUD ----- This manual is meant to be read by implementors just getting started with CircleMUD. This should be the first document you should read after reading the main README file. It should be the first documentation you read (after the README file in theIt describes how to get the MUD compiled, configured, and running; use of command-line options and system logs; and required daily maintenance. This i Table of Contents --------------------------------------------------------------------------- 1. Compiling Circle 1.1. Compatibility Issues 1.2. How-To 2. Configuring Circle 3. Running Circle 3.1. Execution and 'autorun' 3.2. Command-Line Options 4. System Logs 4.1. Player Information 4.2. Usage Information 4.3. Errors 1. Compiling Circle ------------------- 1.1. Compatibility Issues Ultrix 4.0 was used as CircleMUD's development platform up through v2.00; starting with 2.10, Linux 0.99.11 was used instead. If you have Ultrix, Linux, or another BSD-compatible system, and the gcc compiler, you should be able to compile right out of the electronix box. If you don't have gcc, try using cc -- on some systems such as AIX, the cc compiler is ANSI compliant. The author has personally compiled CircleMUD under the following systems: Ultrix 4.0 IRIX 4.0.1, 4.0.4, 4.0.5 SunOS 4.1.1, 4.1.3 AIX 3.2 Linux 0.99.11 ConvexOS V10.2 Others have reported successfully compiling Circle under many other systems; if you have a BSD-compatible system, chances of getting Circle to compile easily are pretty good. Non-BSD systems will probably have trouble with certain functions; getting Circle to compile for the first time on such systems may be difficult and time-consuming. SVR4 compatibility is on the horizon; many functions have already been converted to be SVR4 compatible, but the code has not yet been fully ported. The Makefile has options to compile the MUD under Linux, AIX, and IRIX. It also has an option for SVR4 but, as mentioned above, it does not yet completely work. The unmodified Makefile should work with many other including those listed above. If you port Circle to another operating system and wish to share your work with others, feel free to mail me your changes so that they can be included in future releases of CircleMUD (if any). You'll be given credit, of course. :) 1.2. How-To The /src directory contains the source code for the main MUD; /src/utils has the source for a dozen or so MUD maintenance utilities. The makefile is in the /src directory; type 'make' while in that directory to compile only the Circle server, type 'make utils' to compile all the utilities, or type 'make all' to compile everything. You can also make an individual utility by typing 'make x', where x is the name of the utility you want to compile. Complete documentation of the utility programs can be found in utils.doc. The Makefile directs all compiled programs to the /bin directory. Although not necessary, you may want to put Circle's /bin directory in your $PATH. 2. Configuring Circle --------------------- Your first instinct will probably be to put the game up as fast as possible to see if it works. That's fine, but there are some files you should be aware of before you put the game up 'for real'. This is just a partial list -- see 'files.doc' for a complete description of all the files in the Circle distribution. First, you'll probably want to take a look at 'config.c' -- it has dozens of variables you can set to configure various aspects of CircleMUD. The place where most of your day-to-day changes will be is in the lib/text directory; that's where the help files, MOTD (Message Of The Day), imotd (MOTD for immortals), and other text files are all kept. In particular, you should make sure to put something in your 'policy' file -- it's better to have definite rules from the beginning than to have problems later on when people try to bend you as far as they can. Also, you should put tips for new immortals in the 'handbook' file (i.e., "Don't help any mortals", "Don't kill mobiles", "Don't run through puddles", "Don't bring glassware into the pool area", etc.) The area hierarchy is lib/world. lib/world has 5 subdirectories -- wld, mob, obj, shp, and zon, which is where the world, mobile, object, shop, and zone files go, respectively. Each directory has a set of world files in it with the correct extension (i.e., the obj subdir will have a bunch of files ending with ".obj", such as 30.obj, 31.obj, etc.) plus two special files -- 'index' and 'index.mini'. You can control which files are loaded by Circle simply by changing the list of files listed in 'index'. 'index.mini' controls which (smaller) set of world files should be loaded in the debugging mode (Mini-Mud Mode, explained below.) 3. Running Circle ----------------- 3.1. Execution and 'autorun' Circle should always be run from circle's "root" directory, not the /bin directory. You can run it manually by typing 'bin/circle' (useful for testing and debugging). For running the game "for real", it's better to use the 'autorun' shell script provided in Circle's root directory. Autorun lets Circle run itself for long periods of time. It continuously runs the game as well as removing old system logs, moving newer system logs to the /log directory, and saving certain log entries to permanent files. Autorun can be controlled by creating files with certain names. You can use the 'touch' command to create a file, and, of course, the 'rm' command to remove a file. If a file called '.fastboot' exists, the Circle will reboot immediately if it crashes or is shut down instead of waiting 40 seconds as it normally does. A file called '.killscript' will cause the script to terminate itself; i.e., if you want to bring the game down. If you want to temporarily prevent the MUD from rebooting, create a file called 'pause'; the script will go into a wait loop until 'pause' is removed. Although you can create these files manually, the SHUTDOWN command from within the MUD has several command-line options which will create these files for you. See the SHUTDOWN help entry in wizhelp.doc for more information. It's not uncommon for CircleMUD to run for a week without crashing. The game can be rebooted manually with the SHUTDOWN command, or automatically. Once a day, at a time specified by the REBOOT_AT macro in modify.c, the game checks for the existence of the file "reboot" in the selected data directory. If the file exists, the game is rebooted (it terminates nicely, with a nonzero return value). If the size of the file is nonzero, its contents are processed by "sh" (with a system() call). If the processing returns with a nonzero status, the file is renamed to "reboot.FAILED", and the rebooting is called off. If it returns zero, the file is moved to "reboot.SUCCEEDED", and the game is rebooted. The first character to log in to the MUD (i.e., when the playerfile is empty) will be made the maximum level. You should fix your stats using the RESTORE command when you first create the character. To make more God characters, use the ADVANCE command. 3.2. Command-Line Options There are a number of command-line options which Circle will recognize. You can use these when running Circle manually, or put them in the FLAGS variable in your autorun script to use them all the time. The syntax is: circle [-m] [-q] [-r] [-s] [-d ] [] -m: "Mini-Mud Mode". Mini-mud will be one of your most powerful debugging tools; it causes Circle to boot with an abridged world, cutting the boot time down to several seconds. It is useful for testing features which are not world-related (i.e, new commands or spells). CircleMUD uses split world files (in the lib/world heirarchy); each directory (i.e., wld, obj, mob, shp, and zon) has a file called 'index' which specifies which files should be loaded at boot-time. The file 'index.mini' specifies which parts of the world should be loaded with the -m option. -q: Quick boot - prevents checking of timed out object files. Every time Circle boots, it checks every object file to see if it has timed out; if so, it is deleted. This is done primarily to save disk space. If time is more important to you than space, use the -q option. -q is automatically activated when you use -m. -r: Restrict game to new players. Allows you to decide at run-time whether the game is open to new players or not; -r is equivalent to typing "wizlock 1" (see wizhelp.doc for more information). -s: Disable special routines. This option prevents special procedures from being assigned. It is still supported but obsolete because Circle checks to make sure each mob exists before assigning a spec_proc to it. -d: Select data directory. This is useful if you want to keep one or more sets of game data in addition to the standard set. For example, you may wish to make a copy of the entire world in a separate directory, so that you can test additions to the code or worldfile without subjecting the players to unnecessary hazards. The default data directory is 'lib'. Any coredumps (may they never happen to you!) will take place in the selected directory. port : Select the port on which the game is to wait for connections. Default port is 4000; you can change the default in config.c and the PORT= line of the autorun script. 4. System Logs -------------- CircleMUD writes a wide variety of information to its log file (called "syslog"). During Circle's boot sequence, the syslog keeps a record of everything the MUD is doing to initialize itself; this can be useful to determine what the problem is if the MUD dies while it is booting. Once the game is up and running, the syslog contains information about players (i.e., when they connect, disconnect, rent, unrent, quit, die, hit death traps, etc.) as well as status information about the game itself. The game-related information falls generally into 2 categories: usage information and errors. 4.1. Player Information The player information recorded by Circle's system logs will serve you very well as your players start to make wild claims about strange bugs resulting in them losing equipment or points. Many mudders prey on the insecurities of a new mud administrator who is terrified that his or her MUD is riddled with bugs and will do anything to satisfy grumpy players -- don't let yourself fall into that trap! CircleMUD is bound to contain bugs, but most of the core systems have been well tested, so you should take claims such as "I magically lost all my stuff!" with a grain of salt and check your system logs. If a player ever asks you for reimbursement of equipment, money, gold, experience points, or whatever, your gut reaction should always be to check the logs first. As a sidebar, let me point out that the value of system logs is twofold: 1) they actually provide you with valuable information, and 2) they make your players paranoid. When I first started mudding and I heard about this mysterious "system log", it made me incredibly paranoid. Now that I've done a good deal of MUD administration, I've seen the same paranoia in _many_ other players. That paranoia is a very good thing. The system logs become an abstract and shapeless but omnipresent force on the MUD. Players hear about "the System Log" and then get paranoid that everything they do is being recorded, so they tend to behave, lest the evil System Log betray their wrongdoings to the Gods. For this reason, when you go to check your logs, it's a good idea to say something like "Hold on -- let me go check the system logs, OK?" because it reinforces the syslog's presence in the collective psyche of your players. Back to the point. When someone claims that they've been wronged by the evil system, always check the logs. The logs give you power to say things like "What do you mean your items disappeared in rent -- it says right here in the logs 'Rasmussen has quit the game.' -- you didn't rent at all, you just QUIT!" The logs also record when a player's items are dumped due to insufficient funds (remember -- rent is calculated per day on a PER-SECOND basis! If you rent at the rate of 100 coins per day and come back 36 hours later, you'll be charged 150 coins!). Plus, when someone rents, it records in the logs how much rent cost per day and how much the player had, to diffuse disputes such as "But I had enough money!!" In short: the system logs are your friends. Love them. The autorun script saves 6 levels of raw system logs. In addition, it greps the logs for certain pieces of extra-juicy information to save indefinitely. 4.2. Usage Information Every 5 minutes, the game counts how many people are playing and records that information in the system log. Optionally, if you #define RUSAGE in comm.c, it will also record system resource information such as CPU time and memory used. The usage information currently logged by Circle is, as you can see, somewhat sparse; local MUD admins are encouraged to add to this code as is appropriate for their particular site. Usage information isn't critical, but it is interesting to look at the usage patterns to determine when your peak playing hours are. If you're good at using 'cut' and other Unix utilities, you can even dazzle your friends by graphing your MUD's system usage. [ Note: friends not included with the CircleMUD distribution. ] 4.3. Errors Just as your first gut instinct should be to look at the logs if a player starts begging you for something, your first gut instinct in the event of a crash or unexpected shutdown should also be to look at the system logs. A Unix utility called 'tail' is used to look at the last few lines of a text file; it's very useful for looking at the last entries in the system log to see the last thing that happened before the shutdown. Often, Circle will report an error in the logs just before it crashes. This method is particularly useful if the MUD crashes during its boot sequence, because the logging during boot is intensive. If Circle shuts down unexpectedly and there is no core dump in the /lib directory, the game probably detected an internal error and killed itself. Such shutdowns are always preceeded by entries in the system log describing the error. If there's no error message at the end of the log, then there probably IS a core dump, so you can use 'dbx', 'gdb', etc. to examine the core dump and determine the reason for the crash. The file 'hacker.doc', generously provided by Furey of MERC Industries, offers useful insight into the art and science of debugging -- you'd be well advised to give it a look-see. Circle sometimes encouters a serious but non-fatal error; in this case, the error will be written to the system log with the prefix SYSERR, but the MUD will not shut itself down. You should always be aware of any SYSERRs which occur -- they are often useful for forseeing imminent danger or averting problems before they become critical. If a SYSERR does occur, try to determine if a change you've made recently has caused it. Ignoring SYSERRs is like ignoring compiler warnings: you can be tempted to ignore them because the game keeps going even if they exist, but you can easily get yourself into trouble by not listening. The autorun script saves all SYSERRs to the file log/errors. Day-To-Day MUD Administration ----------------------------- Okay, so now you have your wonderful CircleMUD up and running and all is right with the world. Right? Well, technically, yes. Circle requires very little day-to-day attention in order to keep the progam itself running smoothly. But the MUD itself is just a series of instructions running on a computer, processing data. Never lose sight of the fact that there will be dozens, hundreds, or maybe even thousands of people connecting to your MUD -- and they are NOT programs. They're people! What I'm getting at is this: from the technical side, there are relatively few things you have to do to keep the game running. But you can't just plop a MUD on the Internet and then ignore it! Spend time on your MUD. Try to keep up with the boards, and make an effort to respond to the complaints, ideas, and suggestions posted there. Take a look at the 'bug', 'typo', and 'idea' files from time to time -- and maybe even respond to some of the ideas using Mudmail. Try to respond to Mudmail you receive from players in a timely manner. Make sure that your 'news', 'policy' and other text files are up-to-date and suit the political climate on your MUD. If you can't or just don't want to deal with the player politics, make sure sure that you choose someone who can and will, and make them responsible for dealing with it. If no one does it, your MUD will stagnate and die. Maintaining CircleMUD --------------------- CircleMUD requires little technical maintenance. You should look at the log/errors file regularly to make sure there are no recurring problems. Also, you probably will want to 'purge' the playerfile on a regular basis (i.e., remove "deadweight" characters). You can decide how often to purge the playerfile -- every day if disk space is tight, or every month if it isn't. The purgeplay utility program (included) removes deadweight players. You should run the 'purgeobjs' script (in the lib/plrobjs) directory after you purge the playerfile -- it removes the object files of players who no longer exist in the playerfile. The 'automaint' script in the main circle directory will automatically purge the playerfile and player objects for you. DO NOT RUN THIS SCRIPT WHILE THE MUD IS RUNNING! Doing so will make your life (more) difficult. Good luck with your MUD! -- Jeremy Elson jelson@cs.jhu.edu