============================================================================ User's Guide to PennMUSH 1.7.x ============================================================================ Some of this Guide was written by Amberyl, and is used with permission. Most of it is by Paul/Javelin. This most recent version has been updated by Alex/Talek and Javelin. I. Introduction II. Installation Guide (new users) III. Conversion Guide (previous users) IV. Binary Guide (pre-built binary users) V. Additional Options VI. Trouble-shooting VII. Getting Help, Reporting Bugs VIII. Getting a .pennmush.org hostname and mailing lists IX. Comments You may also want to take a look at Javelin's Guide for PennMUSH Gods, at http://pennmush.org/~alansz/guide.html or by ftp from pennmush.org, /pub/PennMUSH/Guide ============================================================================ I. Introduction PennMUSH is a TinyMUD derivative, and one of the branches along the MUSH line. "Vanilla" TinyMUSH, which added the "v" registers and functions to the basic TinyMUD building commands, was written by Larry Foard. The code was later expanded by Jin, of MicroMUSH. In January of 1991, MicroMUSH changed its name to MicroMUSE, and the code there continued to develop under the MUSE name. At that same point in time, Moonchilde took the last public release of that code and began a series of improvements and extensions. That code was released as PernMUSH, named for the MUSH that Moonchilde was running. The last released version of that code was version 1.15, at the end of November 1991. PernMUSH itself had switched over to TinyMUSH 2.0, which Moonchilde had co-written with Glenn Crocker (Wizard of TinyCWRU); there was no longer a reason for Moonchilde to maintain this code. In January of 1992, Amberyl began working on the PernMUSH 1.15 code release, for TinyKrynn. She took over the code, which no one was supporting, and is continuing to work on extending this code, as well as improving its compatibility with TinyMUSH 2.0. She changed the name to PennMUSH (named for her school, the University of Pennsylvania), to avoid the confusion that resulted from PernMUSH actually running TinyMUSH 2.0. In January of 1995, Amberyl passed on her mantle to Javelin (aka Paul@Dune, Alan Schwartz), who is now the maintainer of the primary public distribution in development. He released two patchlevels numbered "dune-1" and "dune-2" before releasing PennMUSH 1.50 pl11 and later distributions. The numbering scheme changed again with PennMUSH 1.6.0 (see CHANGES.OLD). Gradually during the early part of 1995, Alan formed the PennMUSH development team with T. Alexander Popiel (Talek) and Ralph Melton. The development process became more formalized, with official patches, a dedicated bug reporting email address, and better tracking of outstanding issues and history. In August of 1997, Ralph Melton left the PennMUSH development team, and Thorvald Natvig joined as a new member. Many thanks go to Ralph who contributed much time, code, and good cheer to PennMUSH. Javelin, in conjunction with Talek (T. Alexander Popiel) and Thorvald Natvig, are the current PennMUSH development team. A MUSH manual should be available at ftp.digex.net, ftp.math.okstate.edu, primerd.prime.com, or from wherever you got this code from. The manual should be numbered version 2.007 or higher. If you are planning on modifying the source code to PennMUSH, you'll probably want Javelin's Guide for PennMUSH Gods, which should be available where you got this code, or, in hypertext, as http://pennmush.org/~alansz/guide.html Enjoy! ============================================================================ II. Installation (new users) DISCLAIMER: Before attempting to run a MUD of any sort, you should have some reasonable knowledge of UNIX and C. If you do not, it is _strongly_ suggested that you learn UNIX and C to some reasonable level of competency before attempting to set up a MUSH. (Note that even people using the Windows and OS/2 ports are encouraged to know UNIX, because that's the paradigm that PennMUSH was built with, and most resources will be written with UNIX is mind.) Here's a quick picture of the organization of the MUSH directory tree. The "src" directory contains C source code. The "hdrs" directory contains header files for the source code. The files used by a running MUSH are in the "game" directory, which includes subdirectories "data" (current databases), "txt" (text files and directories for building them), "log" (log files), and "save" (backup databases). Finally, the "hints" directory is used during the installation process, and the "os2" directory contains files of using in building for OS/2. top-level-+-> src +-> hdrs +-> game ------+-> data | | | +-> txt -------+-> nws | | +-> evt | | \-> hlp | | | +-> log | \-> save +-> hints +-> os2 \-> utils The quickstart version of the installation is: 1. On win32 only, install proper tools. 2. sh Configure -d 3. create options.h, or make update 4. make install 5. possibly make customize 6. edit game/mush.cnf and game/restart Here's the process in detail: 1. If you're running on win32 (either 95 or NT, that is), install the cygwin32 unix emulation tools (available free from Cygnus at http://www.cygnus.com/misc/gnu-win32/). You'll want the entire Cygnus Developer's Kit (cdk), notably including 'make' and 'patch'. These are required for compiling PennMUSH. Make sure you set up your environment variables properly as discussed in the Kit's installation instructions. VERY IMPORTANT: The rest of the instructions assume that you have started up a bash shell and are running commands under that shell -- they won't work right if run directly from a DOS shell. VERY IMPORTANT: cygwin32's bin directory (usually something horrible like /gnuwin32/b18/h-i386-cygwin32/bin) must appear in your path *before* c:\windows\command does, so that 'sort' calls the good GNU sort, and not the bad Windows sort. Optionally, install Microsoft's Visual C++ compiler. If you want to use it, make sure 'cl' (the command line compiler) is in your PATH. 2. Type 'sh Configure' in the top directory. This script will ask you some questions and attempt to identify the proper Makefile settings for your system. The default answers are very likely to be correct, except that if you have gcc 2.0 or later, you should generally prefer to compile with that than with your system's cc compiler. If you don't want to answer the questions you can try "sh Configure -d" which simply accepts all the defaults. This works right on most systems, though you may prefer "sh Configure -d -D cc=gcc" to use gcc. Win32 has two different configuration sets: 'win32' and 'win32-gcc'. The former (which is default) uses Microsoft's compiler to produce a native executable. The latter (which uses gcc from the Cygnus tools) doesn't require Microsoft's compiler (and thus you don't have to pay for it), but the resulting executable will not run without Cygnus' tools on the system. You may select between these configuration sets when Configure asks which hints file to use. When switching between these configurations, make sure to delete 'config.sh' before running Configure. 3. EITHER: Then, copy options.h.dist to options.h. Note that these files stay in the top directory. Edit the file. It's liberally commented. Also, cp game/mushcnf.dst to game/mush.cnf. OR: Type 'make update', and answer all the questions about which MUSH options you want. You do not need to change any of the other header files. NOTE: If you decided to use shs password encryption (which is required for Win32 MUSHes), you will have to get shs.c and shs.h from export.pennmush.org (in Norway). These files go in the src and hdrs directories, respectively. If you decided to enable the encrypt() and decrypt() MUSHcode functions, you will want to get funcrypt.c from export.pennmush.org, as well, and place it in the src directory. 4. Do a "make install". This will build all the necessary files, and set up some symbolic links for the restart script. You will probably receive a few compilation warnings, which can generally be ignored. Under win32 using the Microsoft compiler, the make will abort when trying to build info_slave. This is all right; you don't need the info_slave. Under win32 using gcc, copy src/netmud.exe to game/netmush.exe, src/mkindx.exe to game/mkindx.exe, and src/info_slave.exe to game/info_slave.exe. Note the name change for netmud -> netmush. 5. If you plan to run multiple MUSHes, you may want to do a "make customize" which will run a script to help set up a separate customized game subdirectory for each MUSH (run it once per MUSH you plan to run). Files in these subdirectories will already be customized in many ways, so what follows may be slightly different. :) 6. The next step is to create your configuration file. In the game directory is a file called "mush.cnf". You may want to rename it <your MUSH name>.cnf. This is a list of all runtime configuration options with their default settting. Change them as you see fit. IMPORTANT: do not _delete_ any parameters. They all need to be there. Under win32 using the Microsoft compiler, DO NOT rename mush.cnf. Also, ignore the restart script. In the configuration file, turn off disk database compression; it is not supported. Remove the .Z endings from all the database names. If this is you first time starting a MUSH (or you want to start a new MUSH), copy game/data/minimal.db to game/data/outdb. Then go to the game directory and run PennMUSH.exe. Poof, you're done. For anyone using something other than win32 with the Microsoft compiler, you must edit the restart script. You must change GAMEDIR to whatever directory the restart script is in, and should change CONF_FILE to the name of the configuration file if it's not mush.cnf. The restart script is written for sh, and assumes a fairly standard Berkeley UNIX setup. If you're on a HP-UX or SysV machine, for example, you may need to change the restart script a bit (the ps options, for example). You should now be ready to start the game. This distribution comes packaged with a basic database - a God character, starting room, and master room. This file is called game/data/minimal.db. The restart script will load this database if it doesn't find another database to load. The god character "One" has no password, so you can log in without one. Of course, you should immediately set one (via @newpasswd). options.h has the Master Room as #2 by default; in the provided database, this room is created for you. Now you should be set -- all you have to do now is customize the .txt files in the game directory. The logfiles in the "log" directory generally contain useful information. You will probably want to read your main logfile (defined in the restart script) every time, since errors and other important messages get printed to that logfile. If you have any problems, see the section on Getting Help below - it has important information about how and where to get help! ============================================================================ III. Conversion Guide (previous users) This section explains how to upgrade to a new version of PennMUSH, or to convert from other MUSH servers (sort of). 1. dune.h/options.h/mush.cnf The 'make update' command will run the update.pl program, which examines the current options.h file, comparse it with options.h.dist, and reports any new or removed options which you can choose to define (or not) interactively. It's designed to make upgrading your options.h from patchlevel to patchlevel a much easier process. Assuming you've unpacked the new patchlevel in a directory called new/, and the old one in a directory called old/, you should copy your old options.h files into new/, and then type 'make update'. Make update also updates your mush.cnf file. Again, copy your old mush.cnf file to new/game/mush.cnf and run make update. Users of PennMUSH versions before 1.7.2 had another file called 'dune.h' that was similar to options.h. If you're upgrading from such a version, tack the contents of dune.h onto your options.h before you run make update. 2. Database format This MUSH version will read databases along the main branch of MUSH evolution -- TinyMUD, vanilla TinyMUSH, MicroMUSH, and all Pern/PennMUSH versions. If you need to convert a TinyMUSH 2.0 database, please contact Amberyl, and she'll mail you an extension to 2.0 that will dump a 1.50-readable flatfile. PennMUSH 1.7.x uses the version header in the database to automatically read the db correctly, no matter what options you have set, and to write a db which reflects those options. If you plan to convert a PennMUSH db to TinyMUSH 2.0, you'll have to unset all the options which add to the db, start up like that, and then shutdown to dump a plain PennMUSH 1.50pl10 db. You will lose all special info (warnings, etc.) in that db, so keep a copy of the original! Please read the CHANGES files. They contain a large amount of important information. A list of code changes that affect players is given in news.txt. You may want to clip that section for your own news file. 3. Improved destroy code NOTE: Past versions of PennMUSH were vulnerable to some types of database corruption. In particular, a room could lose track of its exits, which would then take up space in the database, but not be accessible by any ordinary method. PennMUSH 1.7.x identifies these corruptions and fixes them. When the MUSH first does an @dbck (about 10 minutes after startup) you may get a bunch of messages like this in your netmush.log: ERROR: Exit Out;o(#123E) leading from invalid room #456 destroyed. and Object Out;o(#456E) not pointed to by anything. Orphaned exit destroyed. and Object Out;o(#789E) not pointed to by anything. Moved to Room(#1234R). Do not be alarmed about a burst of these messages in the first ten minutes after startup. Most databases will have some of these orphaned exits. Do, however, inspect each of the rooms to which exits are moved, to decide whether you want to welcome back the prodigal exits. It is likely that many of the exits that get relinked may have been duplicated by later building. (One room on my test database ended up with three North;n exits and three south;s exits.) If errors like this happen after that initial burst, it then merits some concern. The initial burst of messages, though, should be a cause for attention, but not for alarm. [This message by RLM] 4. Upgrading from PennMUSH 1.7.0p9 or earlier Versions of PennMUSH before 1.7.0p10 used the "parent" field on players to keep track of who the player last paged. 1.7.0p10 removed this behavior; the last player(s) paged are now tracked in an attribute (LASTPAGED), and players can have parents like any other object. However, a DB flag was not added to track this change (an oversight on Javelin's part). So, if you load a db from an early version of PennMUSH, you'll find that many players have parents set (because that's who they last paged under your older source). Accordingly, you'll want to unparent all players. You can do this with: @dol lsearch(all,type,player)=@parent ##= ============================================================================ IV. Binary Guide (pre-built binary users) A pre-built binary is frequently available for win32 users who don't want to customize their MUSH server, and don't feel like compiling it themselves. This binary distribution does not contain the src, hdrs, hints, or os2 directories and is missing several key files (like Configure) from the top-level directory. It does include the dune.h and options.h that it was built with, as an aid to those who decide late that they want to customize the server; they are useful as a baseline to work from. Using the pre-built binary is fairly simple; adjust your configuration file as in II.6, then go to the game directory and run PennMUSH.exe. Alternately, if you want the MUSH to automatically start each time you turn on your machine, you can install it as a system service by running 'PennMUSH /install'. PennMUSH can be removed from service status via 'PennMUSH /remove'. ============================================================================ V. Additional Options There are two additional major things which you can change: RWHO and IDENT. MUSH provides an interface for connecting to an RWHO server. RWHO servers allow players to see who is connected to many MUDs via telnet, or, if the administrator allows it, via a direct RWHO command from the game. There are two possible options for RWHO. The first is not to use it. This is the default, and you can feel free to just keep it that way. The second option is to send login info to a remote RWHO server. This option is highly recommended, since it is simple and painless. It uses UDP to send the info, so there will be no slowdown of the game by enabling this. There are several steps to getting this set up. 1) Contact the administrator of an RWHO server and ask if you can send login info to that server. The names of administrators are generally in the MUDlist posted to rec.games.mud.misc. One of the larger servers is run by Moira (Jennifer Smith, jds@moebius.math.okstate.edu). Try sending her mail, with the name and address of your MUSH. 2) The administrator will probably send you mail back within a day or two, with additional info. You will get a password and an address for the RWHO server. Change the appropriate things in options.h and recompile. You should then be set. MUSH also provides an interface to the identd daemon on remote sites. Players who connect from these sites can be identified not only by site, but by account name. Like RWHO, you can choose to use IDENT or not. If you choose to use it, the ident_timeout configuration option in mush.cnf lets you set the maximum number of seconds the MUSH will wait to get an identd response. If you are running without the info_slave, slow identd responses _will_ lag the entire MUSH as people log in. The final thing you may want to think about is compiling announce.c or portmsg.c. These are port announcers; if your MUSH ever goes down, you can set one up, and a message will be given to a person attempting to connect to that port. Read that file for details. It is not an official MUSH piece of code; rather, it is a freely distributable program available via anonymous FTP that is included in this code because it happens to be fairly useful. Javelin suggests using portmsg - it appears to be more stable. ============================================================================ VI. Trouble-shooting If you ever run into trouble, the your first reaction should ALWAYS be to back up your database. indb.Z.old is the file that the MUSH saves indb.Z to when the game, restarted, indb.Z is the file that the MUSH loaded at startup, and outdb.Z is the file to which the MUSH is currently dumping the database. You can tell if a dump is (theoretically) complete by doing a "zcat <database file name> | tail -10". The last line should read "***END OF DUMP***". If it doesn't, your database has been truncated for some reason. Check the logfile. Possible causes include a full process table, a full disk partition, or running out of disk quota. Occasionally the dump process may dump core. This is caused by some sort of corruption in an attribute, normally. You can tell if the dump process has died by looking in your data directory; you will see something like "outdb.Z.#5#". Wait a few moments and check on the file again. If it has grown, then the game is in the process of a normal dump. If it hasn't, and there's a core file, then something has gone wrong. You should definitely shout a warning that building is not being saved. To attempt to fix the problem, do a @dbck to take care of any possible minor weirdness in the database, then try doing a "@dump/paranoid", and reading the checkpoint logfile (default is log/checkpt.log). This is slow, but it will write out an uncorrupted database, and tell you what it fixed. Back up that database and indb.Z, then figure out what you're going to do next: you can take the game down with a kill -9, or attempt to manually fix the problem by either @destroying the offending object, or attempting to reset the attributes on the object that are causing a problem. If "@dump/paranoid" dies, you are more or less out of luck. To fix weirdness in numerical fields, such as location or flags, use the "examine/debug" and "@fixdb" commands. Don't do this unless you know precisely what you're trying to fix, since it's possible to produce database inconsistencies which will panic, crash, or hang the server. The game may crash from time to time. It will generate a core file, usually; if you don't limit the coredumpsize or strip the executable, you should be able to get some useful information out of it, using a debugger. Javelin is interested in stack traces. You can do a stack trace in the following manner: Go into the directory where you keep your source code, and type <name of debugger> netmud ../game/core If you don't call your executable "netmud", substitute in whatever you do call it. You are looking for variables set to bizarre values - attempts to access objects that aren't there, attempts to use pointers which point to nothing, and the like. If you are using the "adb" debugger (don't do this unless you really have absolutely nothing else available), you will see nothing. It's loaded and ready, though. Type "$c". This will print out a list of the functions it called. Type "$q" to quit. You can't really get much more useful information out of adb. If you are using the "dbx" debugger, type "where" to see the stack trace. You can move through it using "up" and "down", and see exactly what the sequence of calls was. You can also use "print <variable name>" to see the value of a variable at the time the game crashed. The "gdb" debugger is similar to "dbx"; with that, you can abbreviate "print" as "p". Javelin appreciates news of any bugs found, and any patches that have been written to deal with them. He is also interested in any extensions that people make to the code, and requests that ones that are of more than just local interest be sent to him for inclusion in the next release of this code. One important thing to remember is, if the MUSH refuses to start, there is probably a good reason. Check the MUSH log, and the core file, if there is one. Make sure to back up your database before attempting to restart -- remember that every time it restarts, it overwrites indb.Z.old. If you restart three times and somehow manage to trash your database each time (for example, a full process table zero'ing out your files), you won't have a backup to restart from, unless you've backed up your database before trying! You can also find helpful tips in Javelin's Guide for Gods, which is available on the WWW as http://pennmush.org/~alansz/guide.html and by ftp from pennmush.org as /pub/DuneMUSH/Guide/guide-single.txt PennMUSH has been tested on a fairly wide variety of machines and operating systems including at least: NeXT Mach 2.1 Sun Sparc SunOS 4.1.x Sun Sparc and i386 Solaris 2.x DEC Decstation Ultrix 4.x and OSF/1 DEC Alpha OSF/1 and Linux SGI Indy Irix 5.x and 6.x HP 9000 series HP-UX 8.x IBM RS/6000 AIX 3.2 Novell Unixware SVR4 Linux FreeBSD AT&T SVR4 Windows 95/NT OS/2 There's no real reason why PennMUSH shouldn't compile on any 32-bit or better BSD, System V, or POSIX operating system. Javelin does his development on a Sun SPARC-series workstation, but has a variety of test platforms. If you have serious problems, contact Javelin and he will try to help you. Email is the best way to get a fast response; in an emergency, you can bother him on a MUD, but for code problems, email will probably get you a better response. ============================================================================ VII. Getting Help, Reporting Bugs Here are some guidelines about where and how to report bugs or problems or generally look for help. There are three places one could get help with a problem: 1. pennmush@pennmush.org is the PennMUSH mailing list. To subscribe, send email to listproc@pennmush.org with the words "subscribe pennmush YourNameHere" in the body of the mesage. The PennMUSH mailing list should only be used for problems, bugs, suggestions, ideas, discussion, etc. that are OF GENERAL INTEREST. It's often hard to say what's of general interest, but a good rule of thumb is: Anything that occurs before the MUSH process is running is *not* of general interest That is, don't report problems with downloading PennMUSH, compilation, installation, restarts, or database corruption to the mailing list. These are often system specific. 2. pennmush-bugs@pennmush.org is the bug reporting address for the PennMUSH developers (suggestions go to pennmush-developers, bugs to pennmush-bugs). This will generally give you the fastest response and is ideal for unusual bugs. 3. dunemush@pennmush.org is Javelin's email address. This is a good place for small suggestions, common-seeming bugs, etc. -- stuff you wouldn't want to bother all the developers with. You will receive a quick response. When reporting a problem, please always include the following information: 1. PennMUSH version number 2. The type of machine you are using (Sun SparcStation, IBM RS/6000, etc.) 3. The operating system and version (SunOS 4.1.2, AIX 3.2.4, etc.), 4. The compiler and compiler version (gcc 2.4.5, SGI cc 2.10, etc. -- the 'file' command usually tells you the compiler version, if there's no built-in option like '-v' or '-V' to give it), 5. Whether or not you have made any changes to the code. If the problem resulted in a crash and a core dump, a stack trace of the core dump (see the section above) should also be included. If I need additional stuff (like a log of the Configure or make), I'll ask for it, but if you know that it's relevant, you can send it along, too. ============================================================================ VIII. Getting a .pennmush.org hostname and mailing lists Thanks to donations from the PennMUSH community, Javelin was able to register the pennmush.org domain name, and, if you're running a PennMUSH, you can have yourmush.pennmush.org assigned as a hostname for your MUSH, so players don't need to telnet to obscuresite.obscuredomain.com! NOTE: A hostname is not the same thing as a site. We don't have accounts for you to run your MUSH from. You must already have your MUSH running at someplace.edu or whatever -- we just provide a nice hostname that will resolve into your current site's IP address. How do you get a pennmush.org hostname? Go to http://lists.pennmush.org/pennmush.html, and follow the instructions. It may take a day or two before the hostname will work. Thovald also has volunteered to host mailing lists for MUSHes in the pennmush.org domain. Details are on the same web page. ============================================================================ IX. Amberyl's Comments These are in the first person. :) I've been working with this code for a year and a quarter now. I can't claim that it's particularly elegant or inspired; all I can say is that it works (most of the time), and that I've had fun writing it. I'm also hoping that it's quite readable; the sections I've added or revised tend to be quite heavily commented. A number of people have been contributed a lot, directly and indirectly, to PennMUSH; many of them are credited in copyright.h. Read the file and embarrass them the next time you see them. ;) PennMUSH 1.50 patchlevel 3 contains the promised parser rewrite. A great deal of the code is derived or directly taken from the TinyMUSH 2.0 parser; credit goes to JT Traub (Moonchilde) and Glenn Crocker (Wizard) for writing the thing in the first place. In most cases, the 1.50 parser should now be functionally identical to the parser in TinyMUSH 2.0.9; see the news file for a brief summary of the changes. Major differences between the 1.50 and 2.0 parsers are almost certainly bugs, and should be reported to me. I do have a life, though, and academics/job/social stuff take priority. Thus, don't get too upset if it takes me a while to add your pet hack. :) I'm generally happy to discuss code and life in general, though, so if you see me on a MUSH, feel free to say hi. Enjoy your MUSH. -- Lydia Leong (lwl@digex.net) "Amberyl" just about everywhere ============================================================================ IX, cont'd. Paul/Javelin's Comments And let me recognize T. Alexander Popiel, Ralph Melton, and Thorvald Natvig, other past and present members of the PennMUSH development team. Working with them is a real pleasure. I am trying to keep extending the functionality of the server, while optimizing and rewriting things wherever possible. I'm always interested in improvements or ideas for the code, as well as anything you might have done to get it to compile and run on unusual systems. -- Alan Schwartz (dunemush@pennmush.org) Paul@DuneMUSHes, Javelin just about everywhere else ============================================================================ IX, cont'd again. Alex/Talek's Comments Since Javelin last worked on this document, there has been a changing of the guard on the PennMUSH development team. Ralph Melton has stepped down, and Thorvald Natvig has joined us. Again, I would like to thank Ralph, Amberyl, Moonchilde, and all the others who went either with us or before us. PennMUSH is the embodiment of many years of hard work by many people. May it never stagnate. -- Alex (talek@pennmush.org)