Javelin's Guide for PennMUSH Gods

Note: This document is available as both a single document (suitable for printing) and a multi-part document (more appropriate to hypertext). These multiple views are automatically generated with a Perl script called multiview, by James "Eric" Tilton, 3/29/94 (jtilton@willamette.edu), heavily modified by me. This document is text-browser friendly. Copyright (c) 1994, 1995, Alan Schwartz (alansz@cogsci.berkeley.edu / Javelin). This document may be distributed freely in whole or part so long as none of its text is changed, no profit is made from the distribution, and appropriate attribution is given to indicate the source of the text. While every effort is made to ensure accuracy, the author can not be responsible for the results of applying the ideas herein.

The current edition of this document is available online at http://pennmush.tinymush.org/~alansz/guide.html.

Here are the diffs since the last revision of the Guide, and here's the guide's log of changes.

You can search the Guide.

Please leave your comments about this Guide!

Introduction and Thanks

Documentation is never a solo project. I am indebted first and foremost to Amberyl (aka Lydia Leong) not only for maintaining, updating, and generally rewriting the PennMUSH code into the form I received it in, not only for teaching me a great deal about how to build, run, hack, and debug a MUSH, not only for writing an excellent MUSH user and coder manual herself, but for that first roybit which got me started on the path to MUSH administration!

I also thank all the MUSH gods who've contributed questions, problems, suggestions, patches, and ideas to the various MUSH mailing lists and newsgroups. As well as the players and admin of the various MUSHes which I've been involved in as site/source hack or consultant (Pandemonium, Mua'kaar, Gohs, Dune II, Princess Bride, Dorsai, and especially DuneMUSH) for their patience. :)

Table of Contents

• Introduction and Thanks
• Table of Contents
• Choosing to use PennMUSH
  • MUSH servers
  • Gathering system info
  • Penn and Tiny compared
• Compiling PennMUSH
  • Getting PennMUSH
  • Files explained
  • Options explained
  • Making PennMUSH (post-pl10)
  • Making PennMUSH (pl10 and earlier)
  • Troubleshooting
• Starting up
  • The game directory
  • The .cnf file
  • The restart script
  • The txt/*.txt files, @readcache, and mkindx
  • Minimal.db and first startup
  • Troubleshooting
• MUSH Management
  • Using #1
  • Dumps, shutdowns, db corruption, and paranoia
  • Wizard commands in detail
  • File descriptors and login limits
  • MUSH crashes
  • Lagging
  • Security
  • Making Guests
  • Everyday stuff
  • Useful globals
  • Miscellany
• Hacking PennMUSH
  • When to hack
  • Source code control, patches, and #ifdef
  • How-to
    • Add flags
    • Add powers
    • Add chat channels
    • Add attributes
    • Add locks
    • Add functions
    • Add commands
  • Upgrading to a new patchlevel
  • Miscellany
• Running a Successful Game: Tips from Gods
  • Contributors
  • Design tips
  • Administration tips
  • MUSHcode tips
  • Server tips
• Resources
  • Where to Report Bugs/Problems
  • The PennMUSH mailing list
  • Newsgroups
  • Ftp Sites
  • Other MUSHes
• Appendix: Useful scripts and code

Choosing a MUSH server

Contents

• MUSH servers
• Gathering system info
• Penn and Tiny compared

MUSH servers

Now there are five MUSH servers I'm aware of:

PennMUSH 1.6

The subject of this guide, a memory-based MUSH server. PennMUSH tends to suffer from creeping featurism, which may be a good or bad thing depending on your outlook. :) It's developing toward having a superset of the TinyMUSH features.

TinyMUSH 2.0

The last developed version is 2.0.10p6, I believe. This has been the standard disk-based MUSH server, though TinyMUSH 2.2 seems to be supplanting it, as there doesn't seem to be much development on 2.0 now.

TinyMUSH 2.2

A rewrite of much of TinyMUSH 2.0, with a similar feature set. The current standard for disk-based MUSH servers.

AlloyMUSH 1.0

Based on a beta version of TinyMUSH 2.2, with various PennMUSH features added like @mail, powers, and zones.

TinyMUX 1.0

Based on TinyMUSH 2.0.10p6, with various PennMUSH features added, like @mail, powers, zones, all the Penn functions, and new channel and macro systems.

A very good list of servers that's often more up-to-date than the one above is maintained by T. Alexander Popiel at http://www.tinymush.org/~popiel/mushinfo.html.

Gathering system info

1. What is the brand and model of the hardware? For example: Sun Sparcstation 2, DEC Decstation 3100S, etc. The "uname -a" command often will give you this information.
2. What is the name and revision level of the operating system? For example, SunOS 4.1.3_u1, Ultrix 4.2, etc. "uname -a" gives this information. It may also be mentioned in the banner you see when you log into the system or in the file /etc/motd. It's useful to know if the operating system is basically BSD (SunOS 4, Ultrix, HP-UX, Linux, NeXT) or SysV (Solaris 2, Irix)
3. How much physical memory is in the machine? For example: 8Mb (typical of a 386/486 machine), 16Mb, 64Mb, etc. Physical memory is ram chips on the machine's motherboard. Figuring this out can be tricky. You can usually find this out if you reboot the machine, or can read its boot logs, which are /usr/adm/messages or /var/adm/messages on most BSD systems.
4. How much virtual memory (swap space) is the machine configured for? Unix systems can use disk space as virtual memory - it's slower than physical memory, but much cheaper and more available. Virtual memory is used when processes need to be paged (portions of their memory sent to swap space) or swapped (the whole process sent to swap space) to free more physical memory. The command /etc/pstat -s reports total memory space (physical + swap) on BSD systems. Solaris uses swap -l. For others, check the man pages for 'swap' or 'virtual'. Typically, machines have around twice as much swap as physical memory, but this varies.
5. How much disk space will the MUSH have available to it? If you're running the game on someone else's machine (and of course you have permission, right? Illegal MUSHes are easily detected and often result in nasty consequences and give MU*'s a bad name), how much disk space can your game account use without causing problems? The upper limit is usually the size of the disk partition on which the game account lives. The "df" command shows the size of disk partitions, and the directories which are housed by those partitions.
6. What is the typical user load of the machine, and what is important to the users? If you own the machine and it's the workstation on your desk that only you use, there's no problem. If the machine is used by others however, it's important to consider what kind of other software is likely to be run. If people use it for email, news, and word-processing, they'll want quick keyboard response, but won't be taking up much CPU or memory. If people use it to compile large software packages or run statistical analyses, you'll be sharing much more CPU and memory.
7. How is the machine connected to the internet? Most university sites don't have to worry about the bandwidth of their connections, but if you're connected via a 14.4k SLIP line, expect some trouble. :)

Penn and Tiny compared

Typically, this means that you want to run PennMUSH when you have plenty of memory to spare, and TinyMUSH when memory is scarce but you have plenty of disk space (and fast disks).

Actually, things are a bit more complicated on modern workstations, since parts of the PennMUSH process that aren't being used will generally be paged out of memory to disk by the operating system. In some cases, this can be more efficient than having the MUSH server do the paging, but generally, it results in more use of physical memory.

Here are some typical usage statistics. The "memory" column refers to the game's total size (SZ on ps listings). The "disk" column refers only to the uncompressed size of the database - not the source code, executables, backup databases, etc. (TinyMUSH entries include the size of the .gdbm.{db,pag,dir} and the .db file). Typically for PennMUSH, you have 2 databases: the database from which the process was started (indb) and the database which the process is currently using/writing (outdb). It's also possible to use compressed databases, which save considerable disk space at the cost of longer startup times and dumps.

Type  OS           Name        # Objects  Memory  Disk
Penn  Sun4.1.3u1   DuneMUSH    19000      28Mb    14Mb uncompressed
Penn  Ultrix4.2    DuneII      2200       8.7Mb   3.8Mb uncompressed
Penn  Linux1.0.8   Gohs        2500       5.5Mb   1.6Mb uncompressed
Tiny  Sun4.1.3     TwoMoons    9350       5.5Mb   30Mb               (1)

(1) Info from elfchief@lupine.org. TwoMoons is based on Tiny 2.0.10p6

What Penn has that Tiny does not:

• The Royalty flag, and @powers
• Multiple control and local master rooms via Zones
• A built-in mail system
• A built-in chat channel system
• A built-in building/topology checking system
• Object creation/modification times
• More extensive help and other documentations systems (news, rules, events, index)

What Tiny has that Penn does not:

• The @robot command
• The @forwardlist command, which makes creating puppets which report to multiple players a whole lot easier
• Exits within things and players
• The very handy @attribute and @list commands
• Exits are inherited from parent rooms

Compiling PennMUSH

Contents

• Getting PennMUSH
• Files explained
• Options explained
• Making PennMUSH (post-pl10)
• Making PennMUSH (pl10 and earlier)
• Troubleshooting

Getting PennMUSH

PennMUSH now uses the following version-numbering scheme:

                                 1.6.0 patchlevel 0
                                 | | |            |
          Code base version -----/ | |            |
          Major version -----------/ |            |
          Minor version -------------/            |
          Patchlevel -----------------------------/

You can find the most recent PennMUSH code at pennmush.tinymush.org in /pub/PennMUSH/Source.

It will have a filename like "pennmush-1.6.8.p0.tar.gz". Once you've got the file, you'll need to uncompress it (using gunzip or uncompress if the file ends in .gz or .Z, respectively), move it to an empty directory, and untar it ("tar xvf pennmush-1.6.8.p0.tar"). PennMUSH does not create its own top-level directory when untarred - be sure you untar it in an empty directory!

There may also be patches in that directory, which should be applied to the code once you've uncompressed and untarred it. They have names like 1.6.8-patch01.

PennMUSH releases are signed with Javelin's PGP public key, which is also available in the ftp directory.

Older versions of the PennMUSH source code can be found in the "oldsrc" subdirectory.

Files explained

The PennMUSH source includes the following files:

BUGS

A list of known bugs in the current release. If you fix one, let me know!

CHANGES-#

A set of files describing changes to the code from patchlevel to patchlevel

Configure

A program which automatically configures MUSH for your system and builds you a Makefile and some other important files.

FAQ

Some frequently asked questions

Makefile.dist

The distributed Makefile for compiling the MUSH (pl10 and before). You'd copy this to Makefile and modify that.

Patchlevel

A file which tracks official patches to prevent them from being applied out of order. Don't mess with it.

README

Compilation instructions

options.h.dist

A file which contains compile-time options that you'll want to set. Copy this to options.h, and modify that.

dune.h.dist

More compile-time options. Again, copy this to dune.h and modify that. (post-pl10)

src/announce.c

The source code for a standalone port announcer. You can use this code when your MUSH is down to provide a simple message when people try to connect. But it's a bit buggy, so consider using portmsg.c, instead, described in the Appendix on Programs and Scripts.

hdrs/ansi.h

The header file defining ANSI codes

src/atr_tab.c

Attribute table stuff. This code handles the hashed attribute table, and contains the attribute alias table.

hdrs/atr_tab.h

The table of standard attributes. All standard MUSH attribs are listed here. The format is described below.

src/attrib.c

Attribute setting and getting

hdrs/attrib.h

The header file which lays out the actual attribute (ATTR) structure

src/boolexp.c

Working out boolean expressions (like locks!)

src/bsd.c

The tcp/ip socket interface to the MUSH. Handles player connection to the game, low-level input/output from players, WHO and QUIT. This is where the main() function is and where the main input/output loop is.

src/chat.c

The code for the @chat/@channel system. The list of chat channels is at the very end of this file.

hdrs/chat.h

Header file for @chat/@channel system

src/compress.c

A wrapper for the routines to compress and uncompress the text of attributes. This keeps down MUSH memory requirements. It either defines things for no compress, or includes compress_h.c or compress_b.c, depending on the setting of the COMPRESSION_TYPE option.

src/comp_b.c

MUSH before 1.50pl10 used a "bigram" compression method, which is simple and unlikely to go very wrong, but doesn't give very good memory savings. This file contains that algorithm.

src/comp_h.c

MUSH after 1.50pl10 introduced a Huffman compression method which should reduce memory requirements but be slightly slower.

src/comp_w.c

Nick Gammon's word-based compression, required for Win32 machines. Unix sites can also use this method, which is more efficient for large databases than Huffman, but is not 8-bit clean.

src/conf.c

Code to read your mush.cnf file and set up the MUSH's configuration

hdrs/conf.h

Important MUSH configuration constants that are rarely changed.

src/connect.c

A file which does nothing. Ignore it, but don't delete, since the Makefile expects to find it. This is ancient stuff.

src/convdb.c

Code which does db conversions for db's which don't contain a Powers field and the like.

hdrs/copyrite.h

The copyright statement

src/cque.c

Code to maintain the MUSH queue

src/create.c

Object creation code

src/db.c

Code to implement the MUSH database, let you access objects, etc.

hdrs/db.h

Definitions of objects in the database, macros

hdrs/dbdefs.h

Definitions of macros about db objects

src/destroy.c

Object destruction code

src/dump.c

Code for a miniprogram which dumps all of a given user's objects out of a db. Generally ignored. Build with 'make dump'.

src/extchat.c

This will be the source code for the extended chat system. Currently, in progress.

hdrs/extchat.h

Headers for extended chat.

hdrs/externs.h

Header file of externally defined stuff

src/extmail.c

The source code for the EXTENDED_MAIL mailer, included by src/mail.c when defined.

hdrs/extmail.h

Header file for extended mail system.

src/extract.c

Code for a miniprogram to extract a subsection of a db. Generally ignored. Build with 'make extract'.

src/flags.c

Code for setting, checking, and using MUSH flags is here. Also, the flag table and powers table are here.

hdrs/flags.h

Constants representing MUSH flags and powers are defined here

src/function.c

The function table and code for dealing with it.

hdrs/function.h

Header file for the function parser and function table.

src/fun*.c

The src/fun*.c files (src/funlist.c, src/funmath.c, etc.) contain the definitions of PennMUSH functions of various types. If you add functions to PennMUSH, add them to src/funlocal.c.

src/game.c

Another biggie. The MUSH command parser lives here. All commands (by players or objects) are parsed here, and the appropriate functions are called elsewhere.

hdrs/game.h

Header file for game.c

hdrs/getpgsiz.h

Header file to simulate the getpagesize() system call if your system doesn't have it. This is used only with the gmalloc package, and in fact behaves incorrectly on at least Ultrix 4.2.

hdrs/globals.h

Global macros. A very small file.

src/gmalloc.c

The source code for the GNU malloc package, one of the 3 basic malloc packages. Discussed below.

hdrs/help.h

Header containing the structure of a help index entry.

src/intrface.c

This file really doesn't do much more than #include bsd.c. If more kinds of interfaces were written (or if the port concentrator worked), this file would include the appropriate code.

hdrs/intrface.h

Definitions for the interface code.

src/lock.c

Code for the extended @lock system introduced in pl13. To add new locks, you'll modify the top of this file.

hdrs/lock.h

Header file for the extended @lock system. To add new locks, you'll modify the bottom of this file.

src/log.c

Code to do logging of things to the logfiles

src/look.c

Code for look and examine

src/mail.c

Code for the MUSH @mailer. In the post-1.50pl10 releases, this is really just a stub that selects either src/origmail.c or src/extmail.c, based on whether EXTENDED_MAIL is defined in dune.h.

src/match.c

Code to determine if an object matches a name, with various constraints. This is where the MUSH figures out if, say, there's an exit in the room called 'out'.

hdrs/match.h

Header file containing the match.c prototypes, which is included in other modules which intend to use matching functions.

src/memcheck.c

Code to do some simple checking on the allocation and deallocation of memory

hdrs/memcheck.h

Header file for mem_check.c

src/mkindx.c

The standalone mkindx program, which creates indexes for the help.txt, news.txt, and events.txt files.

src/move.c

Code to move objects from place to place. Commands like @tel, enter, and moving through exits.

hdrs/oldattr.h

The old header file attrib.h, used in some db conversions

src/origmail.c

The source code for the original (pre-1.50pl10) MUSH mailer.

src/parse.c

The function parser

src/player.c

Code to handle players, including creation, password-checking, names and aliases, etc.

src/plyrlist.c

This maintains the list of connected players and aliases.

src/predicat.c

A bunch of standard functions to check various conditions. One of the most important source code functions, controls(), is here (which determines when one thing controls another!)

src/rob.c

Code to manage MUSH money, include give and rob.

src/rpage.c

Code for remote-paging of other MUSHes

src/set.c

Code for setting object attributes.

src/smalloc.c

The Satoria malloc package, one of the 3 standard ones.

src/speech.c

Code for messages, including say, pose, page, whisper, @emit, etc. (Doesn't include @mail or @chat)

src/strutil.c

Utility functions for doing string comparisons and similar kinds of things.

src/timer.c

The game timer, which determines when a dump should take place, when objects from the wait queue should be triggered, etc.

src/unparse.c

Unparsing an object is correctly displaying its brief examine information (flags, locks, etc.) Some routines for that are here.

src/utils.c

Various utility functions.

src/version.c

Sounrce file which implements the @version command, reporting build time, date, flags, and MUSH version. This file is rebuilt at every compile.

hdrs/version.h

Header telling you the version of the code

src/warning.c

Code which implements the building warning system if USE_WARNINGS is defined in dune.h. (post-1.50pl10)

hdrs/warning.h

Header file for the warning system (post-1.50pl10).

src/wild.c

Code for wildcard matching

src/wiz.c

Wizard functions and commands are defined here

win32/

Directory containing support files for porting PennMUSH to Windows NT or Windows 95. This port was done by Nick Gammon.

RWHO/

Directory containing the code for the RWHO library, needed if your MUSH is going to send or receive RWHO information. Just go in here and type 'make' to make the library (librwho.a).

IDENT/

Directory containing the ident library, which allows your MUSH to get user account information for connections from sites running the ident daemon. (post-1.50pl10)

game/

The directory for run-time game stuff, including:

game/access.cnf The access.cnf file controls which sites can access the MUSH in a various ways. You can prevent sites from connecting, creating players, and connecting to guests. You can also enforce registration and automatically SUSPECT players from certain sites. Details about access.cnf can be found in the section on Security.

game/mush.cnf

The run-time configuration file for the MUSH. Discussed below. Many people copy this file to once called <mushname>.cnf, and modify the restart script to use that file instead.

game/names.cnf

A list of names which players aren't allowed to use. Obscenities typically, and/or out-of-theme names.

game/restart

The MUSH startup/restart shell script. You'll want to edit this to reflect your setup. Discussed below.

game/data

The directory for game databases in use

game/data/minimal.db.Z

The minimal database, containing 3 objects: #0 (Limbo, the start room), #1 (One aka God, the SuperWizard), and #2 (the Master Room)

game/log

The directory where MUSH log files are created

game/save

The directory where backup databases are usually kept

game/txt

The directory for text files used by the MUSH

game/txt/connect.txt

Text file shown when a player connects to the MUSH

game/txt/create_reg.txt

Text file shown when a player tries to create a character from a site where creation is not allowed.

game/txt/down.txt

Text file shown when the MUSH is set to disallow non-admin logins and any player tries to connect

game/txt/events.txt

Text file containing 'events' entries. Starting with pl13, this file is built for you from files in the game/txt/evt directory. See game/txt/README for information.

game/txt/full.txt

Text file shown when a player tries to connect to the MUSH and the MUSH is full (at the player login limit)

game/txt/guest.txt

Text file shown to guests that log in. (post-1.50pl10)

game/txt/help.txt

Text file containing 'help' entries. Starting with pl13, this file is built for you from files in the game/txt/hlp directory. See game/txt/README for information.

game/txt/motd.txt

Text file shown to all players on connection.

game/txt/news.txt

Text file containing 'news' entries. Starting with pl13, this file is built for you from files in the game/txt/nws directory. See game/txt/README for information.

game/txt/newuser.txt

Text file shown when a player successfully creates a new character

game/txt/quit.txt

Text file shown when a player quits

game/txt/wizmotd.txt

Text file shown when an admin connects

Options explained

Options which are unclear or which deserve special mention are discussed in this section.

The EXTENDED_ANSI define turns on the ansi() function which allows players to use color and other ansi attributes in their messages. As the file notes, however, in order to protect non-ANSI players, if you use EXTENDED_ANSI, the game must filter every message output to players, and remove ansi characters from messages to non-ANSI players. This is a significant increase in CPU time required (since passing messages to players is what the MUSH spends a lot of time doing), but shouldn't be a problem for most modern machines that aren't heavily loaded.

FUNCTION_SIDE_EFFECTS are nifty, and make possible some very queue-light (albeit often CPU-intensive) code. They also make possible a lot of security problems. In general, if your coders aren't demanding these, avoid them.

PLAYER_NAME_SPACES works fine in post-1.50pl10 releases, but has some small (but annoying) bugs in releases up to 1.50pl10. If you use this, remind your players that names with spaces should always be enclosed in quotes, like "Paul Atreides".

The DBCOMP option offers essentially a tradeoff between disk usage and speed of MUSH startups and dumps. If you define DBCOMP, the MUSH will pipe its dump through a compression program of your choice (usually "compress" or "gzip"), resulting in a smaller db file and a slower dump (and restart, when it first reads the db). Compress is usually faster than gzip, but gzip gives better compression. If you have the disk to burn, I personally recommend not using DBCOMP at all, just to reduce baggage.

The NO_FORK option prevents the MUSH from forking when it dumps. Details about this are in the MUSH management section on dumps. If you define it, be sure you define a DUMP_NOFORK_MESSAGE to show players. If you don't define NO_FORK, you can choose to have the MUSH use vfork() instead of fork(), but many many systems have broken vfork()'s, so it's rarely worth it - better not to fork at all.

If you're using a version before pl13, and your system doesn't have crypt(), you should define NOCRYPT, and you'll have to uncompress and hand-edit minimal.db.Z to replace the encrypted password to #1 with an unencrypted password of your choice. The password, by the way, is stored in the XYXXY attribute. pl13 and later versions can figure this out themselves.

While the SINGLE_LOGFILE option can save some file descriptors and possibly allow more players to log in to your MUSH, it should be avoided in general as it makes dealing with your MUSH's error, warning, and other output more difficult. However, if you do want to use it, you can often separate out the individual components by using the 'grep' command and searching for NET, RPT, ERR, WIZ, or LOG.

You can set CHAT_SYSTEM to 0 (no chat), 3 (the original MUSH chat system), or 4 (the extended MUSH chat system, which doesn't require server hacking in order to preserve channels across shutdowns). If you're using an old version of PennMUSH (1.50pl10 or earlier), the MUSH can't automatically convert databases to add and remove chat channels; to add chat channels to such a database (which includes minimal.db) you must set CHAT_SYSTEM to 2, load the database, @shutdown, and recompile the MUSH with CHAT_SYSTEM set to 3 (the db has chat, and you want to use it) or, if you're feeling silly, 1 (the db has chat, but don't use it.)

As options.h says, defining MEM_CHECK allows you to test for memory leaks if you know what you're doing. When MEM_CHECK is defined, a count is kept of each memory allocation of various types which is incremented when more memory is allocated and decremented when memory is freed. You can see the list of active (allocated) memory counters by logging in as #1 and typing @stat. If an allocation from a certain function builds up and never decreases, the function may be leaking memory and you can examine it. Rhyanna provides more detailed information about how to use MEM_CHECK. Leave MEM_CHECK undefined for a normally running MUSH, as it's more efficient without.

BOOLEXP_DEBUGGING does not appear to function. Don't define it.

The DEBUG define adds info to the log file whenever a block of text that's been created to send to a player's socket (in bsd.c) is freed. If you're using smalloc.c, this also causes smalloc to try to verify the free-memory table and report the results when #1 does an @stat.

One day I'll have a working port concentrator again (I once had the old one hacked up to work right under SunOS, but not Ultrix, when I lost the code.) Until then, you can't define CONCENTRATOR unless you want to hack it into shape yourself. That requires getting a copy of conc.c and bsdconc.c from PennMUSH 1.50 pl4 or before.

Always define LOCKOUT and WCREAT. There's no reason not to, and the added security is well worth it. If you want everybody on registration status, you can just define WCREAT (and not LOCKOUT), but defining both gives you maximum flexibility.

For discussion of LOGIN_LIMIT, see the section in MUSH management on file descriptors and login limits.

Always define INHERIT_FLAG - it increases security greatly.

Many people misunderstand the ADD_NO_COMMAND_FLAG. In pl10, the flag no_command prevents an object from being check for $commands. This can improve the server's efficiency, and you get this flag no matter how you define ADD_NO_COMMAND_FLAG. What defining it does is cause all rooms and players in your database to be set no_command whenever you restart the MUSH. This is fine if you're converting an older database over, but not what you want if you're starting up from minimal.db, since any time someone chooses to make themselves (or a room) !no_command, the server will change it back to no_command next restart if this is defined. (What you *do* want to do, however, is arrange for all newly created rooms and players to be set no_command, which is handled in the mush.cnf file.)

Before pl10, the old method of dealing with newlines discussed in the OLD_NEWLINES define was not to allow \n's in attributes in the database (a \n was considered to mark the end of an attrib.) The current method still uses \n to end attributes, but allows \r\n's (carriage-return/linefeed, which appears as ^M in editors) to appear in attribs, since \r\n is what %r translates to.

The later #defines are less important constants, and generally you can follow the comments.

Making PennMUSH (post-pl10)

1. Type 'sh Configure' to autobuild a Makefile
2. Either:
   • Copy options.h.dist to option.h and edit it
   • Copy dune.h.dist to dune.h and edit it
3. Or (pl13 and later):
   • Do a 'make update' which will walk you interactively through all the options. Even better, if you're upgrading to a new patchlevel, copy your old options.h and dune.h to your new directory, and then 'make update' - your old settings will be read and incorporated into a new options.h/dune.h. You'll be prompted for new options.
4. Edit src/Makefile and select MALLOC, RWHO, and IDENT options. Information is in src/Makefile, or read the next section.
5. Do a 'make install' to build the files and set up symbolic links
6. Do a 'make customize' (pl12 and later) if you want to customize a directory for your mush (very handy if you run multiple MUSHes). This requires perl. For example, if you customize for 'mymush', a duplicate game/ subdirectory called mymush/ will be created, containing mymush.restart and mymush.cnf already set up correctly. The databases will be named indb.mymush.Z, outdb.mymush.Z, and maildb.mymush.Z, and will live in mymush/data.

Making PennMUSH - pl10 and earlier

Copy the Makefile.dist to Makefile, and edit it, following the instructions for specific systems. If you have gcc available, it's highly recommended as the compiler, as it allows you to use both -g (debugging) and -O (optimizing) flags together. If not, I strongly advise that you use your compiler's debugging flag (-g, typically) rather than the optimizing (-O) flag, so that when your MUSH crashes (and it will sooner or later :), you can determine where the problem lies.

The malloc options are not very well-detailed in the makefile. "Malloc" (memory allocation) is the function which is used when a program wants to get some memory from the operating system. It's a function which is built into all Unix operating systems, but is often inefficient and sometimes buggy. Therefore, MUSH allows you to use one of two alternate malloc packages which do more efficient memory allocation (typically by asking the system malloc for big huge chunks now and then, and then managing the doling out and recovery of memory from those chunks itself). I've used both smalloc and gmalloc successfully on Sun and Dec systems - try both and see which performs better for you. That may change as you MUSH grows. Some odder systems (NeXT, in particular) won't behave well with either of these, and require the system malloc.

If you use smalloc, you might as well define SLOW_STATISTICS, too. If you use gmalloc, and your system has the getpagesize() function, you may want to add -DHAVE_GETPAGESIZE to the SYSDEFS in the Makefile, since gmalloc only detects this function correctly if your system defines BSD, which at least Ultrix 4.2 doesn't. To build pl10 PennMUSH, type 'make install'. People often just 'make' and forget the install step, but it creates crucial symbolic links, so do it!

Troubleshooting

If you need outside help, you could post your problem on the rec.games.mud.admin newsgroup. If you do, be sure you include complete information about the hardware, operating system, compiler used, options set in the makefile, etc. It's a good idea to include a copy of the make error. You can save a copy of your make output by using a command like:

    make |& tee make.log        (csh, tcsh, etc)
    make 2>&1 | tee make.log        (sh, ksh, bash, etc)

    script make.log
    make
    (type 'exit' or ctrl-D to stop logging to the file)

Starting up

Contents:

• The game directory
• The .cnf file
• The restart script
• The txt/*.txt files, @readcache, and mkindx
• Minimal.db and first startup
• Troubleshooting

The game directory

The MUSH game subdirectory contains the following files and directories:

mush.cnf

The config file for your mush (make a copy of this using the name of your mush, e.g., dune.cnf)

restart

The restart script for starting up the MUSH

maildb(.Z)

The @mail database - created at first startup

data/

Directory containing your game's database(s)

save/

Directory for old game databases

txt/

Directory for .txt files (help, events, news, and various message files)

log/

Directory for MUSH log files

The .cnf file

In PennMUSH versions up to pl10, you must shutdown and restart the MUSH for changes to take effect. The non-obvious options you can set in the .cnf file are:

input_database

The location of the input database the MUSH should read from. If you have DBCOMP defined, this is usually data/indb.Z or data/indb.gz, otherwise data/indb. If you've used 'make customize', this will have a name like data/indb.mushname.Z

output_database

The output database. As above, with DBCOMP, usually data/outdb.Z, or data/outgb.gz, otherwise data/outdb. If you've used 'make customize', this will have a name like data/outdb.mushname.Z

crash_database

Panic databases are never compressed. Keep the default data/PANIC.db

mail_database

As above, this is where the mail database is located. With DBCOMP, maildb.Z (or .gz) is the default. Without, use maildb. Actually, there's an argument to be made for using data/maildb.Z and thus keeping all your databases together in the data subdirectory, rather than having maildb's cluttering your game directory. If you've used 'make customize', this will have a name like data/maildb.mushname.Z

compress_program

What program to use for compression, usually compress or gzip. Be sure this program is somewhere on your path.

uncompress_program

What program to use for uncompression, usually uncompress or gunzip.

player_start

This is the room number where newly created players connect to. It defaults to 0, but you will probably want to change it for a non-social MUSH, since #0 is always a good building nexus (because rooms which can be reached from #0 are "connected" and don't give the owner the disconnected room message).

master_room

If DO_GLOBALS is defined, then the Master Room's exits are global throughout the MUSH, and any $commands on objects in the Master Room are global. By default, this is room 2, which comes with minimal.db.

dump_interval

The time in seconds between MUSH checkpoint dumps. For reference, 3600 seconds is an hour, 7200 = 2 hours, 10800 = 3 hours, 14400 = 4 hours, 21600 = 6 hours, 28800 = 8 hours, and 43200 = 12 hours. If you don't do dumps at least every 12 hours, you're playing with fire. If you do any kind of development or hacking on your MUSH, dump at least every 3 hours.

max_logins

This is where you set the maximum number of players who can log in, if you have LOGIN_LIMITS defined. See the section on file descriptors and login limits for more information.

player_queue_limit

Mess with the default of 100 at your risk. If this number is too low, players won't be able to queue enough commands to make some of their objects work. If it's too high, runaway objects may eat up too much queue space and lag your MUSH. This makes you vulnerable to a denial of service attack by a twink as well as to coder mistakes.

queue_chunk

When the MUSH is not processing input from the net, it takes some commands off the queue and runs them. This parameter controls how many commands are run. The higher the number, the less your queue will build up, but the slower the game's net response will be. The default of 3 is usually fine, since by the time the queue's a serious issue, there's often nearly constant net activity anyway. See below.

active_queue_chunk

When there is net activity, the MUSH still can take some commands off the queue for processing. By default, it takes off a single command, giving the queue the same priority as a single player. If you get a lot of players and find your queue building up unacceptable, raising this (start by raising it to 2) can reduce queue build-up (and therefore queue lag) at the expense of slower command response. It's a tradeoff, but it often pays when there's a slew of players and queued commands.

function_recursion_limit

Mucking with this can allow code to waste CPU by recursing (calling itself) too many times. Encourage your coders not to write recursive code, and keep this at the default of 50.

function_invocation_limit

The maximum number of functions that can be invoked in a single command. This can be a hassle if you try to do some kind of @dolist on all the objects in your database, but it pays to keep it down to the default of 2500.

rwho_*

The values for the rwho parameters can be obtained by emailing jds@moebius.math.okstate.edu and asking for an RWHO password, as discussed in the README file.

log_*

These parameters control what the MUSH will log. log_commands and log_huhs will both produce huge spammy logs - don't use them unless you're trying to identify what command is causing a crash or something. I recommend log_forces for security reasons unless you have a global which does a lot of @forcing (like some versions of Dynamic Space). I don't use log_walls, myself, but if you like to watch your wizards, you could. These can also be turned on and off with @enable/@disable, as can logins and daytime.

daytime

The "computationally expensive" commands are: @find, @entrances, @mail/stats, @search, and the lsearch() function.

room_flags, player_flags, exit_flags, thing_flags

These very handle parameters allow you to set up flags which should be automatically set on any object of a given type that's created on the MUSH. Having rooms and players (and possibly things) start out no_command is a good way to save CPU time that would be spent searching things for $commands. Starting players enter_ok makes a lot of sense. Some MUSHes may want to start exits transparent or players opaque or whatever. On DuneMUSH, we had a flag called "unregistered", and players started with this flag set, allowing us to do on-line registration.

The restart script

1. Sets some variables to use later. You must define GAMEDIR to point to your game directory and CONF_FILE to point to your .cnf filename. If you've used 'make customize' these will be set for you.
2. Scans your .cnf file and figures out the name of your incoming and outgoing databases, and the compression scheme you use.
3. The "mush" variable is set to 2 if there's already a MUSH running, or 1 otherwise, by using a tricky little ps/egrep command line. If you run multiple MUSHes, change the line to check for the full name of the conf file of this mush, rather than just the string "conf" (again, 'make customize' does this automatically.) If the MUSH is already running, restart reports that, and quits.
4. The help.txt, news.txt, and events.txt files are re-mkindx'd. In pl13, this is handled by running a 'make' in the txt directory.
5. If there's a PANIC.db, and it's complete (i.e., the game was able to finish the whole panic dump), we turn it into an outdb.
6. All the log files are erased. You may want to change the script to preserve some of these.
7. Tries to find a database to start up, in this order:
   • If there's an outdb, indb is moved to save/indb.old, and outdb is moved to indb.
   • If not, and if there's an indb, we use that.
   • If not, and if there's a save/indb.old, copy that to indb and use that.
   • Finally, if we can find minimal.db.Z, we'll use that.
8. The MUSH is run.

The txt/*.txt files, @readcache, and mkindx

Cached text files

connect.txt

The connection screen. This file should give the name of the MUSH (and usually the source code version), an email address for the God or contact person, and character connection/creation information. It should also include the "Type WHO to see who is currently connected" line that's in the default connect.txt - MUSH clients like tinyfugue use this line to detect when to start displaying text when they're doing quiet logins.

quit.txt

Shown to players when they QUIT or LOGOUT

down.txt

Shown to players when logins are @disabled (i.e., when only admin can log in). Often unused in favor of @motd/nologin, which doesn't require site access.

newuser.txt

Shown to players when they create a new character.

motd.txt

Shown to players after they've connected to their character. Often unused in favor of @motd, which doesn't require site access.

wizmotd.txt

Shown to admin when they connect. Often unused in favor of @motd/wiz, which doesn't require site access.

Indexed text files

In pl13 and later versions, the help.txt, news.txt, and events.txt files themselves should not be edited, because they are built from files residing in the txt/help, txt/news, and txt/events directories. This allows you to keep your local help files separate from those distributed with PennMUSH, and to manage them as a set of files rather than a single large file.

Here's how it works:

1. The source files for help.txt, news.txt, and events.txt are kept in directories called help, news, and events respectively.
2. Files in those directories which end in .<directoryname> are considered to be part of the text. That is, files in help/ which end in .help, and files in news/ which end in .news will be merged into the final help.txt, news.txt, or whatever.
3. When the MUSH is restarted, a 'make' is run in this directory. For if a file in help/ is newer than help.txt, it calls compose.csh to rebuild help.txt. If you've got perl on your system, compose.csh will also call index-files.pl to make a 'help index' entry which lists all your help entries.

The directions which follow about formatting these files still applies to the files in the help/, news/, etc. subdirectories.

The format for the indexed text files is a topic line (or set of lines) followed by the text of the topic. Topic lines begin with "&". The topic "& help" (usually first in each file) is shown if the player types "help", "news", or "events" without any topic.

Topic names with themselves beging with an & denote admin help or news topics, accessible with the ahelp or anews commands.

Here's what a piece of a news file might look like:

& rpg           <-- note that both topics will work for this entry
& game
You've typed 'news rpg' or 'news game'.
This is the player information for the role-playing game...

& &rpg
You've typed 'anews rpg', and you must be an admin.
This is the admin information for the role-playing game.

Minimal.db and first startup

To monitor the restart, type: "tail -f log/netmush.log", which will show you the progress of the startup. When it reaches "MUSH startup completed" (or an error message!), hit ctrl-C to kill the tail process. (If you got an error, see Troubleshooting, below).

In general, you can check to see if the mush is running by using "ps -ux" (on BSD systems) or "ps -lf" (on SysV systems), and looking for the process named "netmush" or "netmud".

Assuming you've succeeded in getting the MUSH up and running on your chosen port, here are some things you should do immediately:

1. Log in as One (password 'one') and change One's password. (Many people also rename One to God or some other appropriate name). This is very important, as #1 is the only player which can confer wizbits on other players, and needs to be protected. @dig a floating room for God to live in, and @tel and @link #1 there.
2. Make a wizard character for yourself. You can do it while logged into #1 by using @pcreate name=password, @set *name=wizard. Once you've done this, you can log out of #1 and into your wizard character. You'll need #1 later, but it's best not to use God unless necessary.
3. Create some guest characters, if you like. You can do this with @pcreate as above, and @power *name=guest. I typically use the following kind of code:

   @dol Guest Guest2 Guest3 <etc> = 
   	{@pcreate ##=guest; @power *##=guest;
   	 @lock *##=##; @elock *##=##; @desc *##=A guest. Be kind.;
   	 @atrlock *##/describe=on}
   

4. If you're bringing up minimal.db, and you had CHAT_SYSTEM defined as 2, do an @shutdown, recompile the MUSH with CHAT_SYSTEM defined as 3, and restart again.

Troubleshooting

The MUSH crashes

Problems loading minimal.db

Bad character 0 on object 0
Bad attribute list object 0

The minimal.db distributed with pl10 already has the @power field added, and should not be run with ADD_POWERS defined. ADD_POWERS adds the @power field to older dbs.

If you have DBCOMP defined, be sure that minimal.db is appropriately compressed or gzip'd, depending on how you have the compression_program defined in mush.cnf. If you don't use DBCOMP, be sure that your startup db isn't compressed. :)

In some cases, the problem might also be that the symbolic link from hdrs/dune.h to dune.h in the top-level directory (or from hdrs/options.h to options.h in the top-level directory) has been broken. In that case, you'll want to do something like this:

cd hdrs
rm dune.h options.h
ln -s ../dune.h dune.h
ln -s ../options.h options.h
cd ..
make

Problems loading your db

1. MAKE A BACKUP OF THE DB! Do this every time. It's very very easy to make a mistake. I put mine in game/save, with names like indb.(date).corrupt
2. If your db is compressed, uncompress it.
3. Load your db into your favorite editor. Some editors can not handle some db's, usually because the lines of text in the db are too long for the editor's buffer (Sun's vi can have this problem), and sometimes because the db itself is too large (20Mb is a big file :). GNU emacs version 19 works pretty reliably. If the problem is the size of the file as a whole (not line length), you can use the unix 'split' (split indb) command to split up the db into 5000-line chunks which you can paste back together when you're done using 'cat x?? > indb.new'.
4. Find the offending object. The beginnings of objects are indicated by lines which start with !object# (for example, "!512"). The next set of lines which contain numbers represent the object's type, flags, powers, chat channels, locks, etc.
5. If you're lucky enough to know the attribute on the object that's causing your trouble, you can find it. Attributes start with a "]" symbol (for example: "]STARTUP"). If you just know the bad character, start searching for that character in the object. The attribute name is followed by some owner and flag information (separated by ^'s) and then on the next line, the text of the attribute itself, which is a single line but may contain literal carriage returns (^M's).
6. When you find the problem character, try to fix it. The most reliable fix tends to be deleting that attribute (the ]attrib line, and the line following it which contains the character), but if you see something strange (control characters besides ^M, hard returns in attributes, etc.) you could try just fixing that and see if it helps.
7. Quit the editor, saving the new db, recompress it if necessary, and try starting up under it. Repeat as above until it works. :P

MUSH Management

Contents

• Using #1
• Dumps, shutdowns, db corruption, and paranoia
• File descriptors and login limits
• Wizard commands in detail
• MUSH crashes
• Lagging
• Security
• Making Guests
• Everyday stuff
• Useful globals
• Miscellany

Using #1

Making wizards

Malloc stats

@startup for @functions

Schmidt@Dune (and elsewhere) developed this code for #1's startup to make automatic @function setup easier:

@STARTUP #1=@dolist lattr(#191/FN_*)=@function [after(##,FN_)]=#191,##

Miscellany

• Only God can use the @poor and @allquota commands.
• Only God can use @log/wipe to erase a game log, and this additionally requires the password for the game account.
• God may @chown a player, which should only be used if, due to some corruption, a player ends up not owning themselves. God can also @boot players who the game lists as not connected. Don't do it.
• God can @wipe wizard-only attributes on things. Even wizards can not (using @wipe - they can clear them manually).
• Only God may @set, @edit, @tel, @force, or @trigger God.
• In the post-pl10 extended mailer, only God can do @mail/nuke and wipe all @mail. And only God may use the mail() function to read other players' @mail.
• In the post-pl10 releases, God may change a player's name (using @name) without giving the player's password.

Shutdowns, dumps, and paranoia

What's a dump?

What's a forking dump?

There's a downside, however. When the MUSH forks, there are basically two MUSH processes running. That means durnig the dump, your MUSH is using twice the CPU (roughly) and twice the memory that it normally would. Unless your machine has a lot of memory (or your MUSH is very small), this can cause the MUSH to swap, and lag everyone badly.

The alternative is to dump without forking. While the MUSH is dumping, it can do nothing else in this case, so the game will pause until the dump is complete. It gives the players a message to let them know that there will be a pause.

What happens on a shutdown dump?

What's a paranoid dump?

What exactly does a paranoid dump try to fix?

• Bad attribute names: Unprintable characters or spaces in names of attributes will be replaced with a '!' character.
• Bad attribute owners: If the attribute is owned by an invalid db#, its owner will be set to God.
• Bad attribute text: If the attribute's text contains unprintable characters or hard newlines (\r's and \n's), they will be replaced with '!' characters. The fixing of hard newlines used to be important, but is actually now more of a hassle since MUSH can now deal with \r\n's in dbs.

What's a panic dump?

File descriptors and login limits

The operating system

Most operating systems have limits on how many file descriptors a user's process can open. Some typical limits are 64, 128, or 256. Sometimes there will be a 'soft limit', which is lower than the maximum, and which you can increase (via the 'unlimit' command in the csh) up to the 'hard limit', or system maximum. The hard limit can only be raised by the system adminstrator recompiling the system's kernel. This is not too bad to do under SunOS 4.1.x (NOFILE in sys/param.h), Ultrix 4.2 and later (NOFILE in h/param.h and max_nofile in conf/{mips,vax}/param.c), and Linux, where you always have kernel source. Note: SunOS 4.1.x systems have (by default) a limit of 256 descriptors, but there's a bug in the stdio code which prevents descriptors after the first 128 from working correctly. :(

When you run out of descriptors and the MUSH tries to open another one, it will likely either crash or hang. Since the MUSH requires about 10 descriptors for itself (6 if you define SINGLE_LOGFILE), subtract that from the hard limit to figure out how many players you can support.

CPU/memory/network bandwidth

Setting login limits

Wizard commands in detail

@comment

The COMMENT attrib can't be seen by mortals, so using @comment to set comments on suspicious players is a common thing to do. To maximize usefulness, consider a policy whereby whenever a player is set suspect, they must be commented, and comments must include the name of the commenting Wizard. If you let any admin set SUSPECT, consider a +suspect player=comment command which sets the flag and the comment at the same time.

@disable/@enable

The options which you can enable and disable are: logins (when disabled, only admin/login-@power can log in), daytime (when enabled, cpu-intensive commands can't be used), command_log (when enabled, all commands are logged), force_log (when enabled, all @forces are logged), huh_log (when enabled, all commands resulting in Huh? are logged), wall_log (when enabled, all @walls and @wizwalls are logged).

@fixdb

This very dangerous command allows you to directly set the contents, location, exits, and next elements of a database object. No error-checking is performed, so be sure you know what you're doing. To learn more about these elements, read the source code and play around with the examine/debug command which displays values from a db object's structure which are not normally accessible in raw form.

@kick

As the help says, @kick causes the immediate execution of a specified number of commands from the queue. The real question is when to use it. It can help if your queue is clogged with a non-infinite loop, like a large @dolist. But what often happens is that while the game is busy executing the @kicked commands, commands from connected players are building up, resulting in a large queue clog even after the @kick. I use it as a last resort, and rarely when many players are connected.

@log

This works just like the help says it does, and is really handy if you want to keep track of things (like when players die by your combat system or use certain commands). The alternative, logging such things to some db object, has all sorts of problems as the log gets bigger and bigger. If you use @log, classify everything you log with some unique KEYWORD so you can get it from your logs with a simple grep. I used to have an object which would @log the number of connected players and admin, and how many were IC, every 30 minutes, and I'd make histograms out of the data in the log. :)

@pcreate

This is how you create characters for people from sites on registration status.

@readcache

Don't forget to run this command if you change the cached .txt files and want to update them (or, in the post-pl10 releases, kill -HUP the MUSH).

@sitelock site-pattern[= options]

Adds the site-pattern directly to the access.cnf file with the specified options. Wizards can use this to lock out sites. Later uses of @sitelock override earlier ones.

@squota

In the post-pl10 releases, you can @squota player=+number or -number, to adjust their quota up or down from its current level.

@uptime

On some operating systems, this command's functionality is limited. On others, the command works, but seriously lags the MUSH while it's working. Test it once and see.

@toad

I'm a fan of disabling this. Wizards shouldn't nuke players, they should boot and newpassword (and maybe sitelock), all of which are reversible. Only God should nuke players, and God should be secure enough to do it with the simple @nuke, not the flashy @toad (which leaves a slimy toad you often nuke anyway). Rhyanna@Castle D'Image notes, however, that @toad can be a convenient way for RP MUSHes to make corpses after IC deaths.

MUSH crashes

In order to get debugging information, your MUSH crash must have produced a core dump, which is a file called 'core' in your game directory. This file is usually quite large. On some systems, you must be sure that your MUSH restart script does an 'unlimit coredumpsize' or you won't get complete core files.

You also need a debugger. Most systems have one of the following debugging programs: gdb (ideal), dbx (a good second choice), sdb (ick), adb (very ick). You (or your sysadmin) can ftp the source code for gdb from the GNU ftp site.

Using the gdb or dbx debugger

To run the debugger, go into your source directory and type:

gdb netmud game/core

The debugger will tell you how the process died, and what function it was executing at the time.

Getting and using a stack trace

The command 'where' will print out a stack trace. The commands 'up' and 'down' will walk you up and down through the stack, showing the values of parameters that are being passed. You can also use the 'p' (print) command to print the values of other variables in each function.

Running the MUSH under gdb

    gdb netmush
    run mush.cnf

When the MUSH crashes, you'll be told how and where, and be returned to gdb to analyze the crash. Gdb and dbx can do much more - you can tell them to run the MUSH until they hit a certain function and then wait for further instructions, step through code one line at a time, etc. Read the manual pages if you need to do these things.

Trashed stacks

Lagging

Network lag

The characteristic property of netlag is that you won't experience it if you're connecting to the MUSH from the MUSH machine itself. If you can get a lagless connection by doing a 'telnet localhost <port#>', netlag is responsible.

If your host has the ping command (most do), you can test how long it takes a packet to travel between your host and another machine, and try to identify how slow things are going to be. If you happen to have the traceroute command, you can see exactly where (between which routers) the network is lagged.

Unless you happen to be a network administrator of the problem stretch of network (or if it's just the local connection to your machine), there's not much you can do. If the problem is your particular net connection, you can probably spend more money and get one with a higher bandwidth, or reduce other things your machine does that requires the net (email, etc.), but neither of these are really worth it for a MUSH, usually. :(

DNS and IDENT lag

Some hosts, however, have very slow nameservers. Sometimes this is because the nameservers are behind slow internet connections with heavy traffic. The MUSH stops while a reverse hostname lookup is going on, so if it takes more than a second, you will feel lag.

If you've got your MUSH configured to use IDENT lookups, the same kind of problem applies. In addition, IDENT lookups of non-unix systems can hang until the lookup times out.

There are a few ways you might deal with this problem:

• Turn off ident or reduce the ident_timeout value in mush.cnf
• If you don't need hostnames, set use_dns to "no" in mush.cnf (PennMUSH 1.6.x) and no reverse hostname lookups will be performed.
• If there are particular sites that are causing you trouble, and if you have access to your system's hosts file (/etc/hosts on most Unix systems), you could try making an entry for the troublesome system in the hosts file. Many DNS setups will check the hosts file before asking the nameserver.

CPU lag

You can examine the CPU load in a few ways. The uptime command will display an interesting, if non-objective statistic called "load average", measured over the last minute, 5 minutes, and 15 minutes. If you know what typical load average looks like, you'll be able to recognize abnormally high load. Loads over 3, especially in the 5/15 minute entries, tend to make for a slow game.

But what's causing the load? Here you can use ps -aux (BSD) or ps -elf (SysV) to see all the running processes and how much CPU time they're getting at that moment. This static picture can be deceiving, but is a good start. Read the man page for details.

If you're responsible for the load due to your own compiling and such (or if you need to decrease the CPU load your MUSH puts on the machine), read the man page for the nice and renice commands, which let you tell the system that your compilation (or MUSH process) should be nice about using CPU, and the CPU should give it lower priority.

Disk swapping

MUSHes can be pretty big programs, though, and sometimes another program (some compilers and editors, as well as statistical software and other such things, for example) has to be granted more memory than can be recovered even with paging. In these situations, the whole MUSH process may be "swapped out" to the disk, temporarily put on hold until it can be swapped back into memory. While the MUSH is swapped out, the game is frozen, and if it stays swapped long enough and often enough, you experience lag.

Dealing with swapping and paging is beyond the scope of this guide. Read the man pages for ps, vmstat, pstat, and iostat, or pick up a book on Unix System Administration or Performance Tuning (say, the O'Reilly Handbooks, which are great) if you're the system administrator of your MUSH machine. If not, purge unused objects from your database and hope.

Queue lag

@kick can be used as a temporary fix for this, though see the concerns above in the section on Wizcommands. A more permanent solution might be to adjust the values of queue_chunk and (especially) active_queue_chunk in the mush.cnf file. This will make keyboard response slighly worse, but will usually fix the queue clogging.

Security

Stable service

Players should be able to play the game - it should be up reliably.

Database control

Players should not be able to modify objects belonging to other players.

Privacy

Private player information (email addresses, sites, private conversations) should be inaccessible by unprivileged players.

Freedom from harassment

Players should be free of harassment from other players (gross spamming, for example.)

A fair game

Players should not be able to use MUSH knowledge to cheat in any game run on the MUSH, particularly if the game is the point of the MUSH.

A cracker philosophy

These folks not only put your game and database at risk, not only might become privy to sensitive information (player email addresses, etc), but destroy the trust which generally exists within the internet and MUSH community. It's no service.

Unfortunately, the crackers usually win, because they have a lot of time to spend trying to compromise your security, while you and your Wizards have more to do than just continually improve it. The goal here, therefore, is to emphasis some easy measures that you can take to deal with attacks on your MUSH.

A twink philosophy

SUSPECTs

There's a script by Talek in the Appendix which I've used to process command.log and create individual suspect files, one per player (by db#), which can be read or searched for keywords like "hack" or whatnot.

By the way, I think it's good policy for every MUSH to place a statement in news ('news policy' perhaps) noting that while every attempt is made to preserve privacy, you reserve the right to log commands executed in order to maintain MUSH security and/or to fix bugs.

Registration and lockout

You can control the following aspects of access:

• Whether or not a site can connect to guests
• Whether or not a site can connect to non-guest characters
• Whether or not a site can create characters at the login screen
• Whether or not a site can use the "register" command at the login screen, to request that a character be created and its password be emailed to the player.
• Whether or not a site is suspect. Players who connect from suspect sites are automatically set SUSPECT.
• Which of the above your Wizards can override using @sitelock, and which are set in stone.

A line in the file looks like this:

   [  ...] [# Comment]

A host which does not match any line in the file is allowed complete access. A host which matches a line with no options listed is banned completely; connections will dropped before the login screen.

There is also a special line in the file:

  @sitelock

The available options include:

create

allow players from this site to use the 'create' command

!create

don't allow players from this site to use the 'create' command

connect

allow players from this site to connect to non-guest characters

!connect

don't allow players from this site to connect to non-guest characters

guest

allow players from this site to connect to guests

!guest

don't allow players from this site to connect to guests.

register

enable the 'register' command at the connection screen. Players may type 'register ' to create a new character and have its (randomly generated) password emailed to the player. Note that this does not disable 'create', so you'll probably want to use this option along with the !create option.

suspect

cause all players connecting from this site to be set SUSPECT. Unless you want SUSPECT guests, you'll probably want to include !guest as well.

The @sitelock command sets the optional comment to inform you of who performed the @sitelock and when.

access.cnf is re-read when the MUSH receives a HUP signal. It is updated whenever someone uses @sitelock.

The file game/access.README contains examples of using access.cnf to enforce a variety of different access control policies.

Gagging, booting, guesting, newpasswording and nuking

The GAG flag

Prevents the player from speaking, a handy response to spammers and those who page obscenities.

The Guest power

Restricts a number of commands players can use, especially if you're running the post-pl10 releases with HARSH_GUEST defined, in which case they can't do any building or attribute-setting.

The FIXED flag

In the post-pl10 releases, this flag prevents the player from using the @tel and home commands. Handy if they keep @tel'ing where they're not wanted.

@boot

Disconnects the player from the MUSH. Nothing, of course, prevents them from reconnecting, unless you lock their site or install a global @aconnect to listen for them connecting and boot them again.

@newpassword

Changes a player's password. This is the proper way for non-Gods to "nuke" a player, as it doesn't actually result in any data loss, and can be reversed if the twink makes amends. This does no good against twinks who are just creating scratch characters they don't care about. In the post-pl10 releases, God can also re-name a player without knowing/changing their password, which can have similar effects.

@nuke

This is how God cleans players from the database. It's also an appropriate response (along with a sitelock) against crackers.

Coded attacks on the MUSH (privacy, denial of service)

Admin passwords must be protected. A cracker who can log in as a Wizard can destroy your database in one command.

Players should not be given wizard-bitted objects if at all possible. Wizard-bitted global commands should be carefully checked for security. One important check is to try calling the command with arguments like "[set(me,visual)]" and "\[set(me,visual)\]" - if the function results in the wizobject becoming visual, it's not secure! (And Wizard globals shouldn't be visual anyway, just in case.) Best is if you can run without FUNCTION_SIDE_EFFECTS.

Be very careful of zones. My policy is that nothing owned by an admin should ever be zoned to a ZMO which has non-admin on the elock. Instead, it should be @chowned to a mortal builder-character and then zoned. You can find ZMO's without elocks by logging in as a mortal and running an @find to see what you control.

In the worst-case scenario, if you somehow lost your entire database, you'd still be okay if you've been making backups of your database every now and then (how often and how many depend on your disk space.) Always have at least one working backup somewhere. And chmod a=r it, too, so you don't accidentally overwrite it! If you really want disaster-recovery, you should keep a database backup on another machine as well, in case your host should crash.

Making Guests

Post-pl10 PennMUSHes can have as many Guest characters as you see fit. Each guest should be set @power Guest. When a player logs into a Guest-@powered character, the following happens:

1. If there's no one else connected to that Guest, the player is connected.
2. Otherwise, the server searches through the database for another Guest-powered character which isn't in use. If it finds one, the player is connected to that Guest.
3. Otherwise, the server gives up, and connects the player to the original Guest (resulting in multiple players controlling one character)

PennMUSH pl10 supports setting the Guest power on multiple players, but doesn't do the autoconnection trick. Pl9 and earlier allow only a single Guest, whose db# is specified in the mush.cnf file.

Everyday stuff

@stat

@uptime

Keep an eye on max res mem, to get a feel for how it grows as your MUSH does.

Player purges

/def nuke = @switch hasflag(pmatch(%1),connected)=1,{think %1 is 
connected!}, {@dol lsearch(%1,none,none)=@nuke ##} 

Then, I define a player purge macro like this:

/def ppurge = @dol lsearch(all,type,player)=@switch 
[and(not(orflags(##,Wr)),lt(convtime(xget(##,last)),sub(convtime(time()),
2419200)))]=1, {think /nuke [name(##)] ## [lstats(##)] }

Actually doing a purge, then, requires these steps:

1. /log purge, to start logging output to a file called 'purge'
2. /ppurge, to list players who are candidates for purging
3. /log off, to stop logging
4. /sh vi purge, to edit the purge file and see who'll be purged. Delete lines in the file for players who you don't want to see purged. What's left will be a list of /nuke lines which will purge the players you want purged.
5. /quote 'purge, to load the commands in the purge file and do the actual purging.
6. /sh rm purge, to remove the purge file

Useful globals

The motd-maintainer

Instead of directly setting the motd's with @motd, Wizards should set the motd's as attributes on this object (&MOTD, &WIZMOTD, &NOLOGINMOTD), and then type 'setmotd', which will post them via @motd. If the game is shut down, the attribs will continue to store the motd's, and on restart, the motd's will be reposted via the object's @startup code. This code actually builds the motd out of any attribs starting with MOTD, so you can maintain a set of motd's more easily.

Here's the important code:

@create MOTD Device
@link MOTD Device = #2
@lock/use MOTD Device = iswizard/1
@set MOTD Device = STARTUP
@set MOTD Device = !NO_COMMAND
@set MOTD Device = SAFE
@set MOTD Device = WIZARD
&DO_SETMOTD MOTD Device=$setmotd:@tr me/U_SETMOTD=%#
&U_SETMOTD MOTD Device=@motd [iter(sort(lattr(me/MOTD*)),%r[eval(me,##)])];@wizmotd [eval(me,WIZMOTD)];@pemit %0=MOTD's set.
@STARTUP MOTD Device=@tr me/U_SETMOTD
&ISWIZARD MOTD Device=[hasflag(%#,W)]
@DESCRIBE MOTD Device=Motd is stored in attributes of the form MOTD*. Type 'setmotd' to set the motd.
&MOTD-1 MOTD Device=First motd message
&MOTD-2 MOTD Device=Second motd message
&WIZMOTD MOTD Device=Admin motd message
@tel MOTD Device = #2

The MUSHclock (autoshutdown, announcements)

@create MUSHclock
@set MUSHclock = STARTUP
@set Announce = SAFE
@power MUSHclock = announce
&ANNOUNCEMENT MUSHclock = Your messages here
&ANNOUNCE MUSHclock=@switch [eval(me,announcement)]=,,{@wall [eval(me,announcement)]}
&LOOP MUSHclock = @tr me/announce; @wait 3600=@tr me/loop
@STARTUP MUSHclock=@wait [sub(3600,mod(secs(),3600))]=@tr me/loop

Miscellany

The port announcer (announce.c)

The distributed announce.c code, unfortunately, has a number of problems which keep it from running correctly in many cases, and may also cause it to crash. I use an alternative port announcer which works just great, called portmsg.c. Read the Appendix on Scripts and Programs for information about how to get portmsg.c.

When you've got it, compile the program with: cc (or gcc) -o announce announce.c

Run it with: portmsg textfile port#

You'll have to kill it by hand when you're done with it.

Hacking PennMUSH

Contents:

• When to hack
• Source code control, patches, and #ifdef
• How-to
  • Add flags
  • Add powers
  • Add chat channels
  • Add attributes
  • Add locks
  • Add functions
  • Add commands
• Upgrading to a new patchlevel
• The PennMUSH code style
• Miscellany

When to hack

I should probably insert here the standard cautions about not adding loads of feeping creatures ("feeps") and kludgy hacks to your MUSH, but I won't. Feeps are fun and usually harmless, and as long as you're happy with your code, don't let anyone tell you otherwise.

While there are no rules, then, there are a few guidelines I try to follow when deciding what *not* to hack:

• Avoid hacks which permanently alter the db or maildb structure, unless you know that you'll always be willing to support the code and cope with possible future PennMUSH upgrades, or if you don't care about ever upgrading. The sort of thing I'm talking about here is adding a couple new variables to the db structure. If you think your hack is of general interest, let me know and if I agree, you'll be assigned an official db-flag for your hack, and we'll arrange for built-in db conversion code to turn your changes on or off (the way USE_WARNINGS works, for example).
• Avoid hacks which require the MUSH to filter all outgoing text. EXTENDED_ANSI (and its relative ANSI_COLOR) is bad enough. While I've seen some beautiful commands like @wrap (which word-wraps output to players), each time you add a filter to all the MUSH's output, you significantly increase CPU requirements. Leave client-functions to clients, if possible.
• Avoid hacks with very limited functionality. If you've got spare time to hack, try to rewrite the chat system to improve its efficiency and give us more than 32 channels, or something.
• If the hack is something that seems very useful, email the idea and/or the source code (a context diff) to dunemush@mellers1.psych.berkeley.edu, the current PennMUSH maintainer (me). It may well appear in the next release!

Source code control, patches, and #ifdef

Source code control

1. Backups. Make a directory under your source directory called "oldsrc" or whatever, and put a copy of your source code into it. When you make changes, you can recover your old files from oldsrc, use it to produce patches, and eventually copy your new files into oldsrc when you're sure they work. Many people keep a "clean" source directory containing the original stock pl10 code, in case they need it. Of course, if you need to go back more than one revision, you're in trouble unless you clutter your disk with many many oldsrc directories. A variant of this strategy involves storing older versions as compressed tar files.
2. SCCS. SCCS (source code control system) is a more sophisticated way to manage source code. It stores changes from version to version in a subdirectory. You "check out" files to work on them, and "check in" files that you've hacked. You can revert to any revision at any time. This is good. Many major unix systems (Ultrix, SunOS, HP-UX) come with sccs installed. Read the man pages for info.
3. RCS. RCS (revision control system) is the GNU project's free replacement for SCCS, available from ftp.gnu.ai.mit.edu in /pub/gnu. The commands are different from SCCS, and some things are easier to do. RCS is standard with Linux. There's a front-end program by GNU called CVS, too. RCS can also be used to ease upgrading to a new patchlevel by preserving your hacks to the older patchlevel (details below).

When I start out with a new pennmush distribution, the first thing I do is to check in the entire source directory to RCS so I'll have a clean copy of the original distribution. I usually do it like this:

cp options.h.dist options.h
cp dune.h.dist dune.h
echo . | ci -n dist -l src/*.c hdrs/*.h

Applying patches with patch

Typically, if you receive a patch from a mailing list or newsgroup, you simply save it to a file, and, from within your source directory, type:

    patch < patchfile

When patch fails - reading context diffs by hand

• If the diff begins with the line "Prereq: <somestring>", then it means that in the file that follows, the string should be present within the first few lines, or the diff should not be applied. Patch checks for prerequisites to help insure that you're patching the right version of the source code.
• For each file in the diff, there are two header lines, which look like this:
  *** filename1 date1
  --- filename2 date2
  This indicates that the diff is the difference between filename1 and filename2, and should usually be applied to filename2.
• After the header lines, the diff will indicate which line numbers in filename1 (the source) are to be examined, what should be changed or deleted, what the resulting line numbers in filename2 (the destination) are, and what should be changed or added:
  • A '-' in the first column of the source part of the patch indicates a line deletion.
  • A '+' in the first column of the destination part of the patch indicates a line addition.
  • A set of '!'s in the first column in both the source and the destination indicate a line-group replacement; a group of consecutive lines in the source are replaced with a corresponding group of lines in the destination.

Making patches with diff -c or rcsdiff

    diff -c player.c.orig player.c > patchfile

If there's more than one source file changed, you can do this:

    diff -c player.c.orig player.c > patchfile
    diff -c game.c.orig game.c >> patchfile

    rcsdiff -c player.c > patchfile
    rcsdiff -c game.c >> patchfile

#ifdef and #define

/* If defined, the NOMAIL flag (a toggle on players) will be in the game,
 * which prevents players from using @mail commands.
 */
#define NOMAIL_FLAG

How-to

Add flags

The other 4 sets of "flags" are called toggles, and each set can only be used with one of the types of object.

There are a limited number of flags/toggles which can be created in each set, because internally, flags are represented as bits in a 32-bit integer. Thirty-two bits means 32 possible flags in each set. Flag space is scarce for generic flags, since most of the MUSH flags are of this type. There's plenty of room to add new toggles, however, and in general, if your new flag idea only applies to a single kind of object, you should add it as a toggle.

As an example, we'll add a (silly) toggle for players called "NOMAIL" (letter 'i') which prevents them from using the @mail commands.

Adding a flag is a 3-step process. First, you must edit flags.h and #define a name and bit pattern for the flags. You should be able to follow the way it's already done in the file. One hint is to try to use bit patterns from the highest possible (0x80000000) and work downward, since new flags added by Amberyl work their way up, and upgrading to a future patchlevel will be more difficult if your flags overlap new ones. If you're adding a toggle, you don't need to start all that high, since it's unlikely that large numbers of toggles will be added to future releases, but better safe than sorry.

In our example, we add these lines:

#ifdef NOMAIL_FLAG
#define PLAYER_NOMAIL   0x80000000
#endif

#ifdef NOMAIL_FLAG
    { "NOMAIL", 'i', TYPE_PLAYER, PLAYER_NOMAIL, F_WIZARD },
#endif

NOTE: In post-pl10 releases, flags have separate permissions for who can turn them on and off. This flag would be written like this in those releases:

#ifdef NOMAIL_FLAG
    { "NOMAIL", 'i', TYPE_PLAYER, PLAYER_NOMAIL, F_WIZARD, F_WIZARD },
#endif

F_ANY

anybody can set this on something they control

F_OWNED

you must own the object to set this

F_INHERIT

only inherit objects can set this on things they control

F_ROYAL

royalty/wizards can set this on things they control - note that royalty typically don't control anything more than normal players!

F_WIZARD

wizards can set this on things they control, which is basically everything

F_GOD

only God (#1) can set this

F_INTERNAL

nobody can set this - it's used internally by the game - used for flags like MARKED

F_DARK (post-pl10)

Only God can see if this flag is set or not.

F_MDARK (post-pl10)

Only admin can see if this flag is set or not.

F_ODARK (post-pl10)

Only admin and the owner of the object can see if this flag is set or not.

While you're in flags.c, also edit the flag alias table further down, which indicates what partial names and aliases can be used to refer to a flag when @set'ing it. You might add entries that look like this:

#ifdef NOMAIL_FLAG
    { "NO_MAIL", "NOMAIL" },
    { "NOMAI",   "NOMAIL" },
    { "NOMA",    "NOMAIL" },
    { "NOM",     "NOMAIL" },
#endif

Finally, you need to figure out what (if anything) your flag is supposed to affect in the code, and add in code that checks for the presence of the flag. For example, we could check in game.c when someone tries to use an @mail command. A common way to handle this is to edit dbdefs.h and define a macro like:

#ifdef NOMAIL_FLAG
#define NoMail(x)	(IS(x,TYPE_PLAYER,PLAYER_NOMAIL))
#endif

When you're defining macros for toggles, define them using the IS() macro above. When you're defining macros for generic flags, you can define them as (Flags(x) & FLAGNAME). For example, the definition of Visual(x) is:

#define Visual(x)	(Flags(x) & VISUAL)

Add powers

In flags.h, you can define the power's bit pattern, just as you would with a flag (the powers are at the end of the file.) The same guidelines apply, except that powers are always generic and can always only be granted by Wizards.

In look.c, you must define how the power is displayed when someone examines the player, in the function powers_description. Find it, and the addition you'll need to make is obvious.

In wiz.c, you'll need to modify the function find_power, which looks up a power's bit pattern, given its name. Again, it's obvious.

And, as with flags, you can now define a macro so you can test for your power. For powers, however, this is done in db.h. For example, the login power's macro looks like this:

#define Can_Login(x)	(Hasprivs(x) || (Powers(x) & LOGIN_ANYTIME))

Add chat channels

Edit the file, and go to the last function. You'll see a list of all the currently defined chat channels. Just follow along and add yours. For example:

   add_channel("Theme", CHP_PUBLIC, 0, 0x100000);

The allowable privileges are:

CHP_PUBLIC

Public channel which anyone may join

CHP_ADMIN

Only admin (royalty/wizards) may use this channel

CHP_WIZARD

Only wizards may use this channel

CHP_FORBID

No one may use this channel - a flag used internally when you delete a channel.

CHP_OBJECT (post-pl10)

If you've got OBJECT_CHAT turned on, only non-player objects and wizards may join this channel. Can be used for radios and the like.

Add attributes

In atr_tab.h, you'll find the attribute table. Entries look like this:

  { (char *) "ACLONE",  AF_ODARK | AF_NOPROG,           NULL,   0 },

The allowable attribute flags are defined in attrib.h to be:

AF_ODARK

Only the owner (of the object or attribute) can see the attribute. If you don't include this attribute flag, the attribute will be a public one, like SEX and DESCRIBE.

AF_MDARK

Only a Wizard can see the attribute, it's invisible to mortals.

AF_DARK

No one can see the attribute, ever. Used mostly for internally used attributes like XYXXY (the player's encrypted password).

AF_LOCKED

Only the creator of the attribute can change it. This is the flag set with @atrlock.

AF_WIZARD

Only a Wizard can change the attribute.

AF_NOPROG

The attribute won't be searched for $commands.

AF_NOCOPY

The attribute won't be copied when the object is @clone'd.

AF_PRIVATE

The attribute won't be inherited if the object is used as an @parent.

AF_NUKED

The attribute is marked to be deleted. This is an internal flag that you never want to set on an attribute you're defining.

	{ "ACLON", "ACLONE" },
	{ "ACLO",  "ACLONE" },
	{ "ACL",   "ACL" },

ATTR *atr_match(char *name)

Given an uppercase attribute name, looks up a standard (i.e. defined in atr_tab.h or atr_tab.c) attribute and returns a pointer to the attribute as defined in atr_tab.h, with the flags, value, and owner as defined in atr_tab.h.

ATTR *atr_get(dbref obj, char *name)

Given an object's db# (an integer) and an attribute name, return a pointer to that attribute on that object or its parent(s). If that attribute isn't set on the object or parent(s), the function returns NULL.

ATTR *atr_get_noparent(dbref obj, char *name)

Just like atr_get, but doesn't check parents.

int atr_add(dbref obj, char *name, char *value, dbref enactor, int flags)

This is the basic function for setting attributes. Given an object, an attribute name, a value for the attribute (or NULL to clear the attribute), the db# of the thing trying to do the setting (for control checks), and the attribute flags to set on the attribute, it tries to set the attribute and returns -1 if unable to, 1 if an attribute is set, and 0 if the attribute is cleared. If you want to be sure that the attribute is set, pass GOD as the enactor. If you don't want to set any attribute flags, pass NOTHING as the flags.

#ifdef EXTENDED_MAIL
    (void) atr_add(player, "MAILCURF", "0", GOD,
		   AF_LOCKED|AF_NOPROG|AF_WIZARD|AF_ODARK);
#endif

Looking through the code for do_edit (and other code in set.c) can be very educational in learning to work with attributes.

Add locks

Adding lock types is more similar to adding a new flag or attribute than a new function or command. As an example, we'll add a Look lock that controls who can look at you.

First, edit lock.h to add a declaration of your new lock type. Go down to where it says '/* Declare new lock types here */'. Add a declaration for your new lock type like this:

extern const lock_type Look_Lock.

const lock_type Look_Lock = "Look";

That's all you need to do to define a new type of lock. @lock, examine, and so forth will all work correctly with the new lock. In most cases, though, you'll want to define the effects of the lock, too.

The function eval_lock() returns the value of a given lock for a given person. For example, to add our Look_Lock, we'll add the following code near the place where it tests for the 'OPAQUE' flag:

	if (!eval_lock(player, thing, Look_Lock)) {
	  notify(player, "You can't look at that.");
        }

Editor's Note: Don't forget to surround code which relies on RALPH_LOCKS with appropriate #ifdef...#endif pairs.

Add functions

The function parser changed between PennMUSH 1.50 and PennMUSH 1.6.x. In PennMUSH 1.50, most functions were defined in eval.c, with the exception of some wizard-only functions which were defined as external functions (XFUNCTIONs) in wiz.c. In 1.6.x, there are no more XFUNCTIONS, and most functions are defined in the fun*.c files (funlist.c, funstr.c, etc.) and sometimes in other files. You should add your own functions to funlocal.c; this file won't be overwritten by future patches or releases, so it's safe to add whatever you like to it.

Defining the function

FUNCTION(fun_<functionname>)
{
  text of the function
}

The FUNCTION macro sets up some standard conventions for coding functions. Your function is expected to return its result in the string buff (which is passed as a pointer, along with (in 1.6.x) bp, a pointer to the pointer). Its arguments are passed in the array of strings args[], and the number of arguments is passed in nargs. Finally, some dbrefs are passed. In 1.50 these are: privs, the dbref of the object executing the command (aka %! in MUSHcode), and doer, the dbref of the object which enacted the command, the object which triggered privs (aka %# in MUSHcode). In 1.6.x, there are 3 dbrefs: executor is the dbref of the object executing the command (%!, like privs); enactor is the dbref of the enacting object (%#, like doer); and caller is the dbref of the last object to do a ufun call (aka %@ in MUSH code).

Function arguments in 1.50