Genesis Administrators Guide

Genesis was initially created as ColdMUD by Greg Hudson, and was later engineered by other individuals, being finalized by Brandon Gillespie.

Introduction

Genesis consists of the programs coldcc, genesis and control. coldcc is used to compile/decompile the database between textual and binary forms. It is also used for external binary database manupulation (such as adding objects, fixing methods, etc). genesis is the run-time interpreter of a binary database. control is not used at the moment.

Several variables are common to all programs:

Base Directory

The base directory is where programs will start to look for files and other directories. This is commonly named world, although it's name is irrelevant as long as the programs know what it is. Unless you explicitly tell a program what the base directory is, it will assume the base directory is the current directory (i.e. the directory you are in when you execute the program).

Binary Database Directory

The binary database directory is where the database files are located, do not specify a directory already used by other files as this directory! When the binary database is compiled coldcc will unlink and destroy any existing files, in an existing binary directory, or it will create it if it does not exist. This entire directory is also copied when a backup is performed (with the ColdC function backup()).

If unspecified, the binary database directory will be binary in the base directory.

Logfile Directory

If the program logs information, it will attempt to open it's logfile in the Logfile Directory. If unspecifiedk, the logfile directory will be logs in the base directory. The logfile directory will not be created if it does not exist. When programs start logfiles are opened for appending, any log information will remain with the new log information appended to the end.

DB Root File Directory

If the programs were compiled with RESTRICTIVE_FILES enabled, files may only be read and written to within the database root file directory. Unless otherwise specified this directory will be root in the base directory.

DB Executable Directory

The database executable directory is for programs to be executed from ColdC with the execute() function. Unless otherwise specified this directory will be dbbin in the base directory.

Database Versions

It is important to remember that a binary database may ONLY be interpreted with the same executable that created it. Because the byte codes can change from compile to compile (adding/removing modules can change these), the binary database will be different. It is important to remember this when upgrading or adding/removing modules to a database. Always decompile a database to text first, then recompile the database with the new coldcc.

Compiling/Decompiling a database

The simplest way to compile a text database is to enter the base directory and run coldcc, specifying the textdump to read. If the textdump is named textdump you do not need any additional arguments, as this is what coldcc expects. Otherwise use the -t name flag (where name is the name of the textdump). For instance, if your text database was minimal.db you would type:

coldcc -t minimal.db

The simplest way to decompile a binary database is to enter the base directory and run coldcc with the argument flag -d. It will decompile the binary database in the directory binary. If you have a different binary directory name you can specify it with the flag -b name. The text database will be named textdump, unless you use the flag -t name.

Running the driver

The simplest way to run the driver on a binary database is to enter the base directory and run genesis. genesis will automatically fork off and run in the background (if you do not want it to fork off, run it with the flag -f). If the logfile directory exists logged information will be printed to the following files in the logfile directory:

db.log
driver.log
genesis.pid

db.log is the logfile for the database. Information is written to this file with the ColdC function log(). driver.log is used by the driver for messages which are not related to the run-time environment (such as reporting a signal). genesis.pid contains the process id for the currently running driver. This can be used to shutdown a server.

Shutting down the server

The server can be shutdown two ways. Either by calling the ColdC function shutdown(), or by sending a signal to the driver process.

Signals

Genesis catch and handle several signals. Signals can be sent to a process in unix with the command kill. When a signal is caught by genesis the method signal is called on the system object. If a database wishes to perform an action when a signal is caught it may by hooking into this method.

The following signals are caught by genesis, handled as specified, then sent to the database by calling the signal method on the system object:

HUP

Sending this signal will flush all connection and file buffers, and will push the interpreter into non-atomic mode, if it is running atomically.

FPE

FPE signal is converted to an ~fpe error for the task which caused it. No message is sent to the database for this signal.

USR1

This causes the driver to cancel all tasks (currently running, preempted and suspended) and return to execution as normal. This is not normally suggested, as it can throw off a database's normal execution situation. However, it is useful when a task has run out of control and is consuming resources.

USR2

genesis does nothing with this signal.

KILL

If this signal is caught genesis will panic and shutdown. No message is sent to the database for this signal.

CHLD

PIPE

These signals are used for internal processing, and are not sent to the database.

QUIT

The system will attempt to shutdown, currently running processes will continue to completion, and a message is sent to the database.

INT

TERM

The first time any of these signals are received all tasks are aborted (suspeded or otherwise), and the system attempts to shutdown. If these signals are received again the driver will panic. No message is sent to the database for these signals.

kill -SIGNAL `cat logs/genesis.pid`

Using a Binary Database

You will want to be VERY careful not to run from a corrupt binary database. It is possible to work around the locks on a binary database which tell genesis and coldcc its status. Do not do this! If genesis reports the binary database as being corrupt, it is! Many people have found that genesis will run from a corrupt db, if you diddle with some files. However, this is not a stable base to build upon, as the moment genesis reaches corrupt data in the database everything will crash, possibly corrupting even more data. The suggested course of action when you have a corrupt binary database is to simply run from a backup. If you do not have a backup then attempt to decompile the corrupt database with coldcc.

NFS

Running the binary database from an NFS disk is NOT SUGGESTED. You will run into lag problems if you do this, even more notably when a backup is running. If possible some lag can be alleviated by soft linking 'binary.bak' to a local drive, for backups (such as /tmp/binary.bak). Overall this is simply not suggested.

Backups

You can expect the backup to take approximately one second for every megabyte in your binary database (it will be faster or slower depending upon your computer and the speed of your disk). Most of this is asyncrynous-- you are still running while it is backing up. There will be a slight pause of all tasks in the server when the backup is initialized. The length of this pause will depend upon how large your cache is, and how many active objects are in memory. In general this pause will be around one second as the cache is cleaned. It has been tested on a large cache of 40x50 (2000 objects in cache) with many active objects. The initial pause takes about three seconds with this configuration.