/* ************************************************************************
* File: running.doc Part of CircleMUD *
* *
* All rights reserved. See license.doc for complete information. *
* *
* Copyright (C) 1993, 94 by the Trustees of the Johns Hopkins University *
* CircleMUD is based on DikuMUD, Copyright (C) 1990, 1991. *
************************************************************************ */
Compiling, Running, and Maintaining CircleMUD
Summary:
This document describes how to compile CircleMUD for the first time,
configuration information, how to run the server including documentation of
command-line options, a description of system logs and how to use them, and
a description of daily and long-term maintenance required by the MUD.
Intended Audience:
Implementors new to CircleMUD or MUD administration in general. This
document should be the first documentation read after the main "README" file
in Circle's home directory.
Table of Contents
---------------------------------------------------------------------------
1. Compiling Circle
1.1. Porting and Compatibility Issues
1.2. Makefile Options
1.3. Compiling the Source
2. Configuring Circle
2.1. config.c
2.2. Text Files
2.3. World Files
3. Running Circle
3.1. Execution and 'autorun'
3.2. Command-Line Options
3.3. Creating an Implementor Character
4. System Logs
4.1. Player Information
4.2. Usage Information
4.3. Errors
5. MUD Maintenance
5.1. Technical Maintenance
5.2. Non-Technical Maintenance
6. A Final Thought
---------------------------------------------------------------------------
1. Compiling Circle
1.1. Porting and Compatibility Issues
Ultrix 4.0 was used as CircleMUD's development platform up through
v2.00. Starting with 2.10, various versions of Linux were used from 0.99.11
up to 1.1.91. SunOS 4.1.3 on a Sun Sparcstation was also used for testing
many versions after 2.20.
For Circle 3.0, a great effort was made to make Circle more portable by
converting all of its system calls over to POSIX compliance. (POSIX stands
for Portable Operating System Interface for UNIX and is an effort to
standardize the way UNIX programs talk to the operating system. For more
information, see Stevens' excellent book, "Advanced Programming in the UNIX
Environment.") Converting Circle to POSIX vastly helps portability on POSIX-
compliant systems; most modern operating systems are POSIX-compliant.
Unfortunately, on some older systems that are not (such as NextSTEP 2.x), it
may be more difficult to compile 3.0 than it was to compile earlier versions.
The most important result of POSIX-standard system calls for MUD users
is that Circle is now compatible with SVR4 versions of Unix. In fact, Circle
3.0 compiles right out of the box under Solaris 2.3 (although it does require
extra libraries at the link stage -- see the next section on Makefile options
for details). If you have any POSIX-compliant system such as SunOS, Solaris,
Linux, or Ultrix, and an ANSI-compatible C compiler such as gcc, you should
be able to compile Circle with no changes to the source at all.
The author has personally compiled and run CircleMUD under the following
systems:
Ultrix 4.3
IRIX 4.0.5, 5.2
SunOS 4.1.1, 4.1.3
Solaris 5.3
AIX 3.2
Linux 1.1.91
ConvexOS V10.2
1.2. Makefile Options
Before trying to compile Circle, take a quick look at the Makefile. It
has a number of options to help compiling on specific operating systems; if
you see your operating system listed, activate the appropriate lines as
instructed in the Makefile.
The Makefile currently has options to compile the MUD under AIX, IRIX,
SVR4 systems such as Solaris. If your operating system isn't listed, don't
make any changes to the Makefile at all -- just try compiling with the
unmodified Makefile.
1.3. Compiling the Source
The /src directory contains the source code for the main MUD; /src/utils
has the source for a dozen or so MUD maintenance utilities. The Makefile
itself is in the /src directory. All compiling should be performed from the
/src directory. To compile the main Circle server alone, simply type 'make'
and cross your fingers. Type 'make utils' to compile the administration
utilities. Type 'make all' to compile both the server and the utilities. You
can also compile an individual utility by typing 'make x', where x is the name
of the utility you want to compile. Complete documentation of the utility
programs can be found in utils.doc.
Much effort has gone into making Circle as portable as possible, but
there is still a chance that you'll have problems compiling if you're using
some version of UNIX that I've never seen before. It's impossible to give
general advice on how to port software, except to say that you should ask a
friend who knows a lot about both UNIX and C to help you. Also, if you have
problems, you should definitely look at the CircleMUD FAQ, a copy of which is
distributed in Circle's home directory. There are a number of questions which
people often ask when they're trying to compile Circle, many of which are
answered in the FAQ.
If you do port Circle to some other platform successfully, please share
your hard work with others by sending a description of what you had to do to
get Circle to compile on your system to jelson@jhu.edu. Be sure to include
the specific name of your operating system and hardware.
The Makefile directs all compiled programs to the /bin directory.
Although not necessary, you may want to put Circle's /bin directory in your
$PATH.
2. Configuring Circle
Once you get over the initial euphoria of having your own MUD compile
successfully for the first time, you should be aware of some of the files
which control how Circle looks and feels so that you can configure it for your
personal taste.
2.1. config.c
The most useful file for configuration is the config.c source file. It
has dozens of options useful for customizing your MUD. Before you start
running your MUD, you should read through config.c from beginning to end,
checking what options are available as well as making sure they're all set the
way you want them. Remember, you have to recompile and rerun the MUD before
any changes you make to config.c take effect, of course.
2.2. Text Files
The place where most of your day-to-day changes will be is in the
lib/text directory, which contains all of the text files read by players. The
most visible file is "motd", (Message Of The Day), which is the message that
mortals seen (though not necessarily read!) when they log in. Similarly, the
"imotd" (Immortal MOTD) is seen by immortals when they log in. Other
interesting files are "news" (for the NEWS command), "help" (for the HELP
command), "help_table" (for HELP <x>), and others.
One file is particularly important: "policy". Despite what anyone tells
you and your best efforts to the contrary, your MUD will have political
problems. If anyone tells you that you can run a MUD without politics,
they're wrong. If you tell your players that you're going to run a
revolutionary MUD that doesn't have any politics, you're lying. Every MUD has
political problems sooner or later (usually sooner). There are various ways
to make political problems easier to handle, but the best way is to decide on
some ground rules from the very beginning, and then set those decisions down
in writing. That's what the "policy" file is for. You probably know what
kind of political problems MUDs have (you're not trying to run a MUD without
ever having played one, are you!?) -- stuff like playerkilling, thieving, kill
stealing, client use, multi-char playing, reimbursements, etc. Decide on your
policies early and make sure your characters know what those policies are.
It's also important to set down in writing rules for what immortals are
allowed to do and not allowed to do. That's what the "handbook" (Immortal
Handbook) is for. Immortals will always try to bend you as far as they can,
so it's important for you to decide on answers to questions *before* those
questions come up. Can immortals assist players? What about giving a 'cure
light' for a player about to die? Can immortals kill mobiles for their own
enjoyment? Can they kill players for the same reason? Are they allowed to
make policy? Break policy? Moderate disputes?
2.3. World Files
The root of the area hierarchy is lib/world. lib/world has 5
subdirectories: wld, mob, obj, shp, and zon, which is where the world, mobile,
object, shop, and zone files go, respectively. Each directory has a set of
world files in it with the appropriate extension (i.e., the obj subdir will
have a bunch of files ending with ".obj", such as 30.obj, 31.obj, etc.) plus
two special files called "index" and "index.mini". "index" is a list of which
world files are to be loaded by Circle. This makes the job of adding new
areas easier -- just add the new area files to your area directory, and then
add the name of the new file to "index". "index.mini" controls which
(smaller) set of world files should be loaded in the debugging mode (Mini-Mud
Mode, explained below.)
3. Running Circle
3.1. Execution and 'autorun'
Circle should always be run from circle's "root" directory, not the /bin
directory. You can run it manually by typing 'bin/circle' (useful for testing
and debugging). For running the game "for real", it's better to use the
'autorun' shell script provided in Circle's root directory.
Autorun lets Circle run itself for long periods of time. It
continuously runs the game as well as removing old system logs, moving newer
system logs to the /log directory, and saving certain log entries to permanent
files.
Autorun can be controlled by creating files with certain names. You can
use the 'touch' command to create a file, and, of course, the 'rm' command to
remove a file. If a file called '.fastboot' exists, the Circle will reboot
immediately if it crashes or is shut down instead of waiting 40 seconds as it
normally does. A file called '.killscript' will cause the script to terminate
itself; i.e., if you want to bring the game down. If you want to temporarily
prevent the MUD from rebooting, create a file called 'pause'; the script will
go into a wait loop until 'pause' is removed.
Although you can create these files manually, the SHUTDOWN command from
within the MUD has several options which will create these files for you. See
the SHUTDOWN help entry in wizhelp.doc for more information.
3.2. Command-Line Options
Circle recognizes a number of command-line options. You can use them
by actually specifying them on the command-line when running Circle manually;
or, by adding them to the FLAGS variable in your autorun script to use the
options automatically every time you run the MUD with autorun.
The syntax is:
circle [-m] [-q] [-r] [-s] [-d <path>] [<port #>]
-m Mini-Mud Mode. Mini-mud will be one of your most powerful debugging
tools; it causes Circle to boot with an abridged world, cutting the boot
time down to several seconds. It is useful for testing features which
are not world-related (i.e, new commands or spells).
CircleMUD uses split world files (in the lib/world hierarchy); each
directory (i.e., wld, obj, mob, shp, and zon) has a file called 'index'
which specifies which files should be loaded at boot-time. The file
'index.mini' specifies which parts of the world should be loaded with
the -m option.
-q Quick boot. Prevents checking of timed out object files. Every time
Circle boots, it checks every object file to see if it has timed out;
if so, it is deleted. This is done primarily to save disk space. If
time is more important to you than space, use the -q option. -q is
automatically activated when you use -m.
-r Restricted game. Allows you to decide at run-time whether or not the
game will allow new characters to be created. Using -r is equivalent
to typing "wizlock 1" (see wizhelp.doc for more information).
-s Special routines disabled. Allows you to suppress the assigning and
calling of all mobile, object, and world special procedures.
Historically used as a debugging tool in conjunction with the -d option
(see below), but now obsolete because Circle checks to make sure
entities exist before attempting to assign a spec_procs to them.
-d Data directory. Useful as a debugging and development tool, if you want
to keep one or more sets of game data in addition to the standard set,
and choose which set is to be used at run-time. For example, you may
wish to make a copy of the entire world in a separate directory, so that
you can test additions to the worldfiles without subjecting players to
unnecessary hazards. The default data directory is 'lib'. Any core
dumps (may they never happen to you!) will take place in the selected
data directory.
port Port selection. Allows you to choose on which port the game is to
listen for connections. The default port is 4000, which is historically
the port used by most DikuMUDs. You can change default in config.c and
the PORT= line of the autorun script. (The PORT= line of config.c
simply passes the value as a command-line parameter to circle.) The
port specified on the command line or by the autorun script will take
precedence over the port specified in config.c.
3.3. Creating an Implementor Character
The first character to log in to the MUD will be made the maximum
(Implementor) level. If you log in and aren't made an implementor, then the
playerfile probably isn't empty -- take the MUD down, delete the playerfile
(lib/etc/players), and start the MUD again. You should fix your stats using
the RESTORE command when you first create the character (i.e., type "RESTORE
<your-name>".
Once you're logged in as an implementor, type WIZHELP for a list of
privileged commands. Documentation of those commands is contained in the file
wizhelp.doc. wizhelp.doc is in the standard help file format, so you can
simply add it to the help index file if you want online help available for
wizard commands. (wizhelp.doc is not contained in the online help by default
as a security precaution.)
To create additional wizard characters, log them in normally as level
1. Then, advance them using your implementor character, using the ADVANCE
command. See wizhelp.doc for more information.
4. System Logs
CircleMUD writes a wide variety of information to standard output. If
you're using the autorun script, the boot messages are put into a file called
"syslog". During Circle's boot sequence, the system log keeps a record of
everything the MUD is doing to initialize itself; this can be useful to
determine what the problem is if the MUD dies while it is booting. Once the
game is up and running, the syslog contains player information, recording when
players connect, disconnect, rent, unrent, quit, die, hit death traps, etc.
The game also records status information about itself, falling generally into
two categories: usage information and errors.
4.1. Player Information
The player information recorded by Circle's system logs will serve you
very well as your players start to make wild claims about strange bugs
resulting in them losing equipment or points. Many mudders prey on the
insecurities of a new mud administrator who is terrified that his or her MUD
is riddled with bugs and will do anything to satisfy grumpy players -- don't
let yourself fall into that trap! CircleMUD is bound to contain bugs, but
most of the core systems have been well tested, so you should take claims such
as "I magically lost all my stuff!" with a grain of salt and check your system
logs.
If a player ever asks you for reimbursement of equipment, money, gold,
experience points (XP), or whatever, your gut reaction should always be to
check the logs first.
As a sidebar, let me point out that the value of system logs is
twofold: 1) they actually provide you with valuable information,
and 2) they make your players paranoid. When I first started
mudding and I heard about this mysterious "system log", it made
me incredibly paranoid. Now that I've done a good deal of MUD
administration, I've seen the same paranoia in _many_ other
players.
That paranoia is a very good thing. The system logs become an
abstract and shapeless but omnipresent force on the MUD. Players
hear about "the System Log" and then get paranoid that everything
they do is being recorded, so they tend to behave, lest the evil
System Log betray their wrongdoings to the Gods.
For this reason, when you go to check your logs, it's a good idea
to say something like "Hold on -- let me go check the system logs,
OK?" because it reinforces the syslog's presence in the collective
psyche of your players.
Back to the point. When someone claims that they've been wronged by the
evil system, always check the logs. The logs give you power to say things
like "What do you mean your items disappeared in rent -- it says right here
in the logs 'Rasmussen has quit the game.' -- you didn't rent at all, you just
QUIT!"
To diffuse disputes such as, "The game dumped my stuff, but I had enough
money!!", two types of log entries are written. First, every time a character
rents, the log records the character's per diem rent rate as well as the total
amount of money on hand and in the bank. Second, the log records makes a
record of all characters' equipment dumped due to insufficient funds.
Remember, rent is specified as a daily rate but is amortized on a per-
second basis! In other words, if you rent at the rate of 100 coins per day
and come back 36 hours later, you'll be charged 150 coins.
The autorun script saves 6 levels of raw system logs. In addition, it
greps the logs for certain pieces of extra-juicy information to save
indefinitely.
The system logs are your friends. Love them.
4.2. Usage Information
Every 5 minutes, the game counts how many people are playing and records
that information in the system log. Optionally, if you #define RUSAGE in
comm.c, it will also record system resource information such as CPU time and
memory used. The usage information currently logged by Circle is, as you can
see, somewhat sparse; local MUD admins are encouraged to add to this code as
is appropriate for their particular site.
Usage information isn't critical, but it is interesting to look at the
usage patterns to determine when your peak playing hours are. If you're good
at using 'cut' and other Unix utilities, you can even dazzle your friends by
graphing your MUD's system usage.
[ Note: friends not included with the CircleMUD distribution. ]
4.3. Errors
Just as your first gut instinct should be to look at the logs if a
player starts begging you for something, your first gut instinct in the event
of a crash or unexpected shutdown should also be to look at the system logs.
A Unix utility called 'tail' is used to look at the last few lines of
a text file; it's very useful for looking at the last entries in the system
log to see the last thing that happened before the shutdown. Often, Circle
will report an error in the logs just before it crashes. This method is
particularly useful if the MUD crashes during its boot sequence, because the
logging during boot is intensive.
If Circle shuts down unexpectedly and there is no core dump in the /lib
directory, the game probably detected an internal error and killed itself.
Such shutdowns are always preceded by entries in the system log describing the
error.
If there's no error message at the end of the log, then there probably
IS a core dump, so you can use 'dbx', 'gdb', etc. to examine the core dump and
determine the reason for the crash. The file 'hacker.doc', generously
provided by Furey of MERC Industries, offers useful insight into the art and
science of debugging -- you'd be well advised to give it a look-see.
Circle sometimes encounters a serious but non-fatal error; in this case,
the error will be written to the system log with the prefix SYSERR, but the
MUD will not shut itself down. You should always be aware of any SYSERRs
which occur -- they are often useful for foreseeing imminent danger or
averting problems before they become critical. If a SYSERR does occur, try
to determine if a change you've made recently has caused it. Ignoring SYSERRs
is like ignoring compiler warnings: you can be tempted to ignore them because
the game keeps going even if they exist, but you can easily get yourself into
trouble by not listening. The autorun script saves all SYSERRs to the file
log/errors.
5. MUD Maintenance
5.1. Technical Maintenance
Once you get the MUD up and running, you'll surely want to modify it --
adding new areas, new features, new code, and new ideas! But, those topics
are beyond the scope of this document. See coding.doc, areas.doc, and other
creation documents for more information about how to customize your MUD once
you get it up and running. This section simply focuses on some of the simple
maintenance that'll be necessary to keep your MUD running smoothly. Make sure
not to get so caught up in being a God that you forgot you're also supposed
to be acting as a software engineer!
First, you should look at the log/errors file regularly to make sure
there are no recurring problems, particularly problems that may have been
caused by code you've added. If the MUD crashes, it will usually generate
what's called a "core dump" -- a big file called "core" in your lib directory,
created by the operating system to record the state the game was in the moment
before it crashed. You should look at the core dump using a debugger such as
"gdb" or "dbx" to determine why the MUD crashed. See the file "hacker.doc"
for more information about debugging.
You probably will want to clean out the playerfile on a regular basis
to remove deadweight characters (i.e., people who log in and look around for
10 minutes, and then never come back). You can decide how often to purge the
playerfile -- every day if disk space is tight, or every month if it isn't.
The purgeplay utility program included in the src/util directory removes
deadweight players. Make sure to run the "purgeobjs" script (in the
lib/plrobjs directory) after you purge the playerfile. purgeobjs removes the
object files of players who no longer exist in the playerfile.
The 'automaint' script in the main circle directory will automatically
purge the playerfile and player objects for you. DO NOT RUN THIS SCRIPT WHILE
THE MUD IS RUNNING! Doing so will make your life (more) difficult.
5.2. Non-Technical Maintenance
Okay, so now you have your wonderful CircleMUD up and running smoothly
and all is right with the world. Right?
Wrong.
Well, technically, right. Circle requires very little day-to-day
attention in order to keep the program itself running smoothly. But the MUD
itself is just a series of instructions running on a computer, processing
data. Never lose sight of the fact that there will be dozens, hundreds, or
maybe even thousands of people connecting to your MUD -- and they are not
programs. They're people!
What I'm getting at is: from the technical side, there are relatively
few things you have to do to keep the game running. But you can't just dump
a MUD on the Internet and then ignore it! Spend time on your MUD. Try to
keep up with the boards, and make an effort to respond to the complaints,
ideas, and suggestions posted there. Take a look at the 'bug', 'typo', and
'idea' files from time to time -- and maybe even respond to some of the ideas
using Mudmail. Try to respond to Mudmail you receive from players in a timely
manner. Make sure that your 'news', 'policy' and other text files are
up-to-date and suit the political climate on your MUD.
If you can't or just don't want to deal with the player politics, make
sure that you choose someone who can and will, and make them responsible for
dealing with it. If no one does it, your MUD will stagnate and die.
6. A Final Thought
Try to remember that running a MUD should be fun. It can sometimes be
easy to lose site of the ultimate goal of personal enjoyment that MUDs are
supposed to provide, particularly when MUDs start to get crushed under the
weight of their own politics or the egos of the administrators. If you find
that your MUD is more of a source of frustration than enjoyment, don't be
afraid to close it.
Good luck with your MUD! And, always feel free to write me and let me
know what you think of the MUD, and the interesting things you've done with
it. I can't promise a timely response, but I love hearing from people who are
using my code.
-- Jeremy Elson
jelson@cs.jhu.edu