/
teeny/db/
teeny/dbm/
teeny/doc/
teeny/includes/
	This is the document for TeenyMUD 1.1. Seems quite solid. In general, a
lot of minor bug fixes over 1.0, and some fairly major improvements. See below.

Introduction
------------

	TeenyMUD is a disk-based clone of the TinyMUD server. It is
completely new code, and is not based on the original TinyMUD code at all.
It is NOT written in ANSI C. The game implemented by TeenyMUD is a fairly
vanilla version of TinyMUD -- pages, whispers, emotes (':' command), NO
pronoun substitions, NO message pages, NO Muck extensions and so on. What
follows is somewhat technical, but I frankly think you really need to read
and understand all of it to run TeenyMUD with any degree of success.

Bringing the server up
----------------------

	First you have to make the thing. There is a Makefile supplied,
typing 'make teeny' at the shell prompt should do it. In order to bring the
server up coherently, you need to understand vaguely how the server works,
so here we go:

	The database is stored in two files, an index file and a chunks
file. We'll get to the index file shortly. The chunks file is where most of
the data lives, scattered about more or less at random in the file. When
data is required, it is read in from this file and 'cached' in memory,
subsequent accesses to the same data can use the cached data and avoid
referencing the disk. The cache size is limited, however, so when too much
data is read in, the least recently referenced data is tossed out of the
cache, and written back to the chunks file if it has been changed since it
was read (or is data for a completely new object). Subsequent references to
that data will then, of course, force the data to be read back in from the
chunks file.

	The index file is used to store data about where in the chunks file
the data for any particular object can be found. In general, this data is
read in when the server is brought up, and kept in memory permanently.
Along with this data is stored the flags and name of each object in the
database -- these are referenced rather frequently, and so are stored with
the permanently-in-memory data. Incidentally, back of the envelope
computations suggest that the permanent memory usage of each object will be
about 50 to 60 bytes, roughly one fifth of what a TinyMUD uses per object.
This does not include the cached data, of course.

	The upshot of all this is that the index file on disk holds the
locations of everything in the chunks file at server startup time. Since
things are constantly being read from, and written back to the chunks file
(at possibly different places), the index file rapidly becomes wildly
inaccurate. The correct data is, of course, always available in memory.
Furthermore, the data in the chunk file is not completely up to date, since
a recently changed object may well be in the cache and not written back to
the chunks file. Thus, the server does periodic dumps to write everything
back to the chunks file, and rewrite the index file to correctly reference
all this data -- i.e. 'bring the db into synch'. The server then
immediately copies the index file to 'old.index' and the chunks file to
'old.chunks'. If the server crashes, the active index and chunk files are
rubbish, but the 'old.index' and 'old.chunk' form, as a pair, a database
correct and complete up to the last dump. Suitable use of the cp command
should let you bring the server back up as of the most recent dump.

	The server accepts several command line flags:

-l
	specifies that an existing database (index/chunkfile pair) is to
	used. Without this flag, the server will create a minimal database
	(Limbo and Wizard) from scratch. This flag cannot be used with the
	-t or -s flags.

-s
	specifies that a small initial database -- Limbo and Wizard -- should
	be built and used.

-t <text database>
	loads a text dump database, instead of an indexfile/chunkfile pair. See
	below for more on this type of database. This flag cannot be used with
	the -l or -s flags.

NOTE: You MUST use exactly one of the -l, -s, -t flags to tell the server where
to get its database. The following flags are optional.

-C n	specifies that a cache of size n kilobytes is to be used.

-c <name>
	specifies the name to use for the chunkfile (defaults to chunky.bits
	if this flag is absent).

-i <name>
	specifies the name to use for the index file (defaults to chunky.index
	if this flag is absent).

	Typically, you will first start the server with the -s flag, to force
it to build an initial database into chunky.bits and chunky.index. Then you
may shut the server down, and use the supplied startserver script to bring
it back up with a log file named 'logfile' and load this database.


The Console
-----------

	Running the server in the foreground gives you access to the
console. Pressing ^C (sending the server process a SIGINT) will cause the
MUD to freeze completely, and give you a console prompt. The console
accepts a few commands:

s         shut the server down after dumping the database.

d         dump the database

w         console WHO list. Shows who has 'Blown Quotas' -- i.e. who is
          spamming the server with lots of commands rapidly.

b n       boots player n off the game

g         'go'. Stops the console, and lets the server continue.

t [str]   create a text dump of the current database. This may be loaded at
          some later time by invoking the server with the -t flag. Optionally,
          the name of the text dump file may be given here (e.g. t dump.text).
          If no name is given, the default name, teeny.text, is used.

	The console is useful for a few things. Starting the initial database
can be accomplished by starting the server in the foreground, with the -s flag,
pressing ^C, and typing 's' at the console prompt. This has the effect of
building the initial minimal database (Wizard and Limbo), and then shutting
down the server, dumping this database into a usable chunks file/index file
pair. The -l flag can then be used when restarting the server.

	If someone is spamming your game, sending it thousand of commands
rapidly, and if you can foreground the server, you can grab the console, type
'w' to see who has lots of blown quotas, and boot them off with a suitable 'b'
command. This capability exists because of what happened to Islandia on its
last night. TeenyMUD is not, in general, spammer friendly -- when a player's
command quota runs out in a given time slice, Teeny does not merely slow them
down, it throws commands from that player away for the duration of the time
slice.

	The text dump and load facilities are useful for portability and
de-fragmenting your database. Attempting to move an existing index file/
chunks file pair to a new machine is probably a bad idea, and bad things
may well result. To move to a new machine, use the t command on the console
to create a text dump, move the text dump file to the new hardware, and
load it into the server with the -t flag on the command line. Doing an
immediate console dump (or shutdown) will create an index file/chunks file
pair that can be used on the new machine.

	In addition, each time a dump occurs, fragmentation data is written
to the log file (i.e. on standard error). This consists of 4 numbers, each
counting the number of free chunks (holes) in your chunkfile in a certain
range of sizes. The first number is the number of free chunks of size zero
or less, and should *always* be a zero. The second is the number of
non-empty free chunks too small to be used for anything, the next is the
number of chunks of useful size less than 512 bytes, and the last number is
the number of free chunks of size greater than 512 bytes. All these numbers
should be 'small', whatever that means. If they indicate that an
unsatisfactory percentage of your chunkfile is taken up by unusably small
chunks, your database is said to be 'fragmented'. To de-fragment, you can
bring the server up, do a text dump from the console, shut the server down,
and immediately restart with the -t flag to re-load the text dump. This
simply rebuilds a new copy of the old database, but does so in a
'sequential' fashion, which leaves no holes in the chunks file. If you dump
from the console immediately, you should get Fragmentation data of
'0 0 0 0'.


Configuring the server
----------------------

	You will need to make some changes here and there to set the server
up to work as you want it to, mostly to #define directives in includes/teeny.h.

	First, you need to edit the text hardcoded in the function 'greet()' in
misc.c to greet players with a banner more appropriate to your game. You may
also want to fiddle with the values of the TIME_SLICE and SLICE_QUOTA and
DUMP_INTERVAL in includes/teeny.h. TIME_SLICE and SLICE_QUOTA are probably fine
as distributed. These two define, roughly, how spammable your MUD is. Each
player is allowed SLICE_QUOTA commands in each TIME_SLICE interval.
DUMP_INTERVAL is, of course, the frequency at which to dump the database as
described above (NOT text dump -- this can only be done from the console).

	Added in version 1.1 is TIMESTAMPS. This does not actual provide full
timestamping. What it does do is build a database library capable of supporting
timestamping, the MUD databases (both chunks file, and text dump) will have
timestamp fields in them. NOTE: This obseletes older databases, though probably
a text dump could be converted with a trivial script. A function
stamp(<object number>) exists in utils.c. Scribbling suitable calls throughout
the code will cause timestamps to be somewhat meaningful. See internals.doc for
details.

	Defining LOGCOMMANDS will cause all player commands (except WHO and
QUIT) to be logged on standard error (your logfile). Commenting this define
out will turn logging of player commands off -- probably a good idea. Log
files get very large otherwise.

	Other defines that are probably ok as distributed are the SLACK and
GROWTH_INCREMENT constants defined in includes/db.h. You may want to tweak
these in, say, a fast growing MUD. SLACK is the amount of free space added to
the index above and beyond the number of objects currently in the database. If
this is greater than the number of objects created between the time the server
is started, and the time it is shut down, then the index will never have to be
re-sized. This is good, because re-sizing the index tends to waste memory. The
GROWTH_INCREMENT constant is the number of index entries to be added to the
index in the even that it should become necessary to re-size it.

	The port upon which the server listens for new connects (the port
at which the server 'lives') is defined by MUDPORT in mud/tcpio.c. It is
distributed as 6666.

	Lastly, you will need to select a cache size for your game -- this
is slightly tricky and depends on several factors. I see two reasonable
approaches to this problem:

	a) determine how much real memory you will typically have to run
the server with, and tune the cache so that the virtual memory size is
roughly equal to this. You should NEVER run the server with a cache so
large that the virtual size is routinely greater than the real size -- if
the operating system starts to page your cache in and out of its own
paging/swapping files, performance will drop sharply. See your local man
page on ps, and ask around if you don't understand all this.

	b) determine how many players will be active during fairly busy
periods, and make the cache large enough to hold the data associated with
them, and any 'social' rooms that will usually have players in them.
Roughly, multiply the number of players plus the number of rooms by, say,
2K and double that for a fudge factor. This will allow the commonly
referenced things to be usually in cache, and you will just have to accept
that exploring players, will cause a fair amount of disk activity.

	The first option will give you a the maximum size cache you should
be using, the second will be the minimum. Note that you should periodically
re-tune your cache, since as your database grows, the amount of permanently
resident data (the flags and names) will grow. If you have your cache tuned
with a small database to approximately fill available real memory, when the
database grows so will your process size, your server will start to page
and performance will drop. Also, keep an eye on the load your machine is
under, and re-tune appropriately. As I have not run any benchmarks, the
above remarks on cache tuning are merely educated guesses on my part. Cache
tuning is well known to be a black art.

The Wiz Password
----------------

	Ok, you made it this far, so I'll tell you what how to log in as
the Wiz in the minimal db you get at the beginning. The name is 'Wizard',
the password is 'foo'. CHANGE THIS PASSWORD. Note that you have to be sort
of careful as a wiz, in particular you can turn off your own Wiz bit. This
is not a good idea. In addition, TeenyMUD has no God Priv, so all wizards
have the same powers (somewhat extensive).

The Future
----------

	I have no plans whatsoever to extend this server at all. I hope to
fix bugs as they appear, and no more. You, gentle reader, may want to hack
at the server a little or a lot. Read the internals document if you plan to
do so.

		Andrew/bob