Table of Contents

   Introduction

   Building from Source

   Setup

   Setup as a System Service

   Running a basic server

   Usage and configuration

   Copyright notices

Introduction

   Welcome to cyphesis, at the time of writing the only fully armed and
   operational WorldForge server. Cyphesis is a small scale or personal
   server for WorldForge games, and is currently being used to develop new
   techniques and technologies for the WorldForge project. Code from cyphesis
   will also be used to control NPCs in future servers such as STAGE using AI
   techniques.

   --------------------------------------------------------------------------

Building from Source

   cyphesis is built using autoconf. Please see the file INSTALL for details.
   It requires Python and PostgreSQL which are included with most Linux
   distributions, and Atlas-C++, varconf, Mercator, wfmath and skstream2
   which are provided by the WorldForge project. GNU readline is required by
   some of the included tools.

   If built from source the software and data must be installed using "make
   install" before it will be ready. Go to the Section called Setup for
   information on the setup steps required after installation.

   --------------------------------------------------------------------------

Setup

   The software requires some post-installation configuration before it will
   run correctly. If you plan to run a server using the System V init
   services as provided by the cyphesis rpm then most of this configuration
   is handled for you automatically. If this is the case please see the
   Section called Setup as a System Service for more information.

   The first step is to setup the database access. The database is required
   to store account and rule information. If full server persistence is
   enabled, the database is also used to store the entire world state. A
   postgresql server must be running on the system where you plan to run
   cyphesis, and the user who will run cyphesis must have access to the
   database. If you do not have root access on the system you will need to
   contact the system administrator to request a database account. By default
   cyphesis assumes that access to a PostgreSQL RDBMS running on the same
   machine from a user account with the same name as the database account
   does not require a password. If this is not the case you can either
   configure the PostgreSQL RDBMS to work this way, or specify a password in
   the config file.

   Once database access has been granted you must run cyloadrules to load the
   default rulesets into the database. For more information on how
   cyloadrules works, including advanced usage see the Section called
   Usage and configuration.

   The server is now ready to run. For for more information on how to start
   the server see the Section called Usage and configuration.

   --------------------------------------------------------------------------

Setup as a System Service

   Running cyphesis as a service is the simplest way to get the server up and
   running. If you are using rpm packages, the cyphesis rpm handles creating
   a user account so that cyphesis does not run as the superuser. In order to
   run the server correctly, the cyphesis service must be started, followed
   by the cyclient service. This can be handled by configuring the system to
   start these services at boot time, or by running the init scripts manually
   as root as follows:

   # /etc/init.d/cyphesis start
   # /etc/init.d/cyclient start


   The postgresql service is required and must be started before cyphesis.
   The first time the cyphesis service is run, the init script will ensure
   that cyphesis has access to the database, and will preload the database
   with the neccessary data automatically.

   If you are not using the packaged version of cyphesis, but wish to run it
   as a system service, the init scripts are included in the top directory of
   the source package and are called cyphesis.init and cyclient.init. Both of
   these files should be installed in the init script directory on your
   system, usually /etc/rc.d/init.d/. The procedure for enabling system
   services varies from system to system. One command used for controlling
   services is the chkconfig command, found on most Linux systems, and some
   Unix variants. Once installed the scripts can be activated as follows:

   # chkconfig --add cyphesis
   # chkconfig --add cyclient


   The services are then enabled as follows:

   # chkconfig cyphesis on
   # chkconfig cyclient on


   For further details please see the chkconfig documentation. By default the
   cyphesis init scripts attempt to run the server and client as a user
   called cyphesis. An account with this username will need to be created
   before the service will work. The file called cyphesis.sysconfig can
   optionally be installed as /etc/sysconfig/cyphesis and edited to control
   the username used to run the cyphesis server and client processes.

   When cyphesis has been run as a system service, any error message or other
   information are sent to the syslog. On most Linux systems this means that
   you can see these message by looking at /var/log/messages. Please see the
   syslog documentation for information about how to control these log
   messages.

   --------------------------------------------------------------------------

Running a basic server

   Before you run the server for the first time, run the cyloadrules to
   prepare the database tables. The command should print out some message
   indicating the number of rules loaded. You will not need to run this
   command again unless you upgrade to a newer version of the rules or of
   cyphesis.

   Start the server with the cyphesis command. It will output some startup
   messages and then run in the foreground. If you want to run the server in
   the background, start the server with the option --cyphesis:daemon=true .

   Each time the server is run it needs to be populated with game data before
   it does anything useful. If you are running the server using the System V
   init service then this is handled for you by the cyclient service. If you
   are running the server manually you will need to run cyclient yourself. In
   a separate terminal run the cyclient command, which will populate the
   server, outputting messages as it does this. Once it has completed
   cyclient will exit, and the server will be ready. The server will
   automatically register its presence with the metaserver so you will not
   need to advertise it.

   If you everything has worked so far, and you are not planning to do any
   server or world development at this time then you do not need to read any
   of the rest of these instructions.

   --------------------------------------------------------------------------

Usage and configuration

   The main server binary is called cyphesis. Its command line arguments and
   configuration are managed by varconf, which means options can be set in
   configuration files and on the command line. The main configuration file
   is called cyphesis.vconf, and server settings are stored in the [cyphesis]
   section. The file can be found in the cyphesis source directory, and is
   installed into the sysconf directory, which is by default /etc. Settings
   in this configuration file can be overridden in on the command line, and
   once overridden they will be stored permanently in .cyphesis.vconf in the
   users home directory. In order to drop back to the default settings,
   remove this file. Settings can be incrementally overridden in
   ~/.cyphesis.vconf non-interactively by passing them as command line
   options to cyconf. cyconf will store any settings it is given in
   ~/.cyphesis.vconf and then exited. If you are planning to have multiple
   servers run on the same system at the same or different times, the easiest
   way to handle the differences in configuration would be to use the
   ~/.cyphesis.vconf file, and avoid modifying the master configuration file.

   As an example, the ruleset to be used is set in cyphesis.vconf as follows:

       [cyphesis]
       ruleset="deeds"

   This setting can be overridden by invoking cyphesis with the following
   option:

       --cyphesis:ruleset=werewolf

   For more details of varconf usage see the Varconf documentation. For full
   details on configuraton options for cyphesis, see the cyphesis(1) man
   page.

   The ruleset specified indicates the entity types available, the set of
   scripts that will be used for these entities, and the initialisation
   script used to populate the server.

   The server is populated using the client program, cyclient. cyclient
   should be run once the server has been started, and it will display a
   report of the world it is setting up, and then exit.

   The default ruleset for this version is Mason, but an additional
   development ruleset is provided for Werewolf, but will probably only be
   useful as a reference. To switch to the Werewolf ruleset, follow the
   instructions above.

   Before you start the server for the first time, you will need to load some
   data into the server's database tables. You will first have to load
   ruleset data into the database. If this is the first time you have run
   cyphesis, you will need to set it up so cyphesis has access. In order to
   use databases, cyphesis needs to know the name of an account it can use,
   and the name of a database where it can create its tables. By default it
   uses the current user name to connect to PostgreSQL, and the name cyphesis
   for the database. It has been assumed that PostgreSQL has been set up as
   it is on most systems to accept a local connection from a user with the
   same name as the database account name without a password. If you want to
   go through the setup of the database manually, or for some reason
   cyphesis-setup does not work, you will need to create a database account
   with the right name, and a database belonging to that account called
   cyphesis, or whatever name you choose to call it. For information on how
   to do this, please see the PostgreSQL documentation provided with the
   version you have installed.

   Once cyphesis has access to the database, run cypasswd with no arguments
   to set the admin password to something unique.

   A ruleset will need to be loaded into the database before you can do
   anything useful with the server. Each ruleset optionally depends on
   another ruleset, so in addition to the ruleset you are using you will need
   to load the rulesets on which it depends. A ruleset is distributed with
   cyphesis as an atlas xml file. The default is mason.xml, which depends on
   acorn.xml, which in turn depends on basic.xml. These three rulesets can be
   loaded into the database using the cyloadrules command with no arguments
   as follows:

       $ cyloadrules
       Reading rules from mason
       49 classes stored in rule database.
       Reading rules from basic
       29 classes stored in rule database.
       $

   This automatically loads the rulesets in order into the database, first
   ensuring that the rules table is empty.

   cyloadrules can also be used to load individual rulesets into the database
   as follows:

       $ cyloadrules mason.xml
       49 classes stored in rule database.
       $ cyloadrules basic.xml
       29 classes stored in rule database.
       $

   You will only need to do this if you are developing new rulesets, or
   customising existing ones.

   The database store is persistent. If new a ruleset is provided, it will be
   necessary to clear the database tables before loading them with new data.

   Once cyphesis is running, it will need to be populated with a map. In
   order to set up a game, you need to run a client to set up the map. The
   client will use a script included in the current ruleset to define what
   the world should contain. This script is kept together with the entity and
   AI scripts required for the ruleset in a directory under the rulesets
   directory. For example, the Mason script is found in
   rulesets/mason/define_world.py. In order to populate the world, simply run
   cyclient once the server is running. You will need to do this each time
   cyphesis is started.

   --------------------------------------------------------------------------

Copyright notices

   The server code in C++ is distributed under the GNU General Public
   License. See the file COPYING for details. The script files included with
   this distribution are also distributed under the GNU General Public
   License. Note that this copyright does not cover user scripts that use
   server services but do not use code from the scripts provided. Using such
   scripts is considered ordinary use of the server, and does not fall under
   the heading of derived work.

   Under the terms of the GNU General Public License version 2, you are
   entitled to modify the software, and are required to make the source code
   to those changes available if you redistribute the modified version.
   Specifically, you are not required to make the source code available if
   the modified version is not redistributed. As the author of the
   cyphesis-C++ core, I believe in your freedom to do what you want with the
   software, and I do not believe I have any right to force you to publish
   any changes if you do not wish to redistribute the modified program. There
   has been some discussion within the Free Software movement about this
   issue, which some see as a hole in the GPL, and it is possible that a
   future version of the GNU General Public License will forbid using a
   modified version of a GPL licensed program to run a service unless the
   changes to the source code are made available. The licensing of many
   programs permit redistribution under the terms of the GNU General Public
   License version 2 or at the licensee's option, a later version, so it is
   possible that a version of those programs may be released that is under
   the terms of a license which requires the source code changes to be
   published for a modified version being used to run an on-line service. As
   the current author and owner of the source code to this program, I have
   never intended that this restriction be placed on the software, and do not
   support its enforcement. I have therefor chosen to restrict redistribution
   of this program to the license provided with the source, which at the time
   of writing is the GPL version 2. If a new version of the GPL is released,
   I will consider on its merits whether or not to make this code available
   under that license. The scripts provided with this software should be
   considered a separate work, as they were not written by me. Nothing in
   this paragraph should be considered to be a legal statement of any kind.
   It is simply a clarification of my opinion on some of the terms of the GNU
   General Public License. If anything in the above paragraph is unclear,
   please feel free to contact me to discuss it.

   Al Riddoch <[email protected]> 2nd April 2002