running.doc
1 /************************************************************************** 2 * Copyright (C) 1993 - see 'license.doc' for complete information. * 3 **************************************************************************/ 4 5 ----- Compiling, Running, and Maintaining CircleMUD ----- 6 7 8 This manual is meant to be read by implementors just getting started with 9 CircleMUD. This should be the first document you should read after reading 10 the main README file. 11 12 It should be the first documentation you read (after the 13 README file in theIt describes how to get the MUD compiled, configured, and 14 running; use of command-line options and system logs; and required daily 15 maintenance. 16 17 This i 18 19 Table of Contents 20 --------------------------------------------------------------------------- 21 22 1. Compiling Circle 23 1.1. Compatibility Issues 24 1.2. How-To 25 2. Configuring Circle 26 3. Running Circle 27 3.1. Execution and 'autorun' 28 3.2. Command-Line Options 29 4. System Logs 30 4.1. Player Information 31 4.2. Usage Information 32 4.3. Errors 33 34 35 1. Compiling Circle 36 ------------------- 37 38 1.1. Compatibility Issues 39 40 Ultrix 4.0 was used as CircleMUD's development platform up through v2.00; 41 starting with 2.10, Linux 0.99.11 was used instead. If you have Ultrix, 42 Linux, or another BSD-compatible system, and the gcc compiler, you should 43 be able to compile right out of the electronix box. If you don't have gcc, 44 try using cc -- on some systems such as AIX, the cc compiler is ANSI 45 compliant. 46 47 The author has personally compiled CircleMUD under the following systems: 48 49 Ultrix 4.0 50 IRIX 4.0.1, 4.0.4, 4.0.5 51 SunOS 4.1.1, 4.1.3 52 AIX 3.2 53 Linux 0.99.11 54 ConvexOS V10.2 55 56 Others have reported successfully compiling Circle under many other 57 systems; if you have a BSD-compatible system, chances of getting Circle 58 to compile easily are pretty good. Non-BSD systems will probably have 59 trouble with certain functions; getting Circle to compile for the first time 60 on such systems may be difficult and time-consuming. SVR4 compatibility is 61 on the horizon; many functions have already been converted to be SVR4 62 compatible, but the code has not yet been fully ported. 63 64 The Makefile has options to compile the MUD under Linux, AIX, and IRIX. 65 It also has an option for SVR4 but, as mentioned above, it does not 66 yet completely work. The unmodified Makefile should work with many other 67 including those listed above. 68 69 If you port Circle to another operating system and wish to share your work 70 with others, feel free to mail me your changes so that they can be included 71 in future releases of CircleMUD (if any). You'll be given credit, of 72 course. :) 73 74 75 1.2. How-To 76 77 The /src directory contains the source code for the main MUD; /src/utils 78 has the source for a dozen or so MUD maintenance utilities. The makefile 79 is in the /src directory; type 'make' while in that directory to compile 80 only the Circle server, type 'make utils' to compile all the utilities, or 81 type 'make all' to compile everything. You can also make an individual 82 utility by typing 'make x', where x is the name of the utility you want to 83 compile. Complete documentation of the utility programs can be found in 84 utils.doc. 85 86 The Makefile directs all compiled programs to the /bin directory. Although 87 not necessary, you may want to put Circle's /bin directory in your $PATH. 88 89 90 91 92 2. Configuring Circle 93 --------------------- 94 95 Your first instinct will probably be to put the game up as fast as possible 96 to see if it works. That's fine, but there are some files you should be 97 aware of before you put the game up 'for real'. This is just a partial 98 list -- see 'files.doc' for a complete description of all the files in the 99 Circle distribution. 100 101 First, you'll probably want to take a look at 'config.c' -- it has dozens 102 of variables you can set to configure various aspects of CircleMUD. 103 104 The place where most of your day-to-day changes will be is in the lib/text 105 directory; that's where the help files, MOTD (Message Of The Day), imotd 106 (MOTD for immortals), and other text files are all kept. 107 108 In particular, you should make sure to put something in your 'policy' file -- 109 it's better to have definite rules from the beginning than to have problems 110 later on when people try to bend you as far as they can. Also, you should 111 put tips for new immortals in the 'handbook' file (i.e., "Don't help any 112 mortals", "Don't kill mobiles", "Don't run through puddles", "Don't bring 113 glassware into the pool area", etc.) 114 115 The area hierarchy is lib/world. lib/world has 5 subdirectories -- wld, 116 mob, obj, shp, and zon, which is where the world, mobile, object, shop, 117 and zone files go, respectively. Each directory has a set of world 118 files in it with the correct extension (i.e., the obj subdir will have 119 a bunch of files ending with ".obj", such as 30.obj, 31.obj, etc.) plus 120 two special files -- 'index' and 'index.mini'. You can control which files 121 are loaded by Circle simply by changing the list of files listed in 'index'. 122 'index.mini' controls which (smaller) set of world files should be loaded 123 in the debugging mode (Mini-Mud Mode, explained below.) 124 125 126 127 128 3. Running Circle 129 ----------------- 130 131 3.1. Execution and 'autorun' 132 133 Circle should always be run from circle's "root" directory, not the /bin 134 directory. You can run it manually by typing 'bin/circle' (useful for 135 testing and debugging). For running the game "for real", it's better 136 to use the 'autorun' shell script provided in Circle's root directory. 137 138 Autorun lets Circle run itself for long periods of time. It continuously 139 runs the game as well as removing old system logs, moving newer system logs 140 to the /log directory, and saving certain log entries to permanent files. 141 142 Autorun can be controlled by creating files with certain names. You can 143 use the 'touch' command to create a file, and, of course, the 'rm' command 144 to remove a file. If a file called '.fastboot' exists, the Circle will reboot 145 immediately if it crashes or is shut down instead of waiting 40 seconds as 146 it normally does. A file called '.killscript' will cause the script to 147 terminate itself; i.e., if you want to bring the game down. If you want 148 to temporarily prevent the MUD from rebooting, create a file called 'pause'; 149 the script will go into a wait loop until 'pause' is removed. 150 151 Although you can create these files manually, the SHUTDOWN command from 152 within the MUD has several command-line options which will create these 153 files for you. See the SHUTDOWN help entry in wizhelp.doc for more 154 information. 155 156 It's not uncommon for CircleMUD to run for a week without crashing. The 157 game can be rebooted manually with the SHUTDOWN command, or automatically. 158 Once a day, at a time specified by the REBOOT_AT macro in modify.c, the 159 game checks for the existence of the file "reboot" in the selected data 160 directory. If the file exists, the game is rebooted (it terminates nicely, 161 with a nonzero return value). If the size of the file is nonzero, its contents 162 are processed by "sh" (with a system() call). If the processing returns 163 with a nonzero status, the file is renamed to "reboot.FAILED", and the 164 rebooting is called off. If it returns zero, the file is moved to 165 "reboot.SUCCEEDED", and the game is rebooted. 166 167 The first character to log in to the MUD (i.e., when the playerfile is 168 empty) will be made the maximum level. You should fix your stats using 169 the RESTORE command when you first create the character. To make more 170 God characters, use the ADVANCE command. 171 172 173 3.2. Command-Line Options 174 175 There are a number of command-line options which Circle will recognize. 176 You can use these when running Circle manually, or put them in the FLAGS 177 variable in your autorun script to use them all the time. 178 179 180 The syntax is: 181 182 circle [-m] [-q] [-r] [-s] [-d <path>] [<port #>] 183 184 -m: "Mini-Mud Mode". Mini-mud will be one of your most powerful debugging 185 tools; it causes Circle to boot with an abridged world, cutting the 186 boot time down to several seconds. It is useful for testing features 187 which are not world-related (i.e, new commands or spells). 188 189 CircleMUD uses split world files (in the lib/world heirarchy); each 190 directory (i.e., wld, obj, mob, shp, and zon) has a file called 'index' 191 which specifies which files should be loaded at boot-time. The file 192 'index.mini' specifies which parts of the world should be loaded with 193 the -m option. 194 195 -q: Quick boot - prevents checking of timed out object files. Every time 196 Circle boots, it checks every object file to see if it has timed out; 197 if so, it is deleted. This is done primarily to save disk space. If 198 time is more important to you than space, use the -q option. -q is 199 automatically activated when you use -m. 200 201 -r: Restrict game to new players. Allows you to decide at run-time whether 202 the game is open to new players or not; -r is equivalent to typing 203 "wizlock 1" (see wizhelp.doc for more information). 204 205 -s: Disable special routines. This option prevents special procedures from 206 being assigned. It is still supported but obsolete because Circle checks 207 to make sure each mob exists before assigning a spec_proc to it. 208 209 -d: Select data directory. This is useful if you want to keep one or more 210 sets of game data in addition to the standard set. For example, you may 211 wish to make a copy of the entire world in a separate directory, so that 212 you can test additions to the code or worldfile without subjecting the 213 players to unnecessary hazards. The default data directory is 'lib'. 214 Any coredumps (may they never happen to you!) will take place in the 215 selected directory. 216 217 port : Select the port on which the game is to wait for connections. 218 Default port is 4000; you can change the default in config.c and 219 the PORT= line of the autorun script. 220 221 222 223 224 4. System Logs 225 -------------- 226 227 CircleMUD writes a wide variety of information to its log file (called 228 "syslog"). During Circle's boot sequence, the syslog keeps a record of 229 everything the MUD is doing to initialize itself; this can be useful to 230 determine what the problem is if the MUD dies while it is booting. Once 231 the game is up and running, the syslog contains information about players 232 (i.e., when they connect, disconnect, rent, unrent, quit, die, hit death 233 traps, etc.) as well as status information about the game itself. The 234 game-related information falls generally into 2 categories: usage 235 information and errors. 236 237 238 4.1. Player Information 239 240 The player information recorded by Circle's system logs will serve you 241 very well as your players start to make wild claims about strange bugs 242 resulting in them losing equipment or points. Many mudders prey on the 243 insecurities of a new mud administrator who is terrified that his or her 244 MUD is riddled with bugs and will do anything to satisfy grumpy players -- 245 don't let yourself fall into that trap! CircleMUD is bound to contain 246 bugs, but most of the core systems have been well tested, so you should 247 take claims such as "I magically lost all my stuff!" with a grain of salt 248 and check your system logs. 249 250 If a player ever asks you for reimbursement of equipment, money, gold, 251 experience points, or whatever, your gut reaction should always be to 252 check the logs first. 253 254 As a sidebar, let me point out that the value of system logs is twofold: 255 1) they actually provide you with valuable information, and 2) they make 256 your players paranoid. When I first started mudding and I heard about 257 this mysterious "system log", it made me incredibly paranoid. Now that 258 I've done a good deal of MUD administration, I've seen the same paranoia 259 in _many_ other players. 260 261 That paranoia is a very good thing. The system logs become an abstract 262 and shapeless but omnipresent force on the MUD. Players hear about "the 263 System Log" and then get paranoid that everything they do is being 264 recorded, so they tend to behave, lest the evil System Log betray their 265 wrongdoings to the Gods. 266 267 For this reason, when you go to check your logs, it's a good idea to 268 say something like "Hold on -- let me go check the system logs, OK?" 269 because it reinforces the syslog's presence in the collective psyche 270 of your players. 271 272 Back to the point. When someone claims that they've been wronged by the 273 evil system, always check the logs. The logs give you power to say things 274 like "What do you mean your items disappeared in rent -- it says right here 275 in the logs 'Rasmussen has quit the game.' -- you didn't rent at all, you 276 just QUIT!" 277 278 The logs also record when a player's items are dumped due to insufficient 279 funds (remember -- rent is calculated per day on a PER-SECOND basis! If you 280 rent at the rate of 100 coins per day and come back 36 hours later, you'll 281 be charged 150 coins!). Plus, when someone rents, it records in the logs how 282 much rent cost per day and how much the player had, to diffuse disputes such 283 as "But I had enough money!!" 284 285 In short: the system logs are your friends. Love them. 286 287 The autorun script saves 6 levels of raw system logs. In addition, it 288 greps the logs for certain pieces of extra-juicy information to save 289 indefinitely. 290 291 292 4.2. Usage Information 293 294 Every 5 minutes, the game counts how many people are playing and records 295 that information in the system log. Optionally, if you #define RUSAGE 296 in comm.c, it will also record system resource information such as CPU time 297 and memory used. The usage information currently logged by Circle is, 298 as you can see, somewhat sparse; local MUD admins are encouraged to add 299 to this code as is appropriate for their particular site. 300 301 Usage information isn't critical, but it is interesting to look at the 302 usage patterns to determine when your peak playing hours are. If you're 303 good at using 'cut' and other Unix utilities, you can even dazzle your 304 friends by graphing your MUD's system usage. 305 306 [ Note: friends not included with the CircleMUD distribution. ] 307 308 309 4.3. Errors 310 311 Just as your first gut instinct should be to look at the logs if a player 312 starts begging you for something, your first gut instinct in the event of 313 a crash or unexpected shutdown should also be to look at the system logs. 314 315 A Unix utility called 'tail' is used to look at the last few lines of a 316 text file; it's very useful for looking at the last entries in the system 317 log to see the last thing that happened before the shutdown. Often, Circle 318 will report an error in the logs just before it crashes. This method is 319 particularly useful if the MUD crashes during its boot sequence, because 320 the logging during boot is intensive. 321 322 If Circle shuts down unexpectedly and there is no core dump in the /lib 323 directory, the game probably detected an internal error and killed itself. 324 Such shutdowns are always preceeded by entries in the system log describing 325 the error. 326 327 If there's no error message at the end of the log, then there probably 328 IS a core dump, so you can use 'dbx', 'gdb', etc. to examine the core 329 dump and determine the reason for the crash. The file 'hacker.doc', 330 generously provided by Furey of MERC Industries, offers useful insight 331 into the art and science of debugging -- you'd be well advised to give it 332 a look-see. 333 334 Circle sometimes encouters a serious but non-fatal error; in this case, 335 the error will be written to the system log with the prefix SYSERR, but 336 the MUD will not shut itself down. You should always be aware of any 337 SYSERRs which occur -- they are often useful for forseeing imminent danger 338 or averting problems before they become critical. If a SYSERR does 339 occur, try to determine if a change you've made recently has caused it. 340 Ignoring SYSERRs is like ignoring compiler warnings: you can be tempted 341 to ignore them because the game keeps going even if they exist, but you 342 can easily get yourself into trouble by not listening. The autorun script 343 saves all SYSERRs to the file log/errors. 344 345 346 347 348 349 Day-To-Day MUD Administration 350 ----------------------------- 351 Okay, so now you have your wonderful CircleMUD up and running and all is 352 right with the world. Right? 353 354 Well, technically, yes. Circle requires very little day-to-day attention 355 in order to keep the progam itself running smoothly. But the MUD itself 356 is just a series of instructions running on a computer, processing data. 357 Never lose sight of the fact that there will be dozens, hundreds, or maybe 358 even thousands of people connecting to your MUD -- and they are NOT 359 programs. They're people! 360 361 What I'm getting at is this: from the technical side, there are relatively 362 few things you have to do to keep the game running. But you can't just plop 363 a MUD on the Internet and then ignore it! Spend time on your MUD. Try to 364 keep up with the boards, and make an effort to respond to the complaints, 365 ideas, and suggestions posted there. Take a look at the 'bug', 'typo', and 366 'idea' files from time to time -- and maybe even respond to some of the ideas 367 using Mudmail. Try to respond to Mudmail you receive from players in a 368 timely manner. Make sure that your 'news', 'policy' and other text files 369 are up-to-date and suit the political climate on your MUD. 370 371 If you can't or just don't want to deal with the player politics, make sure 372 sure that you choose someone who can and will, and make them responsible for 373 dealing with it. If no one does it, your MUD will stagnate and die. 374 375 376 377 Maintaining CircleMUD 378 --------------------- 379 380 CircleMUD requires little technical maintenance. You should look at the 381 log/errors file regularly to make sure there are no recurring problems. 382 Also, you probably will want to 'purge' the playerfile on a regular basis 383 (i.e., remove "deadweight" characters). You can decide how often to purge 384 the playerfile -- every day if disk space is tight, or every month if it 385 isn't. The purgeplay utility program (included) removes deadweight players. 386 387 You should run the 'purgeobjs' script (in the lib/plrobjs) directory after 388 you purge the playerfile -- it removes the object files of players who no 389 longer exist in the playerfile. 390 391 The 'automaint' script in the main circle directory will automatically purge 392 the playerfile and player objects for you. DO NOT RUN THIS SCRIPT WHILE 393 THE MUD IS RUNNING! Doing so will make your life (more) difficult. 394 395 396 397 Good luck with your MUD! 398 399 400 401 -- Jeremy Elson 402 jelson@cs.jhu.edu