--- /dev/null
+ Run-time Installation and Configuration of PennMUSH
+
+This document assumes that you've successfully compiled and installed
+PennMUSH as described in the main PennMUSH README file.
+
+The next step is to create your configuration file. In the game directory
+is a file called "mush.cnf". If you don't have mush.cnf, but you have
+mushcnf.dst, you can copy mushcnf.dst to mush.cnf. This file 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.
+
+WIN32:
+ Under win32 using the Microsoft compiler, ignore the restart script.
+ In the configuration file, turn off disk database compression; it is
+ not supported. Then go to the game directory and run PennMUSH.exe.
+ Poof, you're done.
+
+UNIX:
+ Edit the restart script. Change GAMEDIR to the path to the directory
+ containing mush.cnf. Read about the optional settings in that file.
+ 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). Then run it.
+
+You should now be ready to start the game. This distribution can
+general a minimal database - a God character, starting room, and
+master room. The server will generate this database if it doesn't
+find another database to load.
+
+If you're starting with the minimal database, 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 minimal 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 error logfile (defined
+in mush.cnf) every time, since errors and other important messages get
+printed to that logfile.
+
+============================================================================
+
+ Game 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.
+
+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
+
projects / cobramush.git / commitdiff