
============================================================================
                   User's Guide to PennMUSH 1.6.x
============================================================================

Some of this Guide was written by Amberyl, and is used with permission.
Most of it is by Paul/Javelin.

I.   Introduction
II.  Installation Guide (new users)
III. Conversion Guide (previous users)
IV.  Additional Options
V.   Trouble-shooting
VI.  Getting Help, Reporting Bugs
VII.  Comments

You may also want to take a look at Javelin's Guide for PennMUSH Gods,
at http://pennmush.tinymush.org/~alansz/guide.html
or by ftp from pennmush.tinymush.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-9).

Javelin, in conjunction with Talek (T. Alexander Popiel) and Ralph
Melton, are the current PennMUSH development team.

A MUSH manual should be available at caisr2.caisr.cwru.edu,
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.tinymush.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.

Here's a quick picture of the organization of the MUSH directory tree.
The "src" directory contains source code and subdirectories for
optional libraries. 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, the "win32" directory
contains files of use to people who want to compile PennMUSH for
Windows 95/NT, and the "os2" directory contains files of using in building
for OS2.


 top-level-+-> src -------+-> RWHO 
           |              +-> IDENT 
           | 
           +-> hdrs 
           +-> game ------+-> data 
           |              |   
           |              +-> txt -------+-> nws 
           |              |              +-> evt 
           |              |              \-> hlp 
           |              |                  
           |              +-> log 
           |              \-> save 
           +-> hints 
           +-> os2
           +-> utils 
           \-> win32
               


     The quickstart version of the installation is:

1. sh Configure -d
2. create options.h and dune.h, or make update
3. edit src/Makefile
4. make install
5. possibly make customize
6. edit game/mush.cnf and game/restart

     Here's the process in detail:

1. First, 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.


2. EITHER:

Then, copy options.h.dist to options.h and dune.h.dist to dune.h.  Note
that these files stay in the top directory, as there is a symbolic link
to them from the hdrs directory.

Edit each of these files. They are liberally commented. You probably
should read the whole file before making changes.

Also, cp game/mushcnf.dst to game/mush.cnf.

OR:

Type 'make update', and answer all the questions about which MUSH
options you want.

If you want the chat system, set CHAT_SYSTEM to 3 or 4. If you don't
want it, set CHAT_SYSTEM to 0. PennMUSH is now intelligent enough to
convert db's back and forth automatically.

If you use CHAT_SYSTEM 3, the initial default chat channels are listed
in chat.c. You can change these defaults at runtime (read the help for
@channel, and put the relevant commands on the @startup of an object).
CHAT_SYSTEM 4 doesn't hardcode the chat channels, and is recommended.

You do not need to change any of the other header files.

You next have to make sure you're set up for the IPC you need for your
machine. The only IPC package which is guaranteed to work is bsd.c.
Nick Gammon <nick@c034.aone.net.au> is responsible for the WIN32 port,
and can answer questions about compiling for Windows 95/NT.

3. You should next edit src/Makefile to select options for IDENT, RWHO,
and MALLOC support. These are discussed later in this file, but the
defaults usually work.

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.

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.

Next, 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.Z.  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 dune.h and options.h files, compares them with
dune.h.dist and 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 dune.h/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
dune.h and 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.

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.6.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 (except the CHAT_SYSTEM), 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.6.0 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]
 
============================================================================
 
IV.   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 three 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.

The third option is to send info to the RWHO server, AND enable reading
RWHO server info from within the MUSH (via the RWHO command).  This is
a BAD idea unless the RWHO server and the MUSH are on the same LOCAL
network. The reason for this is that retrieving RWHO info uses a stream
port, and the MUSH could freeze if the net between it and the RWHO
server went down. If you MUST run this way, you might want to talk to
mjr@decuac.dec.com about how to set up your own RWHO server.

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.

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.

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

V.      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.tinymush.org/~alansz/guide.html
and by ftp from pennmush.tinymush.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

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.

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

VI.	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.tinymush.org is the PennMUSH mailing list.
   To subscribe, send email to listproc@pennmush.tinymush.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.tinymush.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.tinymush.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.

============================================================================
 
VII.     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

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

VII, cont'd. Paul/Javelin's Comments

And let me recognize T. Alexander Popiel, and Ralph Melton, the other
two 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.tinymush.org)
		   Paul@DuneMUSHes, Javelin just about everywhere else 
