             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, DO NOT rename mush.cnf.
  Also, ignore the restart script.  In the configuration file, turn off
  disk database compression; it is not supported.  If this is you first
  time starting a MUSH and you don't have an indb file (or you want
  to start a new MUSH), copy game/data/minimal.db to game/data/indb.
  Then go to the game directory and run PennMUSH.exe.  Poof, you're done.

UNIX:
  On Unix or similar systems, you should link it to <your MUSH name>.cnf
  (if you don't have links, rename it to <your MUSH name>.cnf).
  Then edit the restart script. Change CONF_FILE to the new name of the
  configuration 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).

  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.

If you're starting with the minimal.db, 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.

============================================================================

                            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

