cyphesis/README.sgml

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
]>
<article>
  <articleinfo>
    <date>2004-09-16</date>
  </articleinfo>
  <sect1 id="introduction-section">
    <title>Introduction</title>
    <para>
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.
    </para>
  </sect1>

  <sect1 id="building-section">
    <title>Building from Source</title>
    <para>
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.
    </para>

    <para>
If built from source the software and data must be installed using
"make install" before it will be ready. Go to <xref linkend="setup-section">
for information on the setup steps required after installation.
    </para>
  </sect1>

  <sect1 id="setup-section">
    <title>Setup</title>
    <para>
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
<xref linkend="service-section"> for more information.
    </para>

    <para>

    </para>

    <para>
The first step to consider is database access. The database cat be used
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.
    </para>

    <para>
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 <xref linkend="usage-section">.
    </para>

    <para>
The server is now ready to run. For for more information on how to start the
server see <xref linkend="usage-section">.
    </para>
  </sect1>

  <sect1 id="service-section">
    <title>Setup as a System Service</title>
    <para>
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:
    </para>
    <programlisting>
# /etc/init.d/cyphesis start
# /etc/init.d/cyclient start
    </programlisting>
    <para>
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. 
    </para>
    <para>
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 <filename>/etc/rc.d/init.d/</filename>. The procedure
for enabling system services varies from system to system. One command
used for controlling services is the <command>chkconfig</command> command,
found on most Linux systems, and some Unix variants. Once installed the scripts
can be activated as follows:
    </para>
    <programlisting>
# chkconfig --add cyphesis
# chkconfig --add cyclient
    </programlisting>
    <para>
The services are then enabled as follows:
    </para>
    <programlisting>
# chkconfig cyphesis on
# chkconfig cyclient on
    </programlisting>
    <para>
For further details please see the <command>chkconfig</command> 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
<filename>cyphesis.sysconfig</filename> can optionally be installed as
<filename>/etc/sysconfig/cyphesis</filename> and edited to control the username
used to run the cyphesis server and client processes.
    </para>
    <para>
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 <filename>/var/log/messages</filename>.
Please see the syslog documentation for information about how to control
these log messages.
    </para>
  </sect1>

  <sect1 id="running-section">
    <title>Running a basic server</title>
    <para>
Before you run the server for the first time, run the
<command>cyloadrules</command> 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.
    </para>
    <para>
Start the server with the <command>cyphesis</command> 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 .
    </para>

    <para>
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 <command>cyclient</command>
yourself.  In a separate terminal run the <command>cyclient</command> 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.
    </para>

    <para>
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.
    </para>
  </sect1>

  <sect1 id="usage-section">
    <title>Usage and configuration</title>
    <para>
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 <command>cyconf</command>. cyconf
will store any settings it is given in <filename>~/.cyphesis.vconf</filename>
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
<filename>~/.cyphesis.vconf</filename> file, and avoid modifying the master
configuration file.
    </para>

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

<programlisting role="C">
    [cyphesis]
    ruleset="mason"
</programlisting>

    <para>
This setting can be overridden by invoking cyphesis with the following
option:
    </para>

<programlisting role="C">
    --cyphesis:ruleset=werewolf
</programlisting>

    <para>
For more details of varconf usage see the Varconf documentation. For full
details on configuraton options for cyphesis, see the
<citerefentry>
  <refentrytitle>cyphesis</refentrytitle>
  <manvolnum>1</manvolnum>
</citerefentry> man page.
    </para>

    <para>
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.
    </para>

    <para>
The server is populated using the client program, <command>cyclient</command>.
<command>cyclient</command> 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.
    </para>

    <para>
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.
    </para>

    <para>
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.
    </para>

    <para>
Once cyphesis has access to the database, run <command>cypasswd</command> with
no arguments to set the admin password to something unique.
    </para>

    <para>
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
<command>cyloadrules</command> command with no arguments as follows:
    </para>

<programlisting role="C">
    $ cyloadrules
    Reading rules from mason
    49 classes stored in rule database.
    Reading rules from basic
    29 classes stored in rule database.
    $
</programlisting>

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

    <para>
cyloadrules can also be used to load individual rulesets into the database as
follows:
    </para>

<programlisting role="C">
    $ cyloadrules mason.xml
    49 classes stored in rule database.
    $ cyloadrules basic.xml
    29 classes stored in rule database.
    $
</programlisting>

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

    <para>
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.
    </para>

    <para>
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 <command>cyclient</command> once the server is running. You will need to do
this each time cyphesis is started.
    </para>
  </sect1>

  <sect1 id="copright-section">
    <title>Copyright notices</title>
    <para>
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.
    </para>

    <para>
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.
    </para>

    <para>
  Al Riddoch &lt;alriddoch@zepler.org&gt; 2nd April 2002
    </para>
  </sect1>
</article>